From 9593771ee90bc829560eaf4fa25d06214ddef253 Mon Sep 17 00:00:00 2001 From: "Lubomir I. Ivanov" Date: Fri, 9 Feb 2024 12:23:03 +0200 Subject: [PATCH] kubeadm-certs: add notes about different external CA approaches There are multiple ways to prepare the credentials for use with "external CA" mode: - manual - using kubeadm CSRs - using kubeadm phases --- .../kubeadm/kubeadm-certs.md | 42 ++++++++++++++++++- 1 file changed, 40 insertions(+), 2 deletions(-) diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md index df93d79c46..623e528aa8 100644 --- a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -46,8 +46,46 @@ CA key on disk. Instead, run the controller-manager standalone with `--controllers=csrsigner` and point to the CA certificate and key. -[PKI certificates and requirements](/docs/setup/best-practices/certificates/) includes guidance on -setting up a cluster to use an external CA. +There are various ways to prepare the component credentials when using external CA mode. + +### Manual preparation of component credentials + +[PKI certificates and requirements](/docs/setup/best-practices/certificates/) includes information +on how to prepare all the required by kubeadm component credentials manually. + +### Preparation of credentials by signing CSRs generated by kubeadm + +kubeadm can [generate CSR files](#signing-csr) that you can sign manually with tools like +`openssl` and your external CA. These CSR files will include all the specification for credentials +that components deployed by kubeadm require. + +### Automated preparation of component credentials by using kubeadm phases + +Alternatively, it is possible to use kubeadm phase commands to automate this process. + +- Go to a host that you want to prepare as a kubeadm control plane node with external CA. +- Copy the external CA files `ca.crt` and `ca.key` that you have into `/etc/kubernetes/pki` on the node. +- Prepare a temporary [kubeadm configuration file](/docs/reference/setup-tools/kubeadm/kubeadm-init/#config-file) +called `config.yaml` that can be used with `kubeadm init`. Make sure that this file includes +any relevant cluster wide or host-specific information that could be included in certificates, such as, +`ClusterConfiguration.controlPlaneEndpoint`, `ClusterConfiguration.certSANs` and `InitConfiguration.APIEndpoint`. +- On the same host execute the commands `kubeadm init phase kubeconfig all --config config.yaml` and +`kubeadm init phase certs all --config config.yaml`. This will generate all required kubeconfig +files and certificates under `/etc/kubernetes/` and its `pki` sub directory. +- Inspect the generated files. Delete `/etc/kubernetes/pki/ca.key`, delete or move to a safe location +the file `/etc/kubernetes/super-admin.conf`. +- On nodes where `kubeadm join` will be called also delete `/etc/kubernetes/kubelet.conf`. +This file is only required on the first node where `kubeadm init` will be called. +- Note that some files such `pki/sa.*`, `pki/front-proxy-ca.*` and `pki/etc/ca.*` are +shared between control plane nodes, You can generate them once and +[distribute them manually](/docs/setup/production-environment/tools/kubeadm/high-availability/#manual-certs) +to nodes where `kubeadm join` will be called, or you can use the +[`--upload-certs`](/docs/setup/production-environment/tools/kubeadm/high-availability/#stacked-control-plane-and-etcd-nodes) +functionality of `kubeadm init` and `--certificate-key` of `kubeadm join` to automate this distribution. + +Once the credentials are prepared on all nodes, call `kubeadm init` and `kubeadm join` for these nodes to +join the cluster. kubeadm will use the existing kubeconfig and certificate files under `/etc/kubernetes/` +and its `pki` sub directory. ## Check certificate expiration