Add documentation for certificate rotation.

_data/tasks.yml

@@ -128,6 +128,7 @@ toc:
   - docs/tasks/administer-cluster/access-cluster-services.md
   - docs/tasks/administer-cluster/securing-a-cluster.md
   - docs/tasks/administer-cluster/encrypt-data.md
+  - docs/tasks/administer-cluster/certificate-rotation.md
   - docs/tasks/administer-cluster/configure-upgrade-etcd.md
   - docs/tasks/administer-cluster/static-pod.md
   - docs/tasks/administer-cluster/cluster-management.md

docs/tasks/administer-cluster/certificate-rotation.md

@@ -0,0 +1,70 @@
+---
+approvers:
+- smarterclayton
+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 %}
+
+## 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` for the feature to be
+enabled.
+
+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 %}

docs/tasks/administer-cluster/securing-a-cluster.md

@@ -195,6 +195,17 @@ parties that gain access to your etcd backups from viewing the content of those
 this feature is currently experimental, it may offer an additional level of defense when backups
 are not encrypted or an attacker gains read access to etcd.
 
+### Kubelet Certificate Rotation
+
+The kubelet uses certificates for authenticating to the Kubernetes API.
+Normally, these certificates are issued with a long expiry date, such that
+normally 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.
+
 ### Receiving alerts for security updates and reporting vulnerabilities
 
 Join the [kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce)