📖 Proposal external CA and cert sign #12739
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,150 @@ | ||
| --- | ||
| title: Fully External CA and external certificate signing in Cluster API | ||
| authors: | ||
| - "@moh2a" | ||
| reviewers: | ||
| - "" | ||
| creation-date: 2025-09-07 | ||
| last-updated: 2025-09-08 | ||
| status: provisional | ||
| --- | ||
|
|
||
| # Title | ||
|
|
||
| Enabling Cluster API to integrate with fully External CA and delegate certificate signing | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| <!-- START doctoc generated TOC please keep comment here to allow auto update --> | ||
| <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> | ||
|
|
||
| - [Glossary](#glossary) | ||
| - [Summary](#summary) | ||
| - [Motivation](#motivation) | ||
| - [Goals](#goals) | ||
| - [Non-Goals/Future Work](#non-goalsfuture-work) | ||
| - [Proposal](#proposal) | ||
| - [User Stories](#user-stories) | ||
| - [Story 1](#story-1) | ||
| - [Story 2](#story-2) | ||
| - [Security Model](#security-model) | ||
| - [Upgrade Strategy](#upgrade-strategy) | ||
| - [Implementation History](#implementation-history) | ||
|
|
||
| <!-- END doctoc generated TOC please keep comment here to allow auto update --> | ||
|
|
||
| ## Glossary | ||
|
|
||
| Refer to the [Cluster API Book Glossary](https://cluster-api.sigs.k8s.io/reference/glossary.html). | ||
|
|
||
| ### External CA | ||
|
|
||
| An External Certificate Authority (CA) is a CA that exists outside the Cluster API (CAPI) management plane. Instead of having Cluster API generate and manage its own self-signed CA for cluster components (such as kube-apiserver, kubelet, and etcd), an external CA can be integrated to provide trusted root certificates. This is typically used in environments where certificate lifecycles are centrally managed for compliance, auditing, or security policy reasons. | ||
|
|
||
| ### External certificate signing | ||
|
|
||
| External certificate signing is the process of delegating certificate issuance to a signing service instead of relying on self-signed certificates generated by Cluster API or a [bootstrap provider](https://cluster-api.sigs.k8s.io/reference/glossary.html#bootstrap-provider). With this approach, the Cluster API user becomes responsible for providing the signed certificates, ensuring their signing by the external CA, and managing their rotation over time. | ||
|
|
||
| ## Summary | ||
|
|
||
| This proposal introduces the ability for CAPI to integrate with fully external Certificate Authorities (CAs), meaning that CA key never leaves the external system. It also supports external certificate signing, where all certificate issuance is delegated externally. Cluster components generate Certificate Signing Requests (CSRs) that are signed by the external CA, providing a centralized and consistent trust chain across cluster bootstrap and lifecycle operations. | ||
|
|
||
| With this approach, the CAPI user is responsible for setting up a system to provide signed certificates, coordinate signing with the external CA, and manage certificate rotation over time. This enables integration with enterprise PKI systems, enforces organizational security policies, and ensures compliance with regulatory requirements while maintaining secure communication between cluster components. | ||
|
|
||
| ## Motivation | ||
|
|
||
| Currently, CAPI generates and manages CA keys within the management cluster. These keys are also distributed to control plane nodes via cloud-init userdata during bootstrap. This design exposes several security risks: | ||
|
|
||
| - Key exposure in the management cluster: Anyone with access to the management cluster potentially has access to the CA keys. | ||
| - Key transit over cloud-init: The CA private keys travel over cloud-init user data during control plane provisioning, which could be intercepted or leaked. | ||
| - Privilege escalation risk: With access to CA keys, an attacker can sign admin or superadmin certificates, gaining full control over clusters and workloads. | ||
|
|
||
| For reference, native Kubernetes clusters generate CA keys and store them on control plane nodes. This also represents a security risk because compromise of a control plane node could allow signing of highly privileged certificates. | ||
|
|
||
| By integrating fully external CAs and delegating certificate signing externally: | ||
|
|
||
| - CA keys never leave the external system, removing the risk of compromise through the management cluster or cloud-init. | ||
| - Cluster API users can implement centralized enterprise PKI practices, ensuring strict access control and auditability for certificate issuance. | ||
| - Overall trust in cluster bootstrap and lifecycle operations is increased, mitigating a high-impact attack vector that currently exists in both Cluster API and native Kubernetes. | ||
|
|
||
| This proposal addresses a critical security gap, providing users with a mechanism to eliminate CA key exposure while maintaining full Kubernetes functionality. | ||
|
|
||
| ### Goals | ||
|
|
||
| - Enable Cluster API to integrate with fully external Certificate Authorities (CAs) where CA private keys never leave the external system. | ||
| - Support external certificate signing for cluster components (control plane and nodes), delegating certificate issuance to an external CA or signing service. | ||
| - Allow users to implement their own PKI workflow, including certificate provisioning, signing, and rotation, while maintaining secure cluster bootstrap and lifecycle operations. | ||
| - Reduce the attack surface related to CA key exposure during cluster bootstrap, management, and rotation. | ||
| - Maintain compatibility with existing bootstrap providers while using external signing. | ||
|
|
||
| ### Non-Goals/Future Work | ||
|
|
||
| - Cluster API will not provide a built-in external CA service; users remain responsible for setting up and managing the external CA. | ||
| - This feature does not replace existing certificate management solutions such as cert-manager; rather, it provides a mechanism to integrate them. | ||
| - This proposal does not modify Kubernetes internal certificate signing behavior beyond enabling delegation to an external authority. | ||
|
|
||
| ## Proposal | ||
|
|
||
| To support external certificate signing and fully external CAs in CAPI, this proposal introduces a spec-level flag in the Cluster resource, e.g., externalCA, externalCAKey, or externalCertSigning. This flag will indicate that the cluster should operate in "external CA mode." | ||
|
||
|
|
||
|
There was a problem hiding this comment. Currently, I see these unencrypted keys are on control-planes:
It would be great if the proposal would list these files and provides a hint how each file will be handled There was a problem hiding this comment. It is already listed in kubernetes documentation here: https://kubernetes.io/docs/setup/best-practices/certificates/. I can refer to the link directly. There was a problem hiding this comment. @moh2a thank you for the link. Please image that: An control-plane admin was fired. He is angry. He took all key-files from a node. With your proposal There was a problem hiding this comment. In my proposal, I take into account the CA keys (etcd, ca, and proxy). All other certificates derive from these CAs. Personally, I create certificates (clients/servers) with a fairly short validity period. An angry administrator with access to the control planes could only retrieve the client/server certificate keys, but would not be able to issue certificates indefinitely since the CA keys are not present on the control planes. Regarding the service account key pair, it's a little more complicated since the kube-controller-manager needs it on demand. I suggest you read this proposal: https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/740-service-account-external-signing/README.md. |
||
| Key aspects of the proposal: | ||
|
|
||
| ### External CA mode | ||
|
|
||
| When the flag is enabled, CA keys are no longer required in the CAPI management cluster and must not be stored or validated in secrets. | ||
|
||
| CAPI will not generate or manage CA private keys. The CA certificates needs to be provided by the user in Kubernetes secrets with the current format: | ||
|
||
|
|
||
| - <cluster-name>-etcd | ||
| - <cluster-name>-ca | ||
| - <cluster-name>-proxy | ||
| CAPI should wait for the CA certificates if they are not already provided. CAPI must not adopt these Secrets, as they are the responsibility of the user.” | ||
moh2a marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ### Certificates necessary to Cluster API | ||
|
|
||
| Certificates such as the etcd client certificate and the admin certificate for the kubeconfig are normally generated by CAPI. In external CA mode, these certificates are still needed, but their provisioning and lifecycle management become the responsibility of the user. Users can leverage their own certificate management system, such as cert-manager or any other certificate management solution, to sign and rotate these certificates. | ||
|
There was a problem hiding this comment. what about the client certificate keys? There was a problem hiding this comment. The client certificate keys remain stored in Kubernetes Secrets even in external CA mode. This proposal only allows CAPI to operate without storing, using or validating the CA keys in the management cluster, cloud init or in a workload cluster. There was a problem hiding this comment. if the user provides the kube-apiserver --kubelet-client-key and --kubelet-client-cert in a secret, signed by an external CA, what mechanism in CAPI will write them on the nodes? and when will that happen? perhaps i'm misunderstanding, but if both a client cert and a client cert key are written to a secret, ideally, that has to be encrypted. because the private keys cannot be publicly accessible. |
||
|
|
||
| The etcd client certificate should be provided by the user in a secret named <cluster-name>-apiserver-etcd-client | ||
| The kubeconfig admin certificate should be provided by the user in a secret named <cluster-name>-admin | ||
|
There was a problem hiding this comment. would controller logs be the location where errors would surface for users that did not prepare the cert secrets correctly? There was a problem hiding this comment. A condition could also be used to impact the overall status of the Cluster resource. At initialization, a missing certificate is not necessarily an error but a temporary state. There was a problem hiding this comment. the proposal should include all proposed changes in CAPI and provide alternatives near the end. |
||
|
|
||
| ### Kubeadm Bootstrap: ClusterConfiguration and InitConfiguration | ||
|
|
||
| When using Kubeadm bootstrap, the command kubeadm certs generate-csr requires a configuration file containing ClusterConfiguration and/or InitConfiguration. Currently these files are only provided to the initialization control plane. | ||
| These configurations must be provided to joining control plane nodes because they contain the necessary information to generate Certificate Signing Requests (CSRs) for their components. The joining control plane nodes will generate CSRs locally and submit them to the external CA or user-provided signing system. | ||
|
There was a problem hiding this comment. how would the init/clusterconfiguration be transferred to joining control plane nodes? what mechanism would take the CSRs from the hosts and send them to the external signer? while ideally kubeadm CSRs should be the source of truth for any certs that kubeadm needs, calling kubeadm commands on the node hosts and then sending CSRs over the network sounds complicated. also who is going to call the kubeadm commands on the node hosts? There was a problem hiding this comment. The init/ClusterConfiguration for joining control plane nodes would be transferred using the same mechanism as for the initial control plane node (using cloud init files) The responsibilities of CAPI end at enabling external CA mode and signaling that CA keys are managed externally. Generation of CSRs from the nodes and their submission to an external signer are fully the responsibility of the user. Users can leverage their own mechanisms, such as pre-kubeadm scripts, cloud-init, or any other automation, to generate the CSRs, submit them to the external CA, and retrieve the signed certificates. This approach ensures that CAPI remains agnostic to the external signing process, while giving users full flexibility to implement their desired certificate management workflow. There was a problem hiding this comment. i see, so this CAEP proposes to disable the internal use of CA keys in CAPI by enabling |
||
|
|
||
| Below the workflow that describe this proposal. | ||
|
|
||
|  | ||
|
|
||
| ### User Stories | ||
|
|
||
| #### Enterprise PKI Integration | ||
|
|
||
| As a Cluster API user in an enterprise environment, I want to delegate certificate signing to our corporate CA, so that CA keys never reside in the management cluster and certificate issuance complies with organizational security policies. | ||
|
|
||
| #### Flexible Bootstrap Provider Support | ||
|
|
||
| As a Cluster API user I want that cluster-api provide all necessary configuration to bootstrap providers to be compatible with external signing, so that I can maintain secure certificate flows regardless of the underlying bootstrap mechanism. | ||
moh2a marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ### Security Model | ||
|
|
||
| The External CA / External Certificate Signing feature is designed to minimize exposure of CA private keys and improve the overall security posture of Cluster API clusters. The security model includes the following key points: | ||
|
|
||
| - CA private keys never leave the external CA system. | ||
| - Cluster API and management clusters do not store CA keys in secrets. | ||
|
|
||
| ## Upgrade Strategy | ||
|
|
||
| No special upgrade plan is required for this feature. Enabling external CA and external certificate signing does not break existing Cluster API behavior. Clusters that use the default internal CA workflow will remain fully functional. | ||
|
||
|
|
||
|
There was a problem hiding this comment. @moh2a will it be possible to update an existing cluster (which was created the old way) to a cluster with external CA? I guess this will not be possible. Maybe add a about that note here. There was a problem hiding this comment. I didn't think about switching from internal CA to external CA. If you want to make this change, you'll need to ask yourself whether you want to keep the same CAs or use new ones. If you want to use new ones (I think this is the case for you, as your current CAs may already have been exposed), you will need to perform a rotation, which is not trivial: https://kubernetes.io/docs/tasks/tls/manual-rotation-of-ca-certificates/ There was a problem hiding this comment. covering this use case is a valid as in-scope / out-of-scope; users might want to migrate existing clusters to externalCA. |
||
| ## Additional Details | ||
|
|
||
| ## Implementation History | ||
|
|
||
| - [x] 08/05/2025: Proposed idea in an issue | ||
| - [x] 09/03/2025: First round of feedback from community | ||
| - [x] 09/08/2025: Open proposal PR | ||
| - [ ] MM/DD/YYYY: Present proposal at a [community meeting] | ||
|
|
||
| <!-- Links --> | ||
|
|
||
| [community meeting]: https://docs.google.com/document/d/1ushaVqAKYnZ2VN_aa3GyKlS4kEd6bSug13xaXOakAQI/edit#heading=h.pxsq37pzkbdq | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| @startuml | ||
| title Cluster API External CA / External Certificate Signing Flow | ||
|
|
||
| actor "Cluster API User" as User | ||
| entity "Management Cluster (CAPI)" as CAPI | ||
| entity "PKI System" as PKI | ||
| entity "Control Plane Node" as CP | ||
| entity "Bootstrap Provider" as BP | ||
|
|
||
| User -> CAPI : Sets `externalCA=true` in Cluster spec | ||
|
|
||
| User -> PKI : Generate and submit CSR for admin certificate | ||
| User-> PKI : Generate and submit CSR for etcd-client certificate | ||
| PKI -> User : Sign etcd-client certificate | ||
| PKI -> User : Sign admin certificate | ||
|
|
||
| User -> CAPI : Provider admin certificate for kubeconfig | ||
| User -> CAPI : Provider etcd-client certificate for etcd healthcheck and others actions. | ||
moh2a marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| CAPI -> CP : Provides ClusterConfiguration / InitConfiguration | ||
| CP -> BP : Provides ClusterConfiguration / InitConfiguration | ||
| BP -> CP : Generates CSRs for required certs | ||
| CP -> PKI : Submits CSRs for signing | ||
| CA -> CP : Returns signed certificates | ||
| CP -> CAPI : Registers certificates / updates status | ||
| CP -> CP : Uses signed certs for kube-apiserver, etcd, kubelet | ||
|
|
||
| note right of PKI | ||
| CA keys never leave the PKI system | ||
| end note | ||
|
|
||
| note left of User | ||
| Responsible for providing signed certificates | ||
| and managing rotation | ||
| end note | ||
|
|
||
| @enduml | ||
Uh oh!
There was an error while loading. Please reload this page.