Skip to content

Commit

Permalink
kubeadm-certs: add notes about different external CA approaches
Browse files Browse the repository at this point in the history
There are multiple ways to prepare the credentials for use
with "external CA" mode:
- manual
- using kubeadm CSRs
- using kubeadm phases
  • Loading branch information
neolit123 committed Feb 9, 2024
1 parent 80aa5f5 commit 9593771
Showing 1 changed file with 40 additions and 2 deletions.
42 changes: 40 additions & 2 deletions content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md
Expand Up @@ -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

Expand Down

0 comments on commit 9593771

Please sign in to comment.