-
Notifications
You must be signed in to change notification settings - Fork 14.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* kubeadm certificate API and CSR documentation * copyedits * fix typo
- Loading branch information
1 parent
c22d699
commit 7e11bde
Showing
1 changed file
with
124 additions
and
0 deletions.
There are no files selected for viewing
124 changes: 124 additions & 0 deletions
124
content/en/docs/tasks/administer-cluster/kubeadm/kubeadm-certs.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |