From 48d7eba6b784db1f6031f9a6bea78a1442a6680c Mon Sep 17 00:00:00 2001 From: JENNIFER RONDEAU Date: Mon, 13 Aug 2018 15:18:22 -0400 Subject: [PATCH 1/3] rebase certificates PR on Hugo master Co-authored-by: liztio --- content/en/docs/setup/certificates.md | 136 ++++++++++++++++++ .../setup/independent/kubelet-integration.md | 6 +- 2 files changed, 137 insertions(+), 5 deletions(-) create mode 100644 content/en/docs/setup/certificates.md diff --git a/content/en/docs/setup/certificates.md b/content/en/docs/setup/certificates.md new file mode 100644 index 0000000000000..7c0c1e856b0bd --- /dev/null +++ b/content/en/docs/setup/certificates.md @@ -0,0 +1,136 @@ +--- +title: PKI Certificates and Requirements +reviewers: +- sig-cluster-lifecycle +content_template: templates/concept +--- + +{{% capture overview %}} + +Kubernetes requires PKI certificates for authentication over TLS. +If you install Kubernetes with [kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/), the certificates that your cluster requires are automatically generated. +You can also generate your own certificates -- for example, to keep your private keys more secure by not storing them on the API server. +This page explains the certificates that your cluster requires. + +{{% /capture %}} + +{{% capture body %}} + +## How certificates are used by your cluster + +Kubernetes requires PKI for the following operations: + +* Client certificates for the kubelet to authenticate to the API server +* Server certificate for the API server endpoint +* Client certificates for administrators of the cluster to authenticate to the API server +* Client certificates for the API server to talk to the kubelets +* Client certificate for the API server to talk to etcd +* Client certificate/kubeconfig for the controller manager to talk to the API server +* Client certificate/kubeconfig for the scheduler to talk to the API server. +* Client and server certificates for the [front-proxy][proxy] + +etcd also implements mutual TLS to authenticate clients and peers. + +## Where certificates are stored + +Kubernetes stores certificates by default in `/etc/kubernetes/pki`. All paths in this documentation are relative to that directory. + +## Configure certificates manually + +If you don't want [kubeadm][kubeadm] to generate the required certificates, you can create them in either of the following ways. + +### Single root CA + +You can create a single root CA, controlled by an adminstrator. This root CA can then create multiple intermediate CAs, and delegate all further creation to Kubernetes itself. + +Required CAs: + +| path | Default CN | description | +|------------------------|---------------------------|----------------------------------| +| ca.crt,key | kubernetes-ca | Kubernetes general CA | +| etcd/ca.crt,key | etcd-ca | For all etcd-related functions | +| front-proxy-ca.crt,key | kubernetes-front-proxy-ca | For the [front-end proxy][proxy] | + +### All certificates + +If you don't wish to copy these private keys to your API servers, you can generate all certificates yourself. + +Required certificates: + +| Default CN | Parent CA | O (in Subject) | kind | hosts (SAN) | +|-------------------------------|---------------------------|----------------|----------------------------------------|---------------------------------------------| +| kube-etcd | etcd-ca | | server, client [1][etcdbug] | `localhost`, `127.0.0.1` | +| kube-etcd-peer | etcd-ca | | peer | ``, ``, `localhost`, `127.0.0.1` | +| kube-etcd-healthcheck-client | etcd-ca | | client | | +| kube-apiserver-etcd-client | etcd-ca | system:masters | client | | +| kube-apiserver | kubernetes-ca | | server | ``, ``, ``, `[1]` | +| kube-apiserver-kubelet-client | kubernetes-ca | system:masters | client | | +| front-proxy-client | kubernetes-front-proxy-ca | | client | | + +[1]: `kubernetes`, `kubernetes.default`, `kubernetes.default.svc`, `kubernetes.default.svc.cluster`, `kubernetes.default.svc.cluster.local` + +where `kind` is one or more of the [x509 key usage][usage] types: + +| kind | TLS role | +|--------|---------------------------------------------------------------------------------------------------| +| server | Digital Signature, Key Encipherment, TLS Web Server Authentication | +| peer | Digital Signature, Key Encipherment, TLS Web Server Authentication, TLS Web Client Authentication | +| client | Digital Signature, Key Encipherment, TLS Web Client Authentication | + +### Certificate paths + +Certificates should be placed in a recommended path (as used by [kubeadm][kubeadm]). Paths should be specified using the given argument regardless of location. + +| Default CN | recommend key path | recommended cert path | command | key argument | cert argument | +|------------------------------|------------------------------|-----------------------------|----------------|------------------------------|-------------------------------------------| +| etcd-ca | | etcd/ca.crt | kube-apiserver | | --etcd-cafile | +| etcd-client | apiserver-etcd-client.crt | apiserver-etcd-client.crt | kube-apiserver | --etcd-certfile | --etcd-keyfile | +| kubernetes-ca | | ca.crt | kube-apiserver | --client-ca-file | | +| kube-apiserver | apiserver.crt | apiserver.key | kube-apiserver | --tls-cert-file | --tls-private-key | +| apiserver-kubelet-client | apiserver-kubelet-client.crt | | kube-apiserver | --kubelet-client-certificate | | +| front-proxy-client | front-proxy-client.key | front-proxy-client.crt | kube-apiserver | --proxy-client-cert-file | --proxy-client-key-file | +| | | | | | | +| etcd-ca | | etcd/ca.crt | etcd | | --trusted-ca-file, --peer-trusted-ca-file | +| kube-etcd | | etcd/server.crt | etcd | | --cert-file | +| kube-etcd-peer | etcd/peer.key | etcd/peer.crt | etcd | --peer-key-file | --peer-cert-file | +| etcd-ca | | etcd/ca.crt | etcdctl[2] | | --cacert | +| kube-etcd-healthcheck-client | etcd/healthcheck-client.key | etcd/healthcheck-client.crt | etcdctl[2] | --key | --cert | + +[2]: For a liveness probe, if self-hosted + +## Configure certificates for user accounts + +You must manually configure thesee administrator account and service accounts: + +| filename | credential name | Default CN | O (in Subject) | +|-------------------------|----------------------------|--------------------------------|----------------| +| admin.conf | default-admin | kubernetes-admin | system:masters | +| kubelet.conf | default-auth | system:node:`` | system:nodes | +| controller-manager.conf | default-controller-manager | system:kube-controller-manager | | +| scheduler.conf | default-manager | system:kube-scheduler | | + +1. For each config, generate an x509 cert/key pair with the given CN and O. + +1. Run `kubectl` as follows for each config: + +```shell +KUBECONFIG= kubectl config set-cluster default-cluster --server=https://:6443 --certificate-authority --embed-certs +KUBECONFIG= kubectl config set-credentials --client-key .pem --client-certificate .pem --embed-certs +KUBECONFIG= kubectl config set-context default-system --cluster default-cluster --user +KUBECONFIG= kubectl config use-context default-system +``` + +These files are used as follows: + +| filename | command | comment | +|-------------------------|-------------------------|-----------------------------------------------------------------------| +| admin.conf | kubectl | Configures administrator user for the cluster | +| kubelet.conf | kubelet | One required for each node in the cluster. | +| controller-manager.conf | kube-controller-manager | Must be added to manifest in `manifests/kube-controller-manager.yaml` | +| scheduler.conf | kube-scheduler | Must be added to manifest in `manifests/kube-scheduler.yaml` | + +[usage]: https://tools.ietf.org/html/rfc5280#section-4.2.1.3 +[kubeadm]: /docs/reference/setup-tools/kubeadm/kubeadm/ +[proxy]: /docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/ + +{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/setup/independent/kubelet-integration.md b/content/en/docs/setup/independent/kubelet-integration.md index f9cbc142b2fa1..80836bdd0e30a 100644 --- a/content/en/docs/setup/independent/kubelet-integration.md +++ b/content/en/docs/setup/independent/kubelet-integration.md @@ -20,7 +20,7 @@ system or service manager. When the kubelet is installed using DEBs or RPMs, systemd is configured to manage the kubelet. You can use a different service manager instead, but you need to configure it manually. -Some kublet configuration details need to be the same across all kubelets involved in the cluster, while +Some kubelet configuration details need to be the same across all kubelets involved in the cluster, while other configuration aspects need to be set on a per-kubelet basis, to accommodate the different characteristics of a given machine, such as OS, storage, and networking. You can manage the configuration of your kubelets manually, but [kubeadm now provides a `MasterConfig` API type for managing your @@ -28,8 +28,6 @@ kubelet configurations centrally](#configure-kubelets-using-kubeadm). {{% /capture %}} -{{ toc }} - {{% capture body %}} ## Kubelet configuration patterns @@ -98,8 +96,6 @@ such as systemd. ## Configure kubelets using kubeadm -{{ feature-state for_k8s_version="1.11" state="stable" }} - The kubeadm config API type `MasterConfiguration` embeds the kubelet's ComponentConfig under the `.kubeletConfiguration.baseConfig` key. Any user writing a `MasterConfiguration` file can use this configuration key to also set the base-level configuration for all kubelets From a3001b49c6e8359d59f352d156875c2aefc46df0 Mon Sep 17 00:00:00 2001 From: JENNIFER RONDEAU Date: Wed, 15 Aug 2018 13:30:38 -0400 Subject: [PATCH 2/3] fix per comments, add note about front-proxy --- content/en/docs/setup/certificates.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/content/en/docs/setup/certificates.md b/content/en/docs/setup/certificates.md index 7c0c1e856b0bd..a5c8eea252e0b 100644 --- a/content/en/docs/setup/certificates.md +++ b/content/en/docs/setup/certificates.md @@ -29,15 +29,19 @@ Kubernetes requires PKI for the following operations: * Client certificate/kubeconfig for the scheduler to talk to the API server. * Client and server certificates for the [front-proxy][proxy] +{{< note >}} +**Note:** `front-proxy` certificates are required only if you run kube-proxy to support [an extension API server](/docs/tasks/access-kubernetes-api/setup-extension-api-server/). +{{< /note >}} + etcd also implements mutual TLS to authenticate clients and peers. ## Where certificates are stored -Kubernetes stores certificates by default in `/etc/kubernetes/pki`. All paths in this documentation are relative to that directory. +If you install Kubernetes with kubeadm, certificates are stored in `/etc/kubernetes/pki`. All paths in this documentation are relative to that directory. ## Configure certificates manually -If you don't want [kubeadm][kubeadm] to generate the required certificates, you can create them in either of the following ways. +If you don't want kubeadm to generate the required certificates, you can create them in either of the following ways. ### Single root CA @@ -60,7 +64,7 @@ Required certificates: | Default CN | Parent CA | O (in Subject) | kind | hosts (SAN) | |-------------------------------|---------------------------|----------------|----------------------------------------|---------------------------------------------| | kube-etcd | etcd-ca | | server, client [1][etcdbug] | `localhost`, `127.0.0.1` | -| kube-etcd-peer | etcd-ca | | peer | ``, ``, `localhost`, `127.0.0.1` | +| kube-etcd-peer | etcd-ca | | server, client | ``, ``, `localhost`, `127.0.0.1` | | kube-etcd-healthcheck-client | etcd-ca | | client | | | kube-apiserver-etcd-client | etcd-ca | system:masters | client | | | kube-apiserver | kubernetes-ca | | server | ``, ``, ``, `[1]` | @@ -100,7 +104,7 @@ Certificates should be placed in a recommended path (as used by [kubeadm][kubead ## Configure certificates for user accounts -You must manually configure thesee administrator account and service accounts: +You must manually configure these administrator account and service accounts: | filename | credential name | Default CN | O (in Subject) | |-------------------------|----------------------------|--------------------------------|----------------| @@ -131,6 +135,6 @@ These files are used as follows: [usage]: https://tools.ietf.org/html/rfc5280#section-4.2.1.3 [kubeadm]: /docs/reference/setup-tools/kubeadm/kubeadm/ -[proxy]: /docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/ +[proxy]: /docs/tasks/access-kubernetes-api/configure-aggregation-layer/ {{% /capture %}} \ No newline at end of file From 91a7702dc7b1b22b94d63e6690a1a7c7df11d822 Mon Sep 17 00:00:00 2001 From: JENNIFER RONDEAU Date: Thu, 16 Aug 2018 11:53:44 -0400 Subject: [PATCH 3/3] fix up key usage table and references --- content/en/docs/setup/certificates.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/en/docs/setup/certificates.md b/content/en/docs/setup/certificates.md index a5c8eea252e0b..39db59c3e3fae 100644 --- a/content/en/docs/setup/certificates.md +++ b/content/en/docs/setup/certificates.md @@ -73,13 +73,12 @@ Required certificates: [1]: `kubernetes`, `kubernetes.default`, `kubernetes.default.svc`, `kubernetes.default.svc.cluster`, `kubernetes.default.svc.cluster.local` -where `kind` is one or more of the [x509 key usage][usage] types: +where `kind` maps to one or more of the [x509 key usage][usage] types: -| kind | TLS role | -|--------|---------------------------------------------------------------------------------------------------| -| server | Digital Signature, Key Encipherment, TLS Web Server Authentication | -| peer | Digital Signature, Key Encipherment, TLS Web Server Authentication, TLS Web Client Authentication | -| client | Digital Signature, Key Encipherment, TLS Web Client Authentication | +| kind | Key usage | +|--------|---------------------------------------------------------------------------------| +| server | digital signature, key encipherment, server auth | +| client | digital signature, key encipherment, client auth | ### Certificate paths @@ -133,7 +132,7 @@ These files are used as follows: | controller-manager.conf | kube-controller-manager | Must be added to manifest in `manifests/kube-controller-manager.yaml` | | scheduler.conf | kube-scheduler | Must be added to manifest in `manifests/kube-scheduler.yaml` | -[usage]: https://tools.ietf.org/html/rfc5280#section-4.2.1.3 +[usage]: https://godoc.org/k8s.io/api/certificates/v1beta1#KeyUsage [kubeadm]: /docs/reference/setup-tools/kubeadm/kubeadm/ [proxy]: /docs/tasks/access-kubernetes-api/configure-aggregation-layer/