diff --git a/content/docs/configuration/ca.md b/content/docs/configuration/ca.md index c2a21a34f4..21efc898a6 100644 --- a/content/docs/configuration/ca.md +++ b/content/docs/configuration/ca.md @@ -3,12 +3,16 @@ title: CA description: 'cert-manager configuration: CA Issuers' --- -⚠️ CA issuers are generally either for trying cert-manager out or else for advanced users with -a good idea of how to run a PKI. To be used safely in production, CA issuers introduce complex +
+⚠️ CA issuers are generally for cert-manager demos or for advanced users with experience +and tooling for running a PKI. To be used safely in production, CA issuers introduce complex planning requirements around rotation, trust store distribution and disaster recovery. If you're not planning to run your own PKI, use a different issuer type. +Otherwise, be sure to read the [Important Information](#important-information) below. +
+ The CA issuer represents a Certificate Authority whose certificate and private key are stored inside the cluster as a Kubernetes `Secret`. @@ -92,3 +96,27 @@ ca-issuer True Signing CA verified 2m Certificates are now ready to be requested by using the CA `Issuer` named `ca-issuer` within the `sandbox` namespace. + +## Important Information + +The CA issuer is lightweight and is intended for experienced cluster operators who understand +PKI and the need for planning around certificate rotation. + +You should bear the following in mind: + +- There's no automatic rotation for the CA certificate in the `Secret` you configured + - If running a long-lived CA issuer, you need a plan for rotating the CA certificate + - You should have tracking in place to warn you when the CA cert is nearing expiry +- CA issuers will issue leaf certificates which outlive the CA + - There is no check performed on the duration of the leaf relative to the duration of the CA + - You'll need to track the expiry of _all_ certificates in the chain +- Updating the secret used for the CA certificate won't trigger re-issuance of leaf certificates + - If your CA was near expiry and your leaf certs weren't, you might need to manually trigger re-issuance of the leaf certs + - `cmctl renew` may be helpful for this (see the [docs](../reference/cmctl.md#renew) for `cmctl`) +- CA issuers don't validate that the CA you configure is a "valid" CA + - At a minimum, CA certs should have the basic constraints extension present with `isCA` set to true + - Most likely, you'll also need to set `certificate sign` on the key usages + - For generating a cert with cert-manager, see the [bootstrapping example](./selfsigned.md#bootstrapping-ca-issuers) + - cert-manager will automatically add the correct key usages if `isCA` is set to true + - It will accept a server certificate with `isCA: false` for example + - Leaf certs "issued" by such a "CA" will fail to validate in most situations