diff --git a/docs/backups-restore-to-new-cluster.md b/docs/backups-restore-to-new-cluster.md index 04aa7eb..72d34b0 100644 --- a/docs/backups-restore-to-new-cluster.md +++ b/docs/backups-restore-to-new-cluster.md @@ -71,7 +71,7 @@ Configure the `PerconaXtraDBClusterRestore` Custom Resource. Specify the followi and the backup name. * the necessary [storage configuration keys](backups-storage.md#configure-storage-for-backups), just like in the `deploy/cr.yaml` file of the source cluster. * `verifyTLS` to verify the storage server TLS certificate - * the custom TLS configuration if you use it for backups. Refer to the [backups-storage.md#configure-tls-verification-with-custom-certificates-for-s3-storage] section for more information. + * the custom TLS configuration if you use it for backups. Refer to the [Configure TLS verification with custom certificates for S3 storage](backups-storage.md#configure-tls-verification-with-custom-certificates-for-s3-storage) section for more information. ```yaml ... diff --git a/docs/backups-storage.md b/docs/backups-storage.md index 314476d..7687890 100644 --- a/docs/backups-storage.md +++ b/docs/backups-storage.md @@ -81,6 +81,9 @@ Before configuring the storage, you need to create a [Kubernetes Secret :octicon bucket: S3-BACKUP-BUCKET-NAME-HERE region: us-west-2 credentialsSecret: my-cluster-name-backup-s3 + caBundle: + name: minio-ca-bundle + key: tls.cert ... ``` @@ -102,11 +105,11 @@ Before configuring the storage, you need to create a [Kubernetes Secret :octicon To configure TLS verification with custom certificates, do the following: - 1. Create the Secret object that contains the CA certificate used for authentication to S3 storage + 1. Create the Secret object that contains the TLS certificate to access the S3 storage, the certificate's private key and the CA certificate. 2. Modify the S3 storage configuration in the Custom Resource and specify the following information: * `storages..s3.caBundle.name` is the name of the Secret object you created previously - * `storages..s3.caBundle.key` is the CA certificate to use. + * `storages..s3.caBundle.key` is the CA certificate. Here's the example configuration: diff --git a/docs/operator.md b/docs/operator.md index a8b71d8..2d5c958 100644 --- a/docs/operator.md +++ b/docs/operator.md @@ -239,6 +239,22 @@ Enables or disables the [TLS encryption](TLS.md). If set to `false`, | ----------- | ---------- | | :material-toggle-switch-outline: boolean | `true` | +### `tls.certValidityDuration` + +Validity period for TLS certificates. Minimum required validity is 1 hour. Durations lower than 1 hour are rejected. Setting the duration to exactly 1 hour prevents the Operator from generating the correct certificate object. + +| Value type | Example | +| ----------- | ---------- | +| :material-code-string: string | `2160h` | + +### `tls.caValidityDuration` + +Validity period for CA certificate. Minimum accepted duration is 730 hours (approximately 30 days). Setting this value to exactly 730 hours prevents the Operator from generating the correct certificate object. You must set this value greater than 730 hours. + +| Value type | Example | +| ----------- | ---------- | +| :material-code-string: string | `26280h` | + ### `tls.SANs` Additional domains (SAN) to be added to the TLS certificate within the extended cert-manager configuration. @@ -2540,7 +2556,7 @@ The timeout value in seconds, after which backup job will automatically fail. | ----------- | ---------- | | :material-numeric-1-box: int | `3600` | -### backup.startingDeadlineSeconds +### `backup.startingDeadlineSeconds` The maximum time in seconds for a backup to start. The Operator compares the timestamp of the backup object against the current time. If the backup is not started within the set time, the Operator automatically marks it as "failed". @@ -3023,6 +3039,14 @@ configuration file. This Custom Resource contains the following options: | credentialsSecret| string | The Secret name for the backup | true | | endpointUrl | string | A valid endpoint URL | false | | region | string | The region corresponding to the S3 bucket | false | +| caBundle | subdoc | Configuration for custom self-issued TLS certificates | false + +#### backupSource.s3.caBundle subsection + +| Key | Value type | Description | Required | +| ---------------- | ----------------- | ---------------------------------------------- | -------- | +| name | string | The name of the Secret object that stores custom TLS certificates | true | +| key | string | The custom CA certificate file used to sign TLS certificates | true | ### backupSource.azure subsection diff --git a/docs/tls-cert-manager.md b/docs/tls-cert-manager.md index 0cc6eae..0488a92 100644 --- a/docs/tls-cert-manager.md +++ b/docs/tls-cert-manager.md @@ -65,4 +65,48 @@ The steps to install the *cert-manager* are the following: cert-manager-webhook-58f4cff74d-th4pp 1/1 Running 0 65s ``` -Once you create the database with the Operator, it will automatically trigger the cert-manager to create certificates. Whenever you check certificates for expiration, you will find that they are valid and short-term. +At this point, you can move on to [deploying the Operator and your database cluster](kubectl.md). + +## Customize certificate duration for cert-manager + +When you deploy the cluster using the default configuration, the Operator triggers the cert-manager to create certificates +with default duration of 90 days. + +You can also customize the certificate duration. For example, to align certificate lifetimes with your organization’s security and compliance policies. + +### Rules and limitations + +Check the following rules and limitations for setting up the certificate duration: + +1. You can set the duration **only when you create a new cluster**. Updating it in a running cluster is not supported. +2. The TLS certificate duration is subject to the following requirements: + + - The minimum accepted value is 1 hour. Durations below 1 hour are rejected. + - Do **not** set the duration to exactly 1 hour; the Operator will fail to generate the correct certificate object if you do. + - By default, cert-manager starts the renewal process when a certificate has one-third of its lifetime remaining, ensuring renewal before expiration. For example, if a certificate is valid for 1 hour, renewal will begin after approximately 40 minutes. + +3. Minimum CA certificate duration is 730 hours (approximately 30 days). Do not set the duration to exactly 730 hours; the Operator will fail to generate the correct certificate object if you do. + +### Configuration + +To set the custom duration, specify the following options in the Custom Resource: + +* `.spec.tls.certValidityDuration` – validity period for TLS certificates +* `.spec.tls.caValidityDuration` – validity period for the Certificate Authority (CA) + +Here's the example configuration: + +```yaml + tls: + enabled: true + certValidityDuration: 2160h + caValidityDuration: 26280h +``` + +Create a new cluster with this configuration: + +```bash +kubectl -f deploy/cr.yaml -n +``` + +To verify the durations, you can [check certificates for expiration](tls-update.md#check-your-certificates-for-expiration) at any time. This ensures your certificates are valid and helps you plan for renewals before they expire. diff --git a/docs/tls-manual.md b/docs/tls-manual.md index 93301d2..6ca7745 100644 --- a/docs/tls-manual.md +++ b/docs/tls-manual.md @@ -7,7 +7,7 @@ You can generate TLS certificates manually instead of using the Operator's autom When you follow the steps from this guide, you'll generate these certificate files: -* `server.pem` - Server certificate for MongoDB nodes +* `server.pem` - Server certificate for Percona XtraDB Cluster nodes * `server-key.pem` - Private key for the server certificate * `client.pem` - Client certificate for external connections * `client-key.pem` - Private key for the client certificate diff --git a/docs/tls-update.md b/docs/tls-update.md index 51b8a31..90c8b6f 100644 --- a/docs/tls-update.md +++ b/docs/tls-update.md @@ -17,7 +17,7 @@ If you [use cert-manager](tls-cert-manager.md): 1. Check the necessary secrets names (`cluster1-ssl` and `cluster1-ssl-internal` by default): - ``` {.bash data-prompt="$" } + ```bash kubectl get certificate ``` @@ -90,9 +90,9 @@ as follows. and the TLS certificate key (`tls.key.old`): ```bash - kubectl get secret/ps-cluster1-ssl -o jsonpath='{.data.ca\.crt}' | base64 --decode > ca.pem.old - kubectl get secret/ps-cluster1-ssl -o jsonpath='{.data.tls\.crt}' | base64 --decode > tls.pem.old - kubectl get secret/ps-cluster1-ssl -o jsonpath='{.data.tls\.key}' | base64 --decode > tls.key.old + kubectl get secret/cluster1-ssl -o jsonpath='{.data.ca\.crt}' | base64 --decode > ca.pem.old + kubectl get secret/cluster1-ssl -o jsonpath='{.data.tls\.crt}' | base64 --decode > tls.pem.old + kubectl get secret/cluster1-ssl -o jsonpath='{.data.tls\.key}' | base64 --decode > tls.key.old ``` 3. Combine new and current `ca.pem` into a `ca.pem.combined` file: @@ -104,11 +104,11 @@ as follows. 4. Create a new Secrets object with the *old* TLS certificate (`tls.pem.old`) and key (`tls.key.old`), but a *new combined* `ca.pem` (`ca.pem.combined`): ``` bash - kubectl create secret generic ps-cluster1-ssl \ + kubectl create secret generic cluster1-ssl \ --from-file=tls.crt=server.pem.old \ --from-file=tls.key=server-key.pem.old \ --from-file=ca.crt=ca.pem.combined \ - --type=Opague -o yaml --dry-run=client | kubectl apply -f - + --type=kubernetes.io/tls -o yaml --dry-run=client | kubectl apply -f - ``` 5. The cluster will go through a rolling restart. This process will not cause issues, because every node has the old TLS certificate/key, and both new @@ -117,7 +117,7 @@ as follows. 6. Create a new Secrets object again. This time use a new TLS certificate (`server.pem` in the example) and a new TLS key (`server-key.pem`), and again the combined CA certificate (`ca.pem.combined`): ``` bash - kubectl create secret generic ps-cluster1-ssl \ + kubectl create secret generic cluster1-ssl \ --from-file=tls.crt=server.pem \ --from-file=tls.key=server-key.pem \ --from-file=ca.crt=ca.pem.combined \ @@ -133,7 +133,7 @@ as follows. its key (`server-key.pem`), and only the new CA certificate (`ca.pem`): ``` bash - kubectl create secret generic ps-cluster1-ssl \ + kubectl create secret generic cluster1-ssl \ --from-file=tls.crt=server.pem \ --from-file=tls.key=server-key.pem \ --from-file=ca.crt=ca.pem \ diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 279b862..95ef52d 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -167,7 +167,6 @@ not_in_nav: | # Common navigation for percona.com, render.com and PDF nav: - - Welcome: index.md - get-help.md - Features: