From f4eaedf0d3537497c439200a46bc7961b8618ecf Mon Sep 17 00:00:00 2001 From: zaunist Date: Sun, 15 May 2022 02:12:13 +0800 Subject: [PATCH] docs: Rsyc content/zh/docs/setup/production-environment/tools/kubeadm --- .../docs/setup/best-practices/certificates.md | 82 +++++- .../tools/kubeadm/create-cluster-kubeadm.md | 250 +++++++++++++----- .../tools/kubeadm/kubelet-integration.md | 53 ++-- 3 files changed, 274 insertions(+), 111 deletions(-) diff --git a/content/zh/docs/setup/best-practices/certificates.md b/content/zh/docs/setup/best-practices/certificates.md index f8a79245c0..bb96a887f6 100644 --- a/content/zh/docs/setup/best-practices/certificates.md +++ b/content/zh/docs/setup/best-practices/certificates.md @@ -26,8 +26,6 @@ Kubernetes 需要 PKI 证书才能进行基于 TLS 的身份验证。如果你 则会自动生成集群所需的证书。你还可以生成自己的证书。 例如，不将私钥存储在 API 服务器上，可以让私钥更加安全。此页面说明了集群必需的证书。 - - * Kubelet 的客户端证书，用于 API 服务器身份验证 +* Kubelet [服务端证书](/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/#client-and-serving-certificates)， + 用于 API 服务器与 Kubelet 的会话 * API 服务器端点的证书 * 集群管理员的客户端证书，用于 API 服务器身份认证 * API 服务器的客户端证书，用于和 Kubelet 的会话 @@ -75,20 +77,25 @@ etcd 还实现了双向 TLS 来对客户端和对其他对等节点进行身份 ## 证书存放的位置 -如果你是通过 kubeadm 安装的 Kubernetes，所有证书都存放在 `/etc/kubernetes/pki` 目录下。本文所有相关的路径都是基于该路径的相对路径。 +假如通过 kubeadm 安装 Kubernetes，大多数证书都存储在 `/etc/kubernetes/pki`。 +本文档中的所有路径都是相对于该目录的，但用户账户证书除外，kubeadm 将其放在 `/etc/kubernetes` 中。 ## 手动配置证书 -如果你不想通过 kubeadm 生成这些必需的证书，你可以通过下面两种方式之一来手动创建他们。 +如果你不想通过 kubeadm 生成这些必需的证书，你可以使用一个单一的根 CA +来创建这些证书或者直接提供所有证书。 +参见[证书](/zh/docs/tasks/administer-cluster/certificates/)以进一步了解创建自己的证书机构。 +关于管理证书的更多信息，请参见[使用 kubeadm 进行证书管理](/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-certs/)。 +下面的例子说明了上表中所示的 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 +``` + [1]: 用来连接到集群的不同 IP 或 DNS 名 （就像 [kubeadm](/zh/docs/reference/setup-tools/kubeadm/) 为负载均衡所使用的固定 IP 或 DNS 名，`kubernetes`、`kubernetes.default`、`kubernetes.default.svc`、 `kubernetes.default.svc.cluster`、`kubernetes.default.svc.cluster.local`）。 -其中，`kind` 对应一种或多种类型的 [x509 密钥用途](https://godoc.org/k8s.io/api/certificates/v1beta1#KeyUsage)： +其中，`kind` 对应一种或多种类型的 [x509 密钥用途](https://pkg.go.dev/k8s.io/api/certificates/v1beta1#KeyUsage)： +下面的例子展示了自行生成所有密钥和证书时所需要提供的文件路径。 +这些路径基于[前面的表格](/zh/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 +``` + +下面是前表中所列文件的完整路径。 + +```console +/etc/kubernetes/admin.conf +/etc/kubernetes/kubelet.conf +/etc/kubernetes/controller-manager.conf +/etc/kubernetes/scheduler.conf +``` diff --git a/content/zh/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md b/content/zh/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md index f6364dd169..680d8c4344 100644 --- a/content/zh/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md +++ b/content/zh/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md @@ -49,11 +49,8 @@ as Ansible or Terraform. 一组云服务器，Raspberry Pi 等。无论是部署到云还是本地， 你都可以将 `kubeadm` 集成到预配置系统中，例如 Ansible 或 Terraform。 - - ## {{% heading "prerequisites" %}} - 你还需要使用可以在新集群中部署特定 Kubernetes 版本对应的 `kubeadm`。 - -[Kubernetes 版本及版本倾斜支持策略](/zh/docs/setup/release/version-skew-policy/#supported-versions) 适用于 `kubeadm` 以及整个 Kubernetes。 +[Kubernetes 版本及版本偏差策略](/zh/docs/setup/release/version-skew-policy/#supported-versions) 适用于 `kubeadm` 以及整个 Kubernetes。 查阅该策略以了解支持哪些版本的 Kubernetes 和 `kubeadm`。 该页面是为 Kubernetes {{< param "version" >}} 编写的。 @@ -102,8 +98,6 @@ Any commands under `kubeadm alpha` are, by definition, supported on an alpha lev 根据定义，在 `kubeadm alpha` 下的所有命令均在 alpha 级别上受支持。 {{< /note >}} - - -### 在你的主机上安装 kubeadm +### 主机准备 -查看 ["安装 kubeadm"](/zh/docs/setup/production-environment/tools/kubeadm/install-kubeadm/)。 +在所有主机上安装 {{< glossary_tooltip term_id="container-runtime" text="容器运行时" >}} 和 kubeadm。 +详细说明和其他前提条件，请参见[安装 kubeadm](/zh/docs/setup/production-environment/tools/kubeadm/install-kubeadm/)。 +1. （推荐）如果计划将单个控制平面 kubeadm 集群升级成高可用， + 你应该指定 `--control-plane-endpoint` 为所有控制平面节点设置共享端点。 + 端点可以是负载均衡器的 DNS 名称或 IP 地址。 +1. 选择一个 Pod 网络插件，并验证是否需要为 `kubeadm init` 传递参数。 + 根据你选择的第三方网络插件，你可能需要设置 `--pod-network-cidr` 的值。 + 请参阅 [安装Pod网络附加组件](#pod-network)。 + + -1. （推荐）如果计划将单个控制平面 kubeadm 集群升级成高可用， -你应该指定 `--control-plane-endpoint` 为所有控制平面节点设置共享端点。 -端点可以是负载均衡器的 DNS 名称或 IP 地址。 -1. 选择一个 Pod 网络插件，并验证是否需要为 `kubeadm init` 传递参数。 -根据你选择的第三方网络插件，你可能需要设置 `--pod-network-cidr` 的值。 -请参阅 [安装Pod网络附加组件](#pod-network)。 -1. （可选）从版本1.14开始，`kubeadm` 尝试使用一系列众所周知的域套接字路径来检测 Linux 上的容器运行时。 -要使用不同的容器运行时， -或者如果在预配置的节点上安装了多个容器，请为 `kubeadm init` 指定 `--cri-socket` 参数。 -请参阅[安装运行时](/zh/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#installing-runtime)。 +1. （可选）`kubeadm` 试图通过使用已知的端点列表来检测容器运行时。 + 或者如果在预配置的节点上安装了多个容器，请为 `kubeadm init` 指定 `--cri-socket` 参数。 + 请参阅[安装运行时](/zh/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#installing-runtime)。 1. （可选）除非另有说明，否则 `kubeadm` 使用与默认网关关联的网络接口来设置此控制平面节点 API server 的广播地址。 -要使用其他网络接口，请为 `kubeadm init` 设置 `--apiserver-advertise-address=` 参数。 -要部署使用 IPv6 地址的 Kubernetes 集群， -必须指定一个 IPv6 地址，例如 `--apiserver-advertise-address=fd00::101` + 要使用其他网络接口，请为 `kubeadm init` 设置 `--apiserver-advertise-address=` 参数。 + 要部署使用 IPv6 地址的 Kubernetes 集群， + 必须指定一个 IPv6 地址，例如 `--apiserver-advertise-address=fd00::101` 这是一个示例映射： -``` +```console 192.168.0.102 cluster-endpoint ``` @@ -302,6 +299,13 @@ To customize control plane components, including optional IPv6 assignment to liv --> 要自定义控制平面组件，包括可选的对控制平面组件和 etcd 服务器的活动探针提供 IPv6 支持，请参阅[自定义参数](/zh/docs/setup/production-environment/tools/kubeadm/control-plane-flags/)。 + +要重新配置一个已经创建的集群，请参见 +[重新配置一个 kubeadm 集群](/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-reconfigure)。 + @@ -314,7 +318,6 @@ have container image support for this architecture. 如果将具有不同架构的节点加入集群， 请确保已部署的 DaemonSet 对这种体系结构具有容器镜像支持。 - kubeadm 对 `admin.conf` 中的证书进行签名时，将其配置为 `Subject: O = system:masters, CN = kubernetes-admin`。 `system:masters` 是一个例外的、超级用户组，可以绕过鉴权层（例如 RBAC）。 不要将 `admin.conf` 文件与任何人共享，应该使用 `kubeadm kubeconfig user` 命令为其他用户生成 kubeconfig 文件，完成对他们的定制授权。 +更多细节请参见[为其他用户生成 kubeconfig 文件](/zh/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users)。 {{< /warning >}} @@ -517,6 +520,26 @@ for `kubeadm`. 如果您的网络无法正常工作或 CoreDNS 不在“运行中”状态，请查看 `kubeadm` 的 [故障排除指南](/zh/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm/)。 + + +### 托管节点标签 {#managed-node-labels} + + +默认情况下，kubeadm 启用 [NodeRestriction](/zh/docs/reference/access-authn-authz/admissiontrollers/#noderestriction) +准入控制器来限制 kubelets 在节点注册时可以应用哪些标签。准入控制器文档描述 kubelet `--node-labels` 选项允许使用哪些标签。 +其中 `node-role.kubernetes.io/control-plane` 标签就是这样一个受限制的标签， +kubeadm 在节点创建后使用特权客户端应用此标签。 +你可以使用一个有特权的 kubeconfig, 比如由 kubeadm 管理的 `/etc/kubernetes/admin.conf`， +通过执行 `kubectl label` 来手动完成操作。 默认情况下，出于安全原因，你的集群不会在控制平面节点上调度 Pod。 -如果你希望能够在控制平面节点上调度 Pod， -例如用于开发的单机 Kubernetes 集群，请运行： +如果你希望能够在控制平面节点上调度 Pod，例如单机 Kubernetes 集群，请运行: ```bash -kubectl taint nodes --all node-role.kubernetes.io/master- +kubectl taint nodes --all node-role.kubernetes.io/control-plane- node-role.kubernetes.io/master- ``` 输出看起来像： -``` +```console node "test-01" untainted -taint "node-role.kubernetes.io/master:" not found -taint "node-role.kubernetes.io/master:" not found ``` 这将从任何拥有 `node-role.kubernetes.io/master` taint 标记的节点中移除该标记， 包括控制平面节点，这意味着调度程序将能够在任何地方调度 Pods。 + + +{{< note >}} +`node-role.kubernetes.io/master` 污点已被废弃，kubeadm 将在 1.25 版本中停止使用它。 +{{< /note >}} 如果没有令牌，可以通过在控制平面节点上运行以下命令来获取令牌： - ```bash kubeadm token list ``` @@ -608,7 +637,6 @@ you can create a new token by running the following command on the control-plane 默认情况下，令牌会在24小时后过期。如果要在当前令牌过期后将节点加入集群， 则可以通过在控制平面节点上运行以下命令来创建新令牌： - ```bash kubeadm token create ``` @@ -652,7 +680,7 @@ The output should look something like: --> 输出应类似于： -``` +```console [preflight] Running pre-flight checks ... (log output of join workflow) ... @@ -672,11 +700,10 @@ nodes` when run on the control-plane node. 几秒钟后，当你在控制平面节点上执行 `kubectl get nodes`，你会注意到该节点出现在输出中。 - {{< note >}} 由于集群节点通常是按顺序初始化的，CoreDNS Pods 很可能都运行在第一个控制面节点上。 为了提供更高的可用性，请在加入至少一个新节点后 @@ -766,7 +793,6 @@ and make sure that the node is empty, then deconfigure the node. 则应首先[清空节点](/docs/reference/generated/kubectl/kubectl-commands#drain)并确保该节点为空， 然后取消配置该节点。 - @@ -840,7 +866,6 @@ options. --> 有关此子命令及其选项的更多信息，请参见[`kubeadm reset`](/zh/docs/reference/setup-tools/kubeadm/kubeadm-reset/)参考文档。 - -## 版本倾斜政策 {#version-skew-policy} +## 版本偏差策略 {#version-skew-policy} -版本 v{{< skew latestVersion >}} 的kubeadm 工具可以使用版本 v{{< skew latestVersion >}} 或 v{{< skew prevMinorVersion >}} 的控制平面部署集群。kubeadm v{{< skew latestVersion >}} 还可以升级现有的 kubeadm 创建的 v{{< skew prevMinorVersion >}} 版本的集群。 +虽然 kubeadm 允许所管理的组件有一定程度的版本偏差， +但是建议你将 kubeadm 的版本与控制平面组件、kube-proxy 和 kubelet 的版本相匹配。 -由于我们不能预见未来，kubeadm CLI v{{< skew latestVersion >}} 可能会或可能无法部署 v{{< skew nextMinorVersion >}} 集群。 + +### kubeadm 中的 Kubernetes 版本偏差 -这些资源提供了有关 kubelet 与控制平面以及其他 Kubernetes 组件之间受支持的版本倾斜的更多信息： +kubeadm 可以与 Kubernetes 组件一起使用，这些组件的版本与 kubeadm 相同，或者比它大一个版本。 +Kubernetes 版本可以通过使用 `--kubeadm init` 的 `--kubernetes-version` 标志或使用 `--config` 时的 +[`ClusterConfiguration.kubernetesVersion`](/zh/docs/reference/configapi/kubeadm-config.v1beta3/) +字段指定给 kubeadm。 +这个选项将控制 kube-apiserver、kube-controller-manager、kube-scheduler 和 kube-proxy 的版本。 -* Kubernetes [版本和版本偏斜政策](/zh/docs/setup/release/version-skew-policy/) -* Kubeadm-specific [安装指南](/zh/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#installing-kubeadm-kubelet-and-kubectl) +例子： +* kubeadm 的版本为 {{< skew latestVersion >}}。 +* `kubernetesVersion` 必须为 {{< skew latestVersion >}} 或者 {{< skew prevMinorVersion >}}。 + +### kubeadm 中 kubelet 的版本偏差 + + +与 Kubernetes 版本类似，kubeadm 可以使用与 kubeadm 相同版本的 kubelet， +或者比 kubeadm 老一个版本的 kubelet。 + + +例子： +* kubeadm 的版本为 {{< skew latestVersion >}} +* 主机上的 kubelet 版本必须为 {{< skew latestVersion >}} 或者 {{< skew prevMinorVersion >}} + + +### kubeadm 支持的 kubeadm 的版本偏差 + + +kubeadm 命令在现有节点或由 kubeadm 管理的整个集群上的操作有一定限制。 + + +如果新的节点加入到集群中，用于 `kubeadm join` 的 kubeadm 二进制文件必须与用 `kubeadm init` +创建集群或用 `kubeadm upgrade` 升级同一节点时所用的 kubeadm 版本一致。 +类似的规则适用于除了 `kubeadm upgrade` 以外的其他 kubeadm 命令。 + + +`kubeadm join` 的例子： +* 使用 `kubeadm init` 创建集群时使用版本为 {{< skew latestVersion >}} 的 kubeadm。 +* 加入的节点必须使用版本为 {{< skew latestVersion >}} 的 kubeadm 二进制文件。 + + +对于正在升级的节点，所使用的的 kubeadm 必须与管理该节点的 kubeadm 具有相同的 +MINOR 版本或比后者新一个 MINOR 版本。 + + +`kubeadm upgrade`的例子: +* 用于创建或升级节点的 kubeadm 版本为 {{< skew prevMinorVersion >}}。 +* 用于升级节点的 kubeadm 版本必须为 {{< skew prevMinorVersion >}} 或 {{< skew latestVersion >}}。 + + +要了解更多关于不同 Kubernetes 组件之间的版本偏差，请参见 +[版本偏差策略](https://kubernetes.io/releases/version-skew-policy/)。 - 此处创建的集群具有单个控制平面节点，运行单个 etcd 数据库。 这意味着如果控制平面节点发生故障，你的集群可能会丢失数据并且可能需要从头开始重新创建。 @@ -1001,5 +1112,4 @@ supports your chosen platform. - 如果你在使用 kubeadm 时遇到困难，请查阅我们的[故障排除文档](/zh/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm/)。 diff --git a/content/zh/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md b/content/zh/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md index 8990ee0acf..1a18ae465d 100644 --- a/content/zh/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md +++ b/content/zh/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md @@ -15,6 +15,8 @@ weight: 80 +{{% dockershim-removal %}} + {{< feature-state for_k8s_version="1.11" state="stable" >}} ### 当使用 `kubeadm init`时的工作流程 -当调用 `kubeadm init` 时，kubelet 配置被编组到磁盘上的 `/var/lib/kubelet/config.yaml` 中， -并且上传到集群中的 ConfigMap。 -ConfigMap 名为 `kubelet-config-1.X`，其中 `X` 是你正在初始化的 kubernetes 版本的次版本。 -在集群中所有 kubelet 的基准集群范围内配置，将 kubelet 配置文件写入 `/etc/kubernetes/kubelet.conf` 中。 +当调用 `kubeadm init` 时，kubelet 的配置会被写入磁盘 `/var/lib/kubelet/config.yaml`， +并上传到集群 `kubee-system` 命名空间的 `kubelet-config` ConfigMap。 +kubelet 配置信息也被写入 `/etc/kubernetes/kubelet.conf`，其中包含集群内所有 kubelet 的基线配置。 此配置文件指向允许 kubelet 与 API 服务器通信的客户端证书。 这解决了[将集群级配置传播到每个 kubelet](#propagating-cluster-level-configuration-to-each-kubelet) 的需求。 @@ -240,7 +236,7 @@ kubeadm 将环境文件写入 `/var/lib/kubelet/kubeadm-flags.env`，其中包 KUBELET_KUBEADM_ARGS="--flag1=value1 --flag2=value2 ..." ``` -除了启动 kubelet 时使用该标志外，该文件还包含动态参数，例如 cgroup 驱动程序以及是否使用其他 CRI 运行时 socket（`--cri-socket`）。 +除了启动 kubelet 时使用该标志外，该文件还包含动态参数，例如 cgroup 驱动程序以及是否使用其他容器运行时 socket（`--cri-socket`）。 将这两个文件编组到磁盘后，如果使用 systemd，则 kubeadm 尝试运行以下两个命令： @@ -255,14 +251,13 @@ systemctl daemon-reload && systemctl restart kubelet When you run `kubeadm join`, kubeadm uses the Bootstrap Token credential to perform a TLS bootstrap, which fetches the credential needed to download the -`kubelet-config-1.X` ConfigMap and writes it to `/var/lib/kubelet/config.yaml`. The dynamic +`kubelet-config` ConfigMap and writes it to `/var/lib/kubelet/config.yaml`. The dynamic environment file is generated in exactly the same way as `kubeadm init`. --> - ### 当使用 `kubeadm join`时的工作流程 当运行 `kubeadm join` 时，kubeadm 使用 Bootstrap Token 证书执行 TLS 引导，该引导会获取一份证书， -该证书需要下载 `kubelet-config-1.X` ConfigMap 并把它写入 `/var/lib/kubelet/config.yaml` 中。 +该证书需要下载 `kubelet-config` ConfigMap 并把它写入 `/var/lib/kubelet/config.yaml` 中。 动态环境文件的生成方式恰好与 `kubeadm init` 完全相同。 - 在 kubelet 加载新配置后，kubeadm 将写入 `/etc/kubernetes/bootstrap-kubelet.conf` KubeConfig 文件中， 该文件包含 CA 证书和引导程序令牌。 kubelet 使用这些证书执行 TLS 引导程序并获取唯一的凭据，该凭据被存储在 `/etc/kubernetes/kubelet.conf` 中。 @@ -289,11 +283,9 @@ kubelet 使用这些证书执行 TLS 引导程序并获取唯一的凭据，该 When the `/etc/kubernetes/kubelet.conf` file is written, the kubelet has finished performing the TLS Bootstrap. Kubeadm deletes the `/etc/kubernetes/bootstrap-kubelet.conf` file after completing the TLS Bootstrap. --> - 当 `/etc/kubernetes/kubelet.conf` 文件被写入后，kubelet 就完成了 TLS 引导过程。 Kubeadm 在完成 TLS 引导过程后将删除 `/etc/kubernetes/bootstrap-kubelet.conf` 文件。 -