diff --git a/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md new file mode 100644 index 0000000000000..6414a9e8de371 --- /dev/null +++ b/content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md @@ -0,0 +1,124 @@ +--- +reviewers: +- sig-cluster-lifecycle +title: Certificate Management with kubeadm +content_template: templates/task +--- + +{{% capture overview %}} + +This page explains how to manage certificates manually with kubeadm. + +{{% /capture %}} + +{{% capture prerequisites %}} + +These are advanced topics for users who need to integrate their organization's certificate infrastructure into a kubeadm-built cluster. If kubeadm with the default configuration satisfies your needs, you should let kubeadm manage certificates instead. + +You should be familiar with [PKI certificates and requirements in Kubernetes](/docs/setup/certificates/). + +{{% /capture %}} + +{{% capture steps %}} + +## Renew certificates with the certificates API + +Kubeadm can renew certificates with the `kubeadm alpha certs renew` commands. + +Typically this is done by loading on-disk CA certificates and keys and using them to issue new certificates. +This approach works well if your certificate tree is self-contained. However, if your certificates are externally +managed, you might need a different approach. + +As an alternative, Kubernetes provides its own [API for managing certificates][manage-tls]. +With kubeadm, you can use this API by running `kubeadm alpha certs renew --use-api`. + +## Set up a signer + +The Kubernetes Certificate Authority does not work out of the box. +You can configure an external signer such as [cert-manager][cert-manager-issuer], or you can use the build-in signer. +The built-in signer is part of [`kube-controller-manager`][kcm]. +To activate the build-in signer, you pass the `--cluster-signing-cert-file` and `--cluster-signing-key-file` arguments. + +You pass these arguments in any of the following ways: + +* Edit `/etc/kubernetes/manifests/kube-controller-manager.yaml` to add the arguments to the command. + Remember that your changes could be overwritten when you upgrade. + +* If you're creating a new cluster, you can use a kubeadm [configuration file][config]: + + ```yaml + apiVersion: kubeadm.k8s.io/v1beta1 + kind: ClusterConfiguration + controllerManager: + extraArgs: + cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt + cluster-signing-key-file: /etc/kubernetes/pki/ca.key + ``` + +* You can also upload a config file using [`kubeadm config upload from-files`][config-upload] + +[cert-manager-issuer]: https://cert-manager.readthedocs.io/en/latest/tutorials/ca/creating-ca-issuer.html +[kcm]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/ +[config]: https://godoc.org/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm/v1beta1 +[config-upload]: https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm-config/#cmd-config-from-file + +### Approve requests + +If you set up an external signer such as [cert-manager][cert-manager], certificate signing requests (CSRs) are automatically approved. +Otherwise, you must manually approve certificates with the [`kubectl certificates`][certs] command. +The following kubeadm command outputs the name of the certificate to approve, then blocks and waits for approval to occur: + +```shell +$ sudo kubeadm alpha certs renew apiserver --use-api & +[1] 2890 +[certs] certificate request "kubeadm-cert-kube-apiserver-ld526" created +$ kubectl certificate approve kubeadm-cert-kube-apiserver-ld526 +certificatesigningrequest.certificates.k8s.io/kubeadm-cert-kube-apiserver-ld526 approved +[1]+ Done sudo kubeadm alpha certs renew apiserver --use-api +``` + +You can view a list of pending certificates with `kubectl get csr`. + +[manage-tls]: https://kubernetes.io/docs/tasks/tls/managing-tls-in-a-cluster/ +[cert-manager]: https://github.com/jetstack/cert-manager +[certs]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#certificate + +## Certificate requests with kubeadm + +To better integrate with external CAs, kubeadm can also produce certificate signing requests (CSRs). +A CSR represents a request to a CA for a signed certificate for a client. +In kubeadm terms, any certificate that would normally be signed by an on-disk CA can be produced as a CSR instead. A CA, however, cannot be produced as a CSR. + +You can create an individual CSR with `kubeadm init phase certs apiserver --use-csr`. +The `--use-csr` flag can be applied only to individual phases. After [all certificates are in place][certs], you can run `kubeadm init --external-ca`. + +You can pass in a directory with `--csr-dir` to output the CSRs to the specified location. +If `--csr-dire` is not specified, the default certificate directory (`/etc/kubernetes/pki`) is used. +Both the CSR and the accompanying private key are given in the output. After a certificate is signed, the certificate and the private key must be copied to the PKI directory (by default `/etc/kubernetes/pki`). + +### Renew certificates + +Certificates can be renewed with `kubeadm alpha certs renew --use-csr`. +As with `kubeadm init`, an output directory can be specified with the `--csr-dir` flag. +To use the new certificates, copy the signed certificate and private key into the PKI directory (by default `/etc/kubernetes/pki`) + +## Cert usage + +A CSR contains a certificate's name, domains, and IPs, but it does not specify usages. +It is the responsibility of the CA to specify [the correct cert usages][cert-table] when issuing a certificate. + +* In `openssl` this is done with the [`openssl ca` command][openssl-ca]. +* In `cfssl` you specify [usages in the config file][cfssl-usages] + +## CA selection + +Kubeadm sets up [three CAs][cert-cas] by default. Make sure to sign the CSRs with a corresponding CA. + +[openssl-ca]: https://superuser.com/questions/738612/openssl-ca-keyusage-extension +[cfssl-usages]: https://github.com/cloudflare/cfssl/blob/master/doc/cmd/cfssl.txt#L170 +[certs]: https://kubernetes.io/docs/setup/certificates +[cert-cas]: https://kubernetes.io/docs/setup/certificates/#single-root-ca +[cert-table]: https://kubernetes.io/docs/setup/certificates/#all-certificates + +{{% /capture %}} +https://prow.k8s.io/?pull=71212