--- title: PKI 证书和要求 content_type: concept weight: 50 --- Kubernetes 需要 PKI 证书才能进行基于 TLS 的身份验证。如果你是使用 [kubeadm](/zh-cn/docs/reference/setup-tools/kubeadm/) 安装的 Kubernetes, 则会自动生成集群所需的证书。 你也可以自己生成证书 --- 例如,不将私钥存储在 API 服务器上, 可以让私钥更加安全。此页面说明了集群必需的证书。 ## 集群是如何使用证书的 {#how-certificates-are-used-by-your-cluster} Kubernetes 需要 PKI 才能执行以下操作: ### 服务器证书 {#server-certificates} * API 服务器端点的证书 * etcd 服务器的服务器证书 * 每个 kubelet 的服务器证书(每个{{< glossary_tooltip text="节点" term_id="node" >}}运行一个 kubelet) * 可选的[前端代理](/zh-cn/docs/tasks/extend-kubernetes/configure-aggregation-layer/)的服务器证书 ### 客户端证书 {#client-certificates} * 针对每个 kubelet 的客户端证书,用于 API 服务器作为 Kubernetes API 的客户端进行身份验证 * 每个 API 服务器的客户端证书,用于向 etcd 进行身份验证 * 控制器管理器与 API 服务器进行安全通信的客户端证书 * 调度程序与 API 服务器进行安全通信的客户端证书 * 客户端证书(每个节点一个),用于 kube-proxy 向 API 服务器进行身份验证 * 集群管理员向 API 服务器进行身份验证的可选客户端证书 * [前端代理](/zh-cn/docs/tasks/extend-kubernetes/configure-aggregation-layer/)的可选客户端证书 ### kubelet 的服务器和客户端证书 {#kubelets-server-and-client-certificates} 为了建立安全连接并向 kubelet 进行身份验证,API 服务器需要客户端证书和密钥对。 在此场景中,证书的使用有两种方法: * 共享证书:kube-apiserver 可以使用与验证其客户端相同的证书和密钥对。 这意味着现有证书(例如 `apiserver.crt` 和 `apiserver.key`)可用于与 kubelet 服务器进行通信。 * 单独的证书:或者,kube-apiserver 可以生成新的客户端证书和密钥对,以验证其与 kubelet 服务器的通信。 在这种情况下,将创建一个名为 `kubelet-client.crt` 的不同证书及其对应的私钥 `kubelet-client.key`。 {{< note >}} 只有当你运行 kube-proxy 并要支持[扩展 API 服务器](/zh-cn/docs/tasks/extend-kubernetes/setup-extension-api-server/)时, 才需要 `front-proxy` 证书。 {{< /note >}} etcd 还实现了双向 TLS 来对客户端和对其他对等节点进行身份验证。 ## 证书存储位置 {#where-certificates-are-stored} 假如你通过 kubeadm 安装 Kubernetes,大多数证书会被存储在 `/etc/kubernetes/pki` 中。 本文档中的所有路径都是相对于该目录的,但用户账号证书除外,kubeadm 将其放在 `/etc/kubernetes` 中。 ## 手动配置证书 {#configure-certificates-manually} 如果你不想通过 kubeadm 生成所需证书,你可以使用一个单根 CA 来创建这些证书,或者直接提供所有证书。 参见[证书](/zh-cn/docs/tasks/administer-cluster/certificates/)以进一步了解如何创建自己的证书授权机构。 更多关于管理证书的信息,请参阅[使用 kubeadm 进行证书管理](/zh-cn/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/)。 ### 单根 CA {#single-root-ca} 你可以创建由管理员控制的单根 CA。这个根 CA 可以创建多个中间 CA, 并将所有进一步的创建委托给 Kubernetes 本身。 需要这些 CA: | 路径 | 默认 CN | 描述 | |------------------------|---------------------------|----------------------------------| | ca.crt、key | kubernetes-ca | Kubernetes 通用 CA | | etcd/ca.crt、key | etcd-ca | 与 etcd 相关的所有功能 | | front-proxy-ca.crt、key | kubernetes-front-proxy-ca | 用于[前端代理](/zh-cn/docs/tasks/extend-kubernetes/configure-aggregation-layer/) | 上面的 CA 之外,还需要获取用于服务账号管理的密钥对,也就是 `sa.key` 和 `sa.pub`。 下面的例子说明了上表中所示的 CA 密钥和证书文件。 ```console /etc/kubernetes/pki/ca.crt /etc/kubernetes/pki/ca.key /etc/kubernetes/pki/etcd/ca.crt /etc/kubernetes/pki/etcd/ca.key /etc/kubernetes/pki/front-proxy-ca.crt /etc/kubernetes/pki/front-proxy-ca.key ``` ### 所有的证书 {#all-certificates} 如果你不想将 CA 的私钥拷贝至你的集群中,你也可以自己生成全部的证书。 需要这些证书: | 默认 CN | 父级 CA |O(位于 Subject 中)| kind | 主机(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 | | client | | | kube-apiserver | kubernetes-ca | | server | ``、``、``[^1] | | kube-apiserver-kubelet-client | kubernetes-ca | system:masters | client | | | front-proxy-client | kubernetes-front-proxy-ca | | client | | {{< note >}} 不使用超级用户组 `system:masters` 来控制 `kube-apiserver-kubelet-client`, 可以使用一个权限较低的组。kubeadm 使用 `kubeadm:cluster-admins` 组来达到这个目的。 {{< /note >}} [^1]: 用来连接到集群的不同 IP 或 DNS 名称 (就像 [kubeadm](/zh-cn/docs/reference/setup-tools/kubeadm/) 为负载均衡所使用的固定 IP 或 DNS 名称:`kubernetes`、`kubernetes.default`、`kubernetes.default.svc`、 `kubernetes.default.svc.cluster`、`kubernetes.default.svc.cluster.local`)。 其中 `kind` 对应一种或多种类型的 x509 密钥用途,也可记录在 [CertificateSigningRequest](/zh-cn/docs/reference/kubernetes-api/authentication-resources/certificate-signing-request-v1#CertificateSigningRequest) 类型的 `.spec.usages` 中: | kind | 密钥用途 | |--------|---------------------------------------------------------------------------------| | server | 数字签名、密钥加密、服务端认证 | | client | 数字签名、密钥加密、客户端认证 | {{< note >}} 上面列出的 Host/SAN 是获取工作集群的推荐配置方式; 如果需要特殊安装,则可以在所有服务器证书上添加其他 SAN。 {{< /note >}} {{< note >}} 对于 kubeadm 用户: * 不使用私钥并将证书复制到集群 CA 的方案,在 kubeadm 文档中将这种方案称为外部 CA。 * 如果将上表与 kubeadm 生成的 PKI 进行比较,你会注意到,如果使用外部 etcd,则不会生成 `kube-etcd`、`kube-etcd-peer` 和 `kube-etcd-healthcheck-client` 证书。 {{< /note >}} ### 证书路径 {#certificate-paths} 证书应放置在建议的路径中(以便 [kubeadm](/zh-cn/docs/reference/setup-tools/kubeadm/) 使用)。无论使用什么位置,都应使用给定的参数指定路径。 | 默认 CN | 建议的密钥路径 | 建议的证书路径 | 命令 | 密钥参数 | 证书参数 | |---------|-------------|--------------|-----|--------|---------| | 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 | 注意事项同样适用于服务账号密钥对: | 私钥路径 | 公钥路径 | 命令 | 参数 | |-------------------|------------------|-------------------------|--------------------------------------| | sa.key | | kube-controller-manager | --service-account-private-key-file | | | sa.pub | kube-apiserver | --service-account-key-file | 下面的例子展示了自行生成所有密钥和证书时所需要提供的文件路径。 这些路径基于[前面的表格](/zh-cn/docs/setup/best-practices/certificates/#certificate-paths)。 ```console /etc/kubernetes/pki/etcd/ca.key /etc/kubernetes/pki/etcd/ca.crt /etc/kubernetes/pki/apiserver-etcd-client.key /etc/kubernetes/pki/apiserver-etcd-client.crt /etc/kubernetes/pki/ca.key /etc/kubernetes/pki/ca.crt /etc/kubernetes/pki/apiserver.key /etc/kubernetes/pki/apiserver.crt /etc/kubernetes/pki/apiserver-kubelet-client.key /etc/kubernetes/pki/apiserver-kubelet-client.crt /etc/kubernetes/pki/front-proxy-ca.key /etc/kubernetes/pki/front-proxy-ca.crt /etc/kubernetes/pki/front-proxy-client.key /etc/kubernetes/pki/front-proxy-client.crt /etc/kubernetes/pki/etcd/server.key /etc/kubernetes/pki/etcd/server.crt /etc/kubernetes/pki/etcd/peer.key /etc/kubernetes/pki/etcd/peer.crt /etc/kubernetes/pki/etcd/healthcheck-client.key /etc/kubernetes/pki/etcd/healthcheck-client.crt /etc/kubernetes/pki/sa.key /etc/kubernetes/pki/sa.pub ``` ## 为用户账号配置证书 {#configure-certificates-for-user-accounts} 你必须手动配置以下管理员账号和服务账号: | 文件名 | 凭据名称 | 默认 CN | O (位于 Subject 中) | |-------------------------|----------------------------|-------------------------------------|------------------------| | admin.conf | default-admin | kubernetes-admin | `` | | super-admin.conf | default-super-admin | kubernetes-super-admin | system:masters | | kubelet.conf | default-auth | system:node:``(参阅注释) | system:nodes | | controller-manager.conf | default-controller-manager | system:kube-controller-manager | | | scheduler.conf | default-scheduler | system:kube-scheduler | | {{< note >}} `kubelet.conf` 中 `` 的值**必须**与 kubelet 向 apiserver 注册时提供的节点名称的值完全匹配。 有关更多详细信息,请阅读[节点授权](/zh-cn/docs/reference/access-authn-authz/node/)。 {{< /note >}} {{< note >}} 在上面的例子中,`` 是实现特定的。 一些工具在默认的 `admin.conf` 中签署证书,以成为 `system:masters` 组的一部分。 `system:masters` 是一个紧急情况下的超级用户组,可以绕过 Kubernetes 的授权层,如 RBAC。 另外,某些工具不会生成单独的 `super-admin.conf` 将证书绑定到这个超级用户组。 kubeadm 在 kubeconfig 文件中生成两个单独的管理员证书。 一个是在 `admin.conf` 中,带有 `Subject: O = kubeadm:cluster-admins, CN = kubernetes-admin`。 `kubeadm:cluster-admins` 是绑定到 `cluster-admin` ClusterRole 的自定义组。 这个文件在所有由 kubeadm 管理的控制平面机器上生成。 另一个是在 `super-admin.conf` 中,具有 `Subject: O = system:masters, CN = kubernetes-super-admin`。 这个文件只在调用了 `kubeadm init` 的节点上生成。 {{< /note >}} 1. 对于每个配置,请都使用给定的通用名称(CN)和组织(O)生成 x509 证书/密钥对。 1. 为每个配置运行下面的 `kubectl` 命令: ```bash KUBECONFIG=<文件名> kubectl config set-cluster default-cluster --server=https://<主机ip>: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 ``` 这些文件用途如下: | 文件名 | 命令 | 说明 | |-------------------------|-------------------------|-----------------------------------------------------------------------| | admin.conf | kubectl | 配置集群的管理员 | | super-admin.conf | kubectl | 为集群配置超级管理员用户 | | kubelet.conf | kubelet | 集群中的每个节点都需要一份 | | controller-manager.conf | kube-controller-manager | 必须添加到 `manifests/kube-controller-manager.yaml` 清单中 | | scheduler.conf | kube-scheduler | 必须添加到 `manifests/kube-scheduler.yaml` 清单中 | 下面是前表中所列文件的完整路径。 ```console /etc/kubernetes/admin.conf /etc/kubernetes/super-admin.conf /etc/kubernetes/kubelet.conf /etc/kubernetes/controller-manager.conf /etc/kubernetes/scheduler.conf ```