From f88c8e31917f6c8b8db887317bd6c656f97a27d5 Mon Sep 17 00:00:00 2001 From: Fabrizio Pandini Date: Wed, 23 Oct 2019 17:56:15 +0200 Subject: [PATCH] Improve PKI certificates and requirements page (#16399) * improve-pki-page * address comments --- .../docs/setup/best-practices/certificates.md | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/content/en/docs/setup/best-practices/certificates.md b/content/en/docs/setup/best-practices/certificates.md index e0772f0158..1e8e36c254 100644 --- a/content/en/docs/setup/best-practices/certificates.md +++ b/content/en/docs/setup/best-practices/certificates.md @@ -56,9 +56,11 @@ 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][proxy] | +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`. + ### All certificates -If you don't wish to copy these private keys to your API servers, you can generate all certificates yourself. +If you don't wish to copy the CA private keys to your cluster, you can generate all certificates yourself. Required certificates: @@ -72,7 +74,8 @@ Required certificates: | 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` +[1]: any other IP or DNS name you contact your cluster on (as used by [kubeadm][kubeadm] the load balancer stable IP and/or DNS name, `kubernetes`, `kubernetes.default`, `kubernetes.default.svc`, +`kubernetes.default.svc.cluster`, `kubernetes.default.svc.cluster.local`) where `kind` maps to one or more of the [x509 key usage][usage] types: @@ -81,6 +84,19 @@ where `kind` maps to one or more of the [x509 key usage][usage] types: | server | digital signature, key encipherment, server auth | | 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. +{{< /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 geneerated 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 >}} + ### 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. @@ -90,18 +106,24 @@ Certificates should be placed in a recommended path (as used by [kubeadm][kubead | etcd-ca | etcd/ca.key | etcd/ca.crt | kube-apiserver | | --etcd-cafile | | 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 | -| apiserver-kubelet-client | apiserver-kubelet-client.key | apiserver-kubelet-client.crt| kube-apiserver | | --kubelet-client-certificate | +| 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[2] | | --cacert | -| kube-etcd-healthcheck-client | etcd/healthcheck-client.key | etcd/healthcheck-client.crt | etcdctl[2] | --key | --cert | +| etcd-ca | | etcd/ca.crt | etcdctl | | --cacert | +| kube-etcd-healthcheck-client | etcd/healthcheck-client.key | etcd/healthcheck-client.crt | etcdctl | --key | --cert | -[2]: For a liveness probe, if self-hosted +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 | +| | sa.pub | kube-apiserver | service-account-key | ## Configure certificates for user accounts