From 227cb354a98fdb90ff83171879e3b4b738b23fa5 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Sat, 17 Dec 2022 17:21:02 +0800 Subject: [PATCH] Normalize the markdown for the certificates.md page --- .../docs/setup/best-practices/certificates.md | 118 ++++++++++-------- 1 file changed, 66 insertions(+), 52 deletions(-) diff --git a/content/en/docs/setup/best-practices/certificates.md b/content/en/docs/setup/best-practices/certificates.md index 7c17850400f..20229b8c04d 100644 --- a/content/en/docs/setup/best-practices/certificates.md +++ b/content/en/docs/setup/best-practices/certificates.md @@ -9,12 +9,12 @@ weight: 50 Kubernetes requires PKI certificates for authentication over TLS. -If you install Kubernetes with [kubeadm](/docs/reference/setup-tools/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. +If you install Kubernetes with [kubeadm](/docs/reference/setup-tools/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. - - ## How certificates are used by your cluster @@ -33,24 +33,30 @@ Kubernetes requires PKI for the following operations: * Client and server certificates for the [front-proxy](/docs/tasks/extend-kubernetes/configure-aggregation-layer/) {{< note >}} -`front-proxy` certificates are required only if you run kube-proxy to support [an extension API server](/docs/tasks/extend-kubernetes/setup-extension-api-server/). +`front-proxy` certificates are required only if you run kube-proxy to support +[an extension API server](/docs/tasks/extend-kubernetes/setup-extension-api-server/). {{< /note >}} etcd also implements mutual TLS to authenticate clients and peers. ## Where certificates are stored -If you install Kubernetes with kubeadm, most certificates are stored in `/etc/kubernetes/pki`. All paths in this documentation are relative to that directory, with the exception of user account certificates which kubeadm places in `/etc/kubernetes`. +If you install Kubernetes with kubeadm, most certificates are stored in `/etc/kubernetes/pki`. +All paths in this documentation are relative to that directory, with the exception of user account +certificates which kubeadm places in `/etc/kubernetes`. ## Configure certificates manually -If you don't want kubeadm to generate the required certificates, you can create them using a single root CA or by providing all certificates. See [Certificates](/docs/tasks/administer-cluster/certificates/) for details on creating your own certificate authority. -See [Certificate Management with kubeadm](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/) for more on managing certificates. - +If you don't want kubeadm to generate the required certificates, you can create them using a +single root CA or by providing all certificates. See [Certificates](/docs/tasks/administer-cluster/certificates/) +for details on creating your own certificate authority. See +[Certificate Management with kubeadm](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/) +for more on managing certificates. ### Single root CA -You can create a single root CA, controlled by an administrator. This root CA can then create multiple intermediate CAs, and delegate all further creation to Kubernetes itself. +You can create a single root CA, controlled by an administrator. This root CA can then create +multiple intermediate CAs, and delegate all further creation to Kubernetes itself. Required CAs: @@ -60,7 +66,8 @@ Required CAs: | 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](/docs/tasks/extend-kubernetes/configure-aggregation-layer/) | -On top of the above CAs, it is also necessary to get a public/private key pair for service account management, `sa.key` and `sa.pub`. +On top of the above CAs, it is also necessary to get a public/private key pair for service account +management, `sa.key` and `sa.pub`. The following example illustrates the CA key and certificate files shown in the previous table: ``` @@ -71,21 +78,22 @@ The following example illustrates the CA key and certificate files shown in the /etc/kubernetes/pki/front-proxy-ca.crt /etc/kubernetes/pki/front-proxy-ca.key ``` + ### All certificates If you don't wish to copy the CA private keys to your cluster, you can generate all certificates yourself. Required certificates: -| Default CN | Parent CA | O (in Subject) | kind | hosts (SAN) | -|-------------------------------|---------------------------|----------------|----------------------------------------|---------------------------------------------| -| kube-etcd | etcd-ca | | server, client | ``, ``, `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]` | -| kube-apiserver-kubelet-client | kubernetes-ca | system:masters | client | | -| front-proxy-client | kubernetes-front-proxy-ca | | client | | +| Default CN | Parent CA | O (in Subject) | kind | hosts (SAN) | +|-------------------------------|---------------------------|----------------|------------------|-----------------------------------------------------| +| kube-etcd | etcd-ca | | server, client | ``, ``, `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]` | +| kube-apiserver-kubelet-client | kubernetes-ca | system:masters | client | | +| front-proxy-client | kubernetes-front-proxy-ca | | client | | [1]: any other IP or DNS name you contact your cluster on (as used by [kubeadm](/docs/reference/setup-tools/kubeadm/) the load balancer stable IP and/or DNS name, `kubernetes`, `kubernetes.default`, `kubernetes.default.svc`, @@ -101,15 +109,18 @@ type: | client | digital signature, key encipherment, client auth | {{< note >}} -Hosts/SAN listed above are the recommended ones for getting a working cluster; if required by a specific setup, it is possible to add additional SANs on all the server certificates. +Hosts/SAN listed above are the recommended ones for getting a working cluster; if required by a +specific setup, it is possible to add additional SANs on all the server certificates. {{< /note >}} {{< note >}} For kubeadm users only: -* The scenario where you are copying to your cluster CA certificates without private keys is referred as external CA in the kubeadm documentation. -* If you are comparing the above list with a kubeadm generated PKI, please be aware that `kube-etcd`, `kube-etcd-peer` and `kube-etcd-healthcheck-client` certificates - are not generated in case of external etcd. +* The scenario where you are copying to your cluster CA certificates without private keys is + referred as external CA in the kubeadm documentation. +* If you are comparing the above list with a kubeadm generated PKI, please be aware that + `kube-etcd`, `kube-etcd-peer` and `kube-etcd-healthcheck-client` certificates are not generated + in case of external etcd. {{< /note >}} @@ -118,31 +129,32 @@ For kubeadm users only: Certificates should be placed in a recommended path (as used by [kubeadm](/docs/reference/setup-tools/kubeadm/)). Paths should be specified using the given argument regardless of location. -| Default CN | recommended key path | recommended cert path | command | key argument | cert argument | -|------------------------------|------------------------------|-----------------------------|----------------|------------------------------|-------------------------------------------| -| etcd-ca | etcd/ca.key | etcd/ca.crt | kube-apiserver | | --etcd-cafile | -| kube-apiserver-etcd-client | apiserver-etcd-client.key | apiserver-etcd-client.crt | kube-apiserver | --etcd-keyfile | --etcd-certfile | -| kubernetes-ca | ca.key | ca.crt | kube-apiserver | | --client-ca-file | -| kubernetes-ca | ca.key | ca.crt | kube-controller-manager | --cluster-signing-key-file | --client-ca-file, --root-ca-file, --cluster-signing-cert-file | -| kube-apiserver | apiserver.key | apiserver.crt | kube-apiserver | --tls-private-key-file | --tls-cert-file | -| kube-apiserver-kubelet-client| apiserver-kubelet-client.key | apiserver-kubelet-client.crt| kube-apiserver | --kubelet-client-key | --kubelet-client-certificate | -| front-proxy-ca | front-proxy-ca.key | front-proxy-ca.crt | kube-apiserver | | --requestheader-client-ca-file | -| front-proxy-ca | front-proxy-ca.key | front-proxy-ca.crt | kube-controller-manager | | --requestheader-client-ca-file | -| front-proxy-client | front-proxy-client.key | front-proxy-client.crt | kube-apiserver | --proxy-client-key-file | --proxy-client-cert-file | -| etcd-ca | etcd/ca.key | etcd/ca.crt | etcd | | --trusted-ca-file, --peer-trusted-ca-file | -| kube-etcd | etcd/server.key | etcd/server.crt | etcd | --key-file | --cert-file | -| kube-etcd-peer | etcd/peer.key | etcd/peer.crt | etcd | --peer-key-file | --peer-cert-file | -| etcd-ca | | etcd/ca.crt | etcdctl | | --cacert | -| kube-etcd-healthcheck-client | etcd/healthcheck-client.key | etcd/healthcheck-client.crt | etcdctl | --key | --cert | +| Default CN | recommended key path | recommended cert path | command | key argument | cert argument | +|------------------------------|------------------------------|-----------------------------|-------------------------|------------------------------|-------------------------------------------| +| etcd-ca | etcd/ca.key | etcd/ca.crt | kube-apiserver | | --etcd-cafile | +| kube-apiserver-etcd-client | apiserver-etcd-client.key | apiserver-etcd-client.crt | kube-apiserver | --etcd-keyfile | --etcd-certfile | +| kubernetes-ca | ca.key | ca.crt | kube-apiserver | | --client-ca-file | +| kubernetes-ca | ca.key | ca.crt | kube-controller-manager | --cluster-signing-key-file | --client-ca-file, --root-ca-file, --cluster-signing-cert-file | +| kube-apiserver | apiserver.key | apiserver.crt | kube-apiserver | --tls-private-key-file | --tls-cert-file | +| kube-apiserver-kubelet-client| apiserver-kubelet-client.key | apiserver-kubelet-client.crt| kube-apiserver | --kubelet-client-key | --kubelet-client-certificate | +| front-proxy-ca | front-proxy-ca.key | front-proxy-ca.crt | kube-apiserver | | --requestheader-client-ca-file | +| front-proxy-ca | front-proxy-ca.key | front-proxy-ca.crt | kube-controller-manager | | --requestheader-client-ca-file | +| front-proxy-client | front-proxy-client.key | front-proxy-client.crt | kube-apiserver | --proxy-client-key-file | --proxy-client-cert-file | +| etcd-ca | etcd/ca.key | etcd/ca.crt | etcd | | --trusted-ca-file, --peer-trusted-ca-file | +| kube-etcd | etcd/server.key | etcd/server.crt | etcd | --key-file | --cert-file | +| kube-etcd-peer | etcd/peer.key | etcd/peer.crt | etcd | --peer-key-file | --peer-cert-file | +| etcd-ca | | etcd/ca.crt | etcdctl | | --cacert | +| kube-etcd-healthcheck-client | etcd/healthcheck-client.key | etcd/healthcheck-client.crt | etcdctl | --key | --cert | Same considerations apply for the service account key pair: -| private key path | public key path | command | argument | -|------------------------------|-----------------------------|-------------------------|--------------------------------------| -| sa.key | | kube-controller-manager | --service-account-private-key-file | -| | sa.pub | kube-apiserver | --service-account-key-file | +| private key path | public key path | command | argument | +|-------------------|------------------|-------------------------|--------------------------------------| +| sa.key | | kube-controller-manager | --service-account-private-key-file | +| | sa.pub | kube-apiserver | --service-account-key-file | -The following example illustrates the file paths [from the previous tables](/docs/setup/best-practices/certificates/#certificate-paths) you need to provide if you are generating all of your own keys and certificates: +The following example illustrates the file paths [from the previous tables](#certificate-paths) +you need to provide if you are generating all of your own keys and certificates: ``` /etc/kubernetes/pki/etcd/ca.key @@ -172,15 +184,17 @@ The following example illustrates the file paths [from the previous tables](/doc You must manually configure these administrator account and service accounts: -| filename | credential name | Default CN | O (in Subject) | -|-------------------------|----------------------------|--------------------------------|----------------| -| admin.conf | default-admin | kubernetes-admin | system:masters | +| filename | credential name | Default CN | O (in Subject) | +|-------------------------|----------------------------|-------------------------------------|----------------| +| admin.conf | default-admin | kubernetes-admin | system:masters | | kubelet.conf | default-auth | system:node:`` (see note) | system:nodes | -| controller-manager.conf | default-controller-manager | system:kube-controller-manager | | -| scheduler.conf | default-scheduler | system:kube-scheduler | | +| controller-manager.conf | default-controller-manager | system:kube-controller-manager | | +| scheduler.conf | default-scheduler | system:kube-scheduler | | {{< note >}} -The value of `` for `kubelet.conf` **must** match precisely the value of the node name provided by the kubelet as it registers with the apiserver. For further details, read the [Node Authorization](/docs/reference/access-authn-authz/node/). +The value of `` for `kubelet.conf` **must** match precisely the value of the node name +provided by the kubelet as it registers with the apiserver. For further details, read the +[Node Authorization](/docs/reference/access-authn-authz/node/). {{< /note >}} 1. For each config, generate an x509 cert/key pair with the given CN and O. @@ -198,7 +212,7 @@ These files are used as follows: | filename | command | comment | |-------------------------|-------------------------|-----------------------------------------------------------------------| -| admin.conf | kubectl | Configures administrator user for the cluster | +| 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` |