diff --git a/docs/reference/certificates.md b/docs/reference/certificates.md new file mode 100644 index 0000000000000..75c238fd01b92 --- /dev/null +++ b/docs/reference/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][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 either 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 | Lets user administer 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