diff --git a/content/docs/faq/README.md b/content/docs/faq/README.md index 6e3dd7b2407..3f71a00e95c 100644 --- a/content/docs/faq/README.md +++ b/content/docs/faq/README.md @@ -85,6 +85,25 @@ root before the connection is started. If the client already has the root, there The same logic with not sending root certificates applies for servers trying to validate client certificates; the [same justification](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.6) is given in the TLS RFC. + +### Why isn't my certificate's chain in my issued Secret's `ca.crt`? + +Users frequently ask us about changing `ca.crt` to include more certs or different certs. We tend to push back on these requests +for the simple reason that we believe `ca.crt` to most often be a risk for any user. + +`ca.crt` is filled by cert-manager with a "best guess" of what the issuing CA was. Importantly, cert-manager can often only guess; +if the issuer doesn't provide the full chain including the root certificate, there might be no way for cert-manager to know what the +root of the chain is. In that case, cert-manager will make a best-effort attempt to use the issuer deepest in the chain. + +That "best effort" attempt is one of the reasons that `ca.crt` can be risky; it might not be correct, and it might change when the issuer +changes even if nothing in cert-manager changes. + +The other issue with `ca.crt` is fundamental - it's updated when the certificate is updated. Some users can be tempted to use `ca.crt` +for trust purposes, but rotating trusted certificates safely relies on being able to have both the old and new CA certificates trusted at the same time. + +By consuming the CA directly from your Secret, it becomes impossible to do this; `ca.crt` will only ever contain the best effort guess +for the CA for the current certificate, and will never include an older or a new CA. + ### How can I see all the historic events related to a certificate object? cert-manager publishes all events to the Kubernetes events mechanism, you can get the events for your specific resources using `kubectl describe `. diff --git a/content/docs/trust/README.md b/content/docs/trust/README.md index f8c86c1d405..13a66783077 100644 --- a/content/docs/trust/README.md +++ b/content/docs/trust/README.md @@ -13,14 +13,13 @@ This is because: 1. That `Secret` also contains the private key of the server, which should only be accessible to the server. You should use RBAC to ensure that the `Secret` containing the serving certificate and private key are only accessible to Pods that need it. -2. Rotating CA certificates safely relies on being able to have both the old and new CA certificates trusted at the same time. - By consuming the CA directly from the source, this isn't possible; - you'll be _forced_ to have some down-time in order to rotate certificates. +2. Rotating CA certificates safely relies on being able to have both the old and new CA certificates trusted at the same time. See [the FAQ](../faq/README.md#chain-cacrt) for more details. When configuring the client you should independently choose and fetch the CA certificates that you want to trust. Download the CA out of band and store it in a `Secret` or `ConfigMap` separate from the `Secret` containing the server's private key and certificate. + [trust-manager](trust-manager) can be used to manage these certificates and automatically distribute them to multiple namespaces. This ensures that if the material in the `Secret` containing the server key and certificate is tampered with,