whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[zh] Sync English site changes for authentication ref

Browse Source 
Some changes are large because ... the original translator failed to
include the English source. I don't know why those PRs got merged in the
first place.
This commit is contained in:
Qiming Teng
2020-11-28 22:57:30 +08:00
parent ec9bfbd16e
commit b8c9b2fa30
4 changed files with 672 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/zh/docs/reference/access-authn-authz/bootstrap-tokens.md
+228 -61
View File
@@ -1,107 +1,238 @@
---
approvers:
- jbeda
title: 使用启动引导令牌（Bootstrap Tokens）认证
weight: 20
---
{{< toc >}}
<!--
reviewers:
- jbeda
title: Authenticating with Bootstrap Tokens
content_type: concept
weight: 20
-->
## 概述
<!-- overview -->
启动引导令牌是一种简单的持有者令牌（Bearer Token），这种令牌是在新建集群或者在现有集群中添加新节点时使用的。
它被设计成能够支持 [`kubeadm`](/zh/docs/reference/setup-tools/kubeadm/)，但是也可以被用在其他的案例中以便用户在
不使用 `kubeadm` 的情况下启动集群。它也被设计成可以通过 RBAC 策略，结合 [Kubelet TLS
Bootstrapping](/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/) 系统进行工作。
{{< feature-state for_k8s_version="v1.18" state="stable" >}}
启动引导令牌被定义成一个特定类型的 secrets(`bootstrap.kubernetes.io/token`)，并存在于
`kube-system` 命名空间中。然后这些 secrets 会被 API 服务器上的启动引导的认证器读取。
控制器管理器中的控制器 TokenCleaner 能够删除过期的令牌。在节点发现的过程中 Kubernetes 会使用特殊的 ConfigMap 对象。
控制器管理器中的 BootstrapSigner 控制器也会使用启动引导令牌为这类对象生成签名信息。
<!--
Bootstrap tokens are a simple bearer token that is meant to be used when
creating new clusters or joining new nodes to an existing cluster. It was built
to support [kubeadm](/docs/reference/setup-tools/kubeadm/), but can be used in other contexts
for users that wish to start clusters without `kubeadm`. It is also built to
work, via RBAC policy, with the
[Kubelet TLS Bootstrapping](/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/) system.
-->
启动引导令牌是一种简单的持有者令牌（Bearer Token），这种令牌是在新建集群
或者在现有集群中添加新节点时使用的。
它被设计成能够支持 [`kubeadm`](/zh/docs/reference/setup-tools/kubeadm/)，
但是也可以被用在其他的案例中以便用户在不使用 `kubeadm` 的情况下启动集群。
它也被设计成可以通过 RBAC 策略，结合
[Kubelet TLS 启动引导](/zh/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/)
系统进行工作。
目前，启动引导令牌处于 **alpha** 阶段，但是预期也不会有大的突破性变化。
<!-- body -->
<!--
## Bootstrap Tokens Overview
Bootstrap Tokens are defined with a specific type
(`bootstrap.kubernetes.io/token`) of secrets that lives in the `kube-system`
namespace. These Secrets are then read by the Bootstrap Authenticator in the
API Server. Expired tokens are removed with the TokenCleaner controller in the
Controller Manager. The tokens are also used to create a signature for a
specific ConfigMap used in a "discovery" process through a BootstrapSigner
controller.
-->
启动引导令牌被定义成一个特定类型的 Secret （`bootstrap.kubernetes.io/token`），
并存在于 `kube-system` 名字空间中。
这些 Secret 会被 API 服务器上的启动引导认证组件（Bootstrap Authenticator）读取。
控制器管理器中的控制器 TokenCleaner 能够删除过期的令牌。
这些令牌也被用来在节点发现的过程中会使用的一个特殊的 ConfigMap 对象。
BootstrapSigner 控制器也会使用这一 ConfigMap。
<!--
## Token Format
Bootstrap Tokens take the form of `abcdef.0123456789abcdef`. More formally,
they must match the regular expression `[a-z0-9]{6}\.[a-z0-9]{16}`.
The first part of the token is the "Token ID" and is considered public
information. It is used when referring to a token without leaking the secret
part used for authentication. The second part is the "Token Secret" and should
only be shared with trusted parties.
-->
## 令牌格式
启动引导令牌使用 `abcdef.0123456789abcdef` 的形式。
更加规范地说，它们必须符合正则表达式 `[a-z0-9]{6}\.[a-z0-9]{16}`。
令牌的第一部分是 "Token ID" ，它是公共信息。用于引用某个令牌，并确保不会泄露认证所使用的秘密信息。
第二部分是“令牌秘密（Token Secret）”，它应该被共享给收信的第三方。
令牌的第一部分是 "Token ID"，它是一种公开信息，用于引用令牌并确保不会
泄露认证所使用的秘密信息。
第二部分是"令牌秘密（Token Secret）"，它应该被共享给受信的第三方。
## 启用启动引导令牌
所有与启动引导令牌相关的特性在 Kubernetes v1.6 版本中默认都是禁用的。
<!--
## Enabling Bootstrap Token Authentication
你可以在 API 服务器上通过 `--enable-bootstrap-token-auth` 参数启用启动引导令牌。
你可以设置控制管理器的 `--controllers` 参数来启用启动引导令牌相关的控制器，例如 `--controllers=*,tokencleaner,bootstrapsigner` 。
在使用 `kubeadm` 时，这是自动完成的。
The Bootstrap Token authenticator can be enabled using the following flag on the
API server:
-->
## 启用启动引导令牌身份认证 {#enabling-bootstrap-token-authentication}
HTTPS 调用中的令牌是这样使用的：
启动引导令牌认证组件可以通过 API 服务器上的如下标志启用：
```
--enable-bootstrap-token-auth
```
<!--
When enabled, bootstrapping tokens can be used as bearer token credentials to
authenticate requests against the API server.
-->
启动引导令牌被启用后，可以作为持有者令牌的凭据，用于 API 服务器请求的身份认证。
```http
Authorization: Bearer 07401b.f395accd246ae52d
```
<!--
Tokens authenticate as the username `system:bootstrap:<token id>` and are members
of the group `system:bootstrappers`. Additional groups may be specified in the
token's Secret.
## 启动引导令牌的密文格式
Expired tokens can be deleted automatically by enabling the `tokencleaner`
controller on the controller manager.
-->
令牌认证为用户名 `system:bootstrap:<token id>` 并且是组 `system:bootstrappers`
的成员。额外的组信息可以通过令牌的 Secret 来设置。
每个合法的令牌背后对应着 `kube-system` 命名空间中的某个 Secret 对象。
你可以从 [这里](https://git.k8s.io/community/contributors/design-proposals/bootstrap-discovery.md) 找到完整设计文档。
过期的令牌可以通过启用控制器管理器中的 `tokencleaner` 控制器来删除。
这是 secret 看起来的样子。注意，`base64(string)` 表示应该通过 base64 对值进行编码。
这里使用的是未解码的版本以便于阅读。
<!--
## Bootstrap Token Secret Format
Each valid token is backed by a secret in the `kube-system` namespace. You can
find the full design doc
[here](https://github.com/kubernetes/community/blob/{{< param "githubbranch" >}}/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md).
Here is what the secret looks like.
-->
## 启动引导令牌的 Secret 格式 {#bootstrap-token-secret-format}
每个合法的令牌背后对应着 `kube-system` 名字空间中的某个 Secret 对象。
你可以从
[这里](https://github.com/kubernetes/community/blob/{{< param "githubbranch" >}}/contributors/design-proposals/cluster-lifecycle/bootstrap-discovery.md).
找到完整设计文档。
这是 Secret 看起来的样子。
```yaml
apiVersion: v1
kind: Secret
metadata:
# name 必须是 "bootstrap-token-<token id>" 格式的
name: bootstrap-token-07401b
namespace: kube-system
# type 必须是 'bootstrap.kubernetes.io/token'
type: bootstrap.kubernetes.io/token
data:
description: base64(The default bootstrap token generated by 'kubeadm init'.)
token-id: base64(07401b)
stringData:
# 供人阅读的描述，可选。
description: "The default bootstrap token generated by 'kubeadm init'."
# 令牌 ID 和秘密信息，必需。
token-id: 07401b
token-secret: base64(f395accd246ae52d)
expiration: base64(2017-03-10T03:22:11Z)
usage-bootstrap-authentication: base64(true)
usage-bootstrap-signing: base64(true)
# 可选的过期时间字段
expiration: "2017-03-10T03:22:11Z"
# 允许的用法
usage-bootstrap-authentication: "true"
usage-bootstrap-signing: "true"
# 令牌要认证为的额外组，必须以 "system:bootstrappers:" 开头
auth-extra-groups: system:bootstrappers:worker,system:bootstrappers:ingress
```
secret 的类型必须是 `bootstrap.kubernetes.io/token` ，而且名字必须是 `bootstrap-token-<token id>`。
`description` 是人类可读的描述，而不应该是机器可读的信息。令牌 ID 和 Secret 是包含在数据字典中的。
<!--
The type of the secret must be `bootstrap.kubernetes.io/token` and the name must
be `bootstrap-token-<token id>`. It must also exist in the `kube-system`
namespace.
`usage-bootstrap-*` 成员表示这个 secret 的用途。启用时，值必须设置为 `true`。
The `usage-bootstrap-*` members indicate what this secret is intended to be used
for. A value must be set to `true` to be enabled.
-->
Secret 的类型必须是 `bootstrap.kubernetes.io/token`，而且名字必须是 `bootstrap-token-<token id>`。
令牌必须存在于 `kube-system` 名字空间中。
`usage-bootstrap-authentication` 表示令牌可以用于 API 服务器的认证。认证器会以
`system:bootstrap:<Token ID>` 认证。它被包含在 `system:bootstrappers` 组中。
命名和组是故意受限制的，以防止用户在启动引导后再使用这些令牌。
`usage-bootstrap-*` 成员表明这个 Secret 的用途。启用时，值必须设置为 `true`。
`usage-bootstrap-signing` 表示令牌应该被用于 `cluster-info` ConfigMap 的签名，就像下面描述的那样。
<!--
* `usage-bootstrap-authentication` indicates that the token can be used to
authenticate to the API server as a bearer token.
* `usage-bootstrap-signing` indicates that the token may be used to sign the
`cluster-info` ConfigMap as described below.
-->
* `usage-bootstrap-authentication` 表示令牌可以作为持有者令牌用于 API 服务器的身份认证。
* `usage-bootstrap-signing` 表示令牌可被用于 `cluster-info` ConfigMap 的签名，
就像下面描述的那样。
`expiration` 数据成员显示了令牌在失效后到现在的时间。这是遵循 RFC3339 进行编码的 UTC 时间。
TokenCleaner 控制器会删除过期的令牌。
<!--
The `expiration` field controls the expiry of the token. Expired tokens are
rejected when used for authentication and ignored during ConfigMap signing.
The expiry value is encoded as an absolute UTC time using RFC3339. Enable the
`tokencleaner` controller to automatically delete expired tokens.
-->
`expiration` 字段控制令牌的失效期。过期的令牌在用于身份认证时会被拒绝，在用于
ConfigMap 签名时会被忽略。
过期时间值是遵循 RFC3339 进行编码的 UTC 时间。
启用 TokenCleaner 控制器会自动删除过期的令牌。
## 使用 `kubeadm` 管理令牌
<!--
## Token Management with kubeadm
你可以使用 `kubeadm` 工具管理正在运行集群的令牌。它会从 `kubeadm` 创建的集群（`/etc/kubernetes/admin.conf`）
自动抓取默认管理员密码。你可以通过参数 `--kubeconfig` 对下面命令指定一个另外的 kubeconfig 文件抓取密码。
You can use the `kubeadm` tool to manage tokens on a running cluster. See the
[kubeadm token docs](/docs/reference/setup-tools/kubeadm/kubeadm-token/) for details.
-->
## 使用 `kubeadm` 管理令牌 {#token-management-with-kubeadm}
* `kubeadm token list` 列举了令牌，同时显示了它们的过期时间和用途。
* `kubeadm token create` 创建一个新令牌。
* `--description` 设置新令牌的描述。
* `--ttl duration` 设置令牌从“现在”起到过期时间的差值。
默认是 0 ，也就是不过期。
* `--usages` 设置令牌被使用的方式。默认是 `signing,authentication`。用途在上面已经描述。
* `kubeadm token delete <token id>|<token id>.<token secret>` 删除令牌。
令牌可以只用 ID 来确认，也可以用整个令牌的值。如果只用 ID 的情况下，密文不匹配的令牌也会被删除。
你可以使用 `kubeadm` 工具管理运行中集群上的令牌。
参见 [kubeadm token 文档](/zh/docs/reference/setup-tools/kubeadm/kubeadm-token/)
以了解详细信息。
### ConfigMap 签名
<!--
## ConfigMap Signing
除了认证之外，令牌可以用于签名 ConfigMap。这在集群启动过程的早期，在客户端信任 API 服务器之前被使用。
被签名的 ConfigMap 可以通过共享令牌被认证。
In addition to authentication, the tokens can be used to sign a ConfigMap. This
is used early in a cluster bootstrap process before the client trusts the API
server. The signed ConfigMap can be authenticated by the shared token.
被签名的 ConfigMap 是 `cluster-info`，存在于 `kube-public` 命名空间中。
Enable ConfigMap signing by enabling the `bootstrapsigner` controller on the
Controller Manager.
-->
### ConfigMap 签名 {#configmap-signing}
除了身份认证，令牌还可以用于签名 ConfigMap。
这一用法发生在集群启动过程的早期，在客户端信任 API 服务器之前。
被签名的 ConfigMap 可以被共享令牌完成身份认证。
通过在控制器管理器上启用 `bootstrapsigner` 控制器可以启用 ConfigMap 签名特性。
```
--controllers=*,bootstrapsigner
```
<!--
The ConfigMap that is signed is `cluster-info` in the `kube-public` namespace.
The typical flow is that a client reads this ConfigMap while unauthenticated and
ignoring TLS errors. It then validates the payload of the ConfigMap by looking
at a signature embedded in the ConfigMap.
The ConfigMap may look like this:
-->
被签名的 ConfigMap 是 `kube-public` 名字空间中的 `cluster-info`。
典型的工作流中，客户端在未经认证和忽略 TLS 报错的状态下读取这个 ConfigMap。
通过 ConfigMap 中嵌入的签名校验 ConfigMap 的载荷。
通过检查 ConfigMap 中嵌入的签名校验 ConfigMap 的载荷。
ConfigMap 会是这个样子的：
@@ -117,7 +248,7 @@ data:
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: <really long certificate data>
certificate-authority-data: <非常长的证书数据>
server: https://10.138.0.2:6443
name: ""
contexts: []
@@ -127,10 +258,46 @@ data:
users: []
```
<!--
The `kubeconfig` member of the ConfigMap is a config file with just the cluster
information filled out. The key thing being communicated here is the
`certificate-authority-data`. This may be expanded in the future.
-->
ConfigMap 的 `kubeconfig` 成员是一个填好了集群信息的配置文件。
这里主要交换的信息是 `certificate-authority-data`。在将来可能会有扩展。
签名是一个 JWS 签名，使用了 "detached" 模式。为了检验签名，用户应该按照 JWS 规则
（base64 编码而忽略结尾的 `=`）对 `kubeconfig` 的载荷进行编码。完成编码的载荷会被通过插入 JWS 并存在于两个点的中间
，用于形成一个完整的 JWS。可以使用令牌的完整信息（比如 `07401b.f395accd246ae52d`）作为共享密钥，
通过 `HS256` 方式 (HMAC-SHA256) 对 JWS 进行校验。 用户 _必须_ 确保使用了 HS256。
<!--
The signature is a JWS signature using the "detached" mode. To validate the
signature, the user should encode the `kubeconfig` payload according to JWS
rules (base64 encoded while discarding any trailing `=`). That encoded payload
is then used to form a whole JWS by inserting it between the 2 dots. You can
verify the JWS using the `HS256` scheme (HMAC-SHA256) with the full token (e.g.
`07401b.f395accd246ae52d`) as the shared secret. Users _must_ verify that HS256
is used.
-->
签名是一个使用 "detached" 模式生成的 JWS 签名。
为了检验签名，用户应该按照 JWS 规则（base64 编码且丢掉结尾的 `=`）对
`kubeconfig` 的载荷进行编码。完成编码的载荷会被插入到两个句点中间，形成完整的
JWS。你可以使用完整的令牌（比如 `07401b.f395accd246ae52d`）作为共享密钥，
通过 `HS256` 方式 (HMAC-SHA256) 对 JWS 进行校验。
用户 _必须_ 确保使用了 HS256。
{{< warning >}}
<!--
Any party with a bootstrapping token can create a valid signature for that
token. When using ConfigMap signing it's discouraged to share the same token with
many clients, since a compromised client can potentially man-in-the middle another
client relying on the signature to bootstrap TLS trust.
-->
任何拥有了启动引导令牌的主体都可以为该令牌生成一个合法的签名。
当使用 ConfigMap 签名时，非常不建议针对很多客户使用相同的令牌，因为某个被攻击的
客户可能对另一个一来签名来开启 TLS 信任的客户发起中间人攻击。
{{< /warning >}}
<!--
Consult the [kubeadm implementation details](/docs/reference/setup-tools/kubeadm/implementation-details/)
section for more information.
-->
参考 [kubeadm 实现细节](/zh/docs/reference/setup-tools/kubeadm/implementation-details/)
了解更多信息。