Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more warnings about using the CA issuer safely #1603

Merged
merged 2 commits into from
Dec 2, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions content/docs/configuration/ca.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<div className="warning">
⚠️ 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.
</div>

The CA issuer represents a Certificate Authority whose certificate and
private key are stored inside the cluster as a Kubernetes `Secret`.

Expand Down Expand Up @@ -92,3 +96,26 @@ 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 if asked to do so
SgtCoDFish marked this conversation as resolved.
Show resolved Hide resolved
- 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 trigger re-issuance manually
SgtCoDFish marked this conversation as resolved.
Show resolved Hide resolved
- `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