From 4a085f5d10d9282cf1f24e21e13296efef9a9d9e Mon Sep 17 00:00:00 2001 From: Jacob Simpson Date: Tue, 26 Sep 2017 09:48:03 -0700 Subject: [PATCH] Add documentation for certificate rotation. --- _data/tasks.yml | 1 + docs/tasks/tls/certificate-rotation.md | 82 ++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 docs/tasks/tls/certificate-rotation.md diff --git a/_data/tasks.yml b/_data/tasks.yml index fce07a3f5dd6a..b880465dbbdb7 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -110,6 +110,7 @@ toc: - title: TLS section: - docs/tasks/tls/managing-tls-in-a-cluster.md + - docs/tasks/tls/certificate-rotation.md - title: Administer a Cluster section: diff --git a/docs/tasks/tls/certificate-rotation.md b/docs/tasks/tls/certificate-rotation.md new file mode 100644 index 0000000000000..9fe86cde66610 --- /dev/null +++ b/docs/tasks/tls/certificate-rotation.md @@ -0,0 +1,82 @@ +--- +approvers: +- jcbsmpsn +- mikedanese +title: Certificate rotation +--- + +{% capture overview %} +This page shows how to enable and configure certificate rotation for the kubelet. +{% endcapture %} + +{% capture prerequisites %} + +* {% include task-tutorial-prereqs.md %} + +* Kubernetes version 1.8.0 or later is required + +* Encryption at rest is beta in 1.8.0 which means it may change without notice. + +{% endcapture %} + +{% capture steps %} + +## Overview + +The kubelet uses certificates for authenticating to the Kubernetes API. +Normally, these certificates are issued with a long expiry date so that they do +not need to be renewed. + +Kubernetes 1.8 contains [kubelet certificate +rotation](/docs/tasks/administer-cluster/certificate-rotation/), a beta feature +that will automatically generate a new key and request a new certificate from +the Kubernetes API to use for authenticating connections. + +## Configuration and determining whether certificate rotation is already enabled + +The `kubelet` process accepts an argument `--rotate-certificates` that controls +if the kubelet will automatically request a new certificate as the expiration of +the certificate currently in use approaches. Since certificate rotation is a +beta feature, the feature flag must also be enabled with +`--feature-gates=RotateKubeletClientCertificate=true`. + + +The `kube-controller-manager` process accepts an argument +`--experimental-cluster-signing-duration` that controls how long certificates +will be issued for. + +## Understanding the certificate rotation configuration + +When a kubelet starts up, if it is configured to bootstrap (using the +`--bootstrap-kubeconfig` flag) it will use it's initial certificate to connect +to the Kubernetes API and issue a certificate signing request. You can view the +status of certificate signing requests using: + +```sh +kubectl get csr +``` + +Initially a certificate signing request from the kubelet on a node will have a +status of `Pending`. If the certificate signing requests meets specific +criteria, it will be auto approved by the controller manager, then it will have +a status of `Approved`. Next, the controller manager will sign a certificate, +issued for the duration specified by the +`--experimental-cluster-signing-duration` parameter, and the signed certificate +will be attached to the certificate signing requests. + +The kubelet will retrieve the signed certificate from the Kubernetes API and +write that to disk, in the location specified by `--cert-dir`. Then the kubelet +will restart itself and use the new certificate to connect to the Kubernetes +API. + +As the expiration of the signed certificate approaches, the kubelet will +automatically issue a new certificate signing request, using the Kubernetes +API. Again, the controller manager will automatically approve the certificate +request and attach a signed certificate to the certificate signing request. The +kubelet will retrieve the new signed certificate from the Kubernetes API and +write that to disk. Then it will update the connections it has to the +Kubernetes API to reconnect using the new certificate. + +{% endcapture %} + +{% include templates/task.md %}