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

Switch language name 'zh' to 'zh-cn'

Browse Source 
This is the first step to rename 'zh' to 'zh-cn'. There are several reasons why we rename the language name.

- The upstream docsy theme changed the language name, leading to many warnings during site build;
  The side-effect is that the i18n strings are no longer working.
- We believe renaming the language is the right thing to do, because this move can make room for other variants of Chinese language, such as 'zh-tw', 'zh-sg' etc.

There would be several follow-ups to this PR, such as fixing the intra-site links, adding redirects etc.

We will lock up changes to zh/zh-cn pages for the moment, until this one gets in.

This PR is based on commit cdad0a7342.
This commit is contained in:
Qiming Teng
2022-06-10 20:25:27 +08:00
parent 3d345b1816
commit c52818c03d
1347 changed files with 8 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/zh-cn/docs/tasks/extend-kubernetes/_index.md
+5
View File
@@ -0,0 +1,5 @@
---
title: "扩展 Kubernetes"
description: 了解针对工作环境需要来调整 Kubernetes 集群的进阶方法。
weight: 90
---
content/zh-cn/docs/tasks/extend-kubernetes/configure-aggregation-layer.md
+603
View File
@@ -0,0 +1,603 @@
---
title: 配置聚合层
content_type: task
weight: 10
---
<!--
title: Configure the Aggregation Layer
reviewers:
- lavalamp
- cheftako
- chenopis
content_type: task
weight: 10
-->
<!-- overview -->
<!--
Configuring the [aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) allows the Kubernetes apiserver to be extended with additional APIs, which are not part of the core Kubernetes APIs.
-->
配置[聚合层](/zh/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)
可以允许 Kubernetes apiserver 使用其它 API 扩展，这些 API 不是核心
Kubernetes API 的一部分。
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!--
There are a few setup requirements for getting the aggregation layer working in your environment to support mutual TLS auth between the proxy and extension apiservers. Kubernetes and the kube-apiserver have multiple CAs, so make sure that the proxy is signed by the aggregation layer CA and not by something else, like the Kubernetes general CA.
-->
{{< note >}}
要使聚合层在你的环境中正常工作以支持代理服务器和扩展 apiserver 之间的相互 TLS 身份验证，
需要满足一些设置要求。Kubernetes 和 kube-apiserver 具有多个 CA，
因此请确保代理是由聚合层 CA 签名的，而不是由 Kubernetes 通用 CA 签名的。
{{< /note >}}
<!--
Reusing the same CA for different client types can negatively impact the cluster's ability to function. For more information, see [CA Reusage and Conflicts](#ca-reusage-and-conflicts).
-->
{{< caution >}}
对不同的客户端类型重复使用相同的 CA 会对集群的功能产生负面影响。
有关更多信息，请参见 [CA 重用和冲突](#ca-reusage-and-conflicts)。
{{< /caution >}}
<!-- steps -->
<!--
## Authentication Flow
Unlike Custom Resource Definitions (CRDs), the Aggregation API involves another server - your Extension apiserver - in addition to the standard Kubernetes apiserver. The Kubernetes apiserver will need to communicate with your extension apiserver, and your extension apiserver will need to communicate with the Kubernetes apiserver. In order for this communication to be secured, the Kubernetes apiserver uses x509 certificates to authenticate itself to the extension apiserver.
This section describes how the authentication and authorization flows work, and how to configure them.
-->
## 身份认证流程
与自定义资源定义（CRD）不同，除标准的 Kubernetes apiserver 外，Aggregation API
还涉及另一个服务器：扩展 apiserver。
Kubernetes apiserver 将需要与你的扩展 apiserver 通信，并且你的扩展 apiserver
也需要与 Kubernetes apiserver 通信。
为了确保此通信的安全，Kubernetes apiserver 使用 x509 证书向扩展 apiserver 认证。
本节介绍身份认证和鉴权流程的工作方式以及如何配置它们。
<!--
The high-level flow is as follows:
1. Kubernetes apiserver: authenticate the requesting user and authorize their rights to the requested API path.
2. Kubernetes apiserver: proxy the request to the extension apiserver
3. Extension apiserver: authenticate the request from the Kubernetes apiserver
4. Extension apiserver: authorize the request from the original user
5. Extension apiserver: execute
-->
大致流程如下：
1. Kubernetes apiserver：对发出请求的用户身份认证，并对请求的 API 路径执行鉴权。
2. Kubernetes apiserver：将请求转发到扩展 apiserver
3. 扩展 apiserver：认证来自 Kubernetes apiserver 的请求
4. 扩展 apiserver：对来自原始用户的请求鉴权
5. 扩展 apiserver：执行
<!--
The rest of this section describes these steps in detail.
The flow can be seen in the following diagram.
The source for the above swimlanes can be found in the source of this document.
-->
本节的其余部分详细描述了这些步骤。
该流程可以在下图中看到。
![聚合层认证流程](/images/docs/aggregation-api-auth-flow.png).
以上泳道的来源可以在本文档的源码中找到。
<!--
Swimlanes generated at https://swimlanes.io with the source as follows:
-----BEGIN-----
title: Welcome to swimlanes.io
User -> kube-apiserver / aggregator:
note:
1. The user makes a request to the Kube API server using any recognized credential (e.g. OIDC or client certs)
kube-apiserver / aggregator -> kube-apiserver / aggregator: authentication
note:
2. The Kube API server authenticates the incoming request using any configured authentication methods (e.g. OIDC or client certs)
kube-apiserver / aggregator -> kube-apiserver / aggregator: authorization
note:
3. The Kube API server authorizes the requested URL using any configured authorization method (e.g. RBAC)
kube-apiserver / aggregator -> aggregated apiserver:
note:
4.The aggregator opens a connection to the aggregated API server using `--proxy-client-cert-file`/`--proxy-client-key-file` client certificate/key to secure the channel
5.The aggregator sends the user info from step 1 to the aggregated API server as http headers, as defined by the following flags:
* `--requestheader-username-headers`
* `--requestheader-group-headers`
* `--requestheader-extra-headers-prefix`
aggregated apiserver -> aggregated apiserver: authentication
note:
6. The aggregated apiserver authenticates the incoming request using the auth proxy authentication method:
* verifies the request has a recognized auth proxy client certificate
* pulls user info from the incoming request's http headers
By default, it pulls the configuration information for this from a configmap in the kube-system namespace that is published by the kube-apiserver, containing the info from the `--requestheader-...` flags provided to the kube-apiserver (CA bundle to use, auth proxy client certificate names to allow, http header names to use, etc)
aggregated apiserver -> kube-apiserver / aggregator: authorization
note:
7. The aggregated apiserver authorizes the incoming request by making a SubjectAccessReview call to the kube-apiserver
aggregated apiserver -> aggregated apiserver: admission
note:
8. For mutating requests, the aggregated apiserver runs admission checks. by default, the namespace lifecycle admission plugin ensures namespaced resources are created in a namespace that exists in the kube-apiserver
-----END-----
-->
<!--
在 https://swimlanes.io 生成的泳道，其源码如下：
-----BEGIN-----
title: 认证流程
User -> kube-apiserver / aggregator:
note:
1.用户使用任何公认的凭证（例如 OIDC 或客户端证书）向 Kube Apiserver 发出请求
kube-apiserver / aggregator -> kube-apiserver / aggregator: 认证
note:
2.Kube Apiserver 使用任何配置的身份验证方法（例如 OIDC 或客户端证书）对传入请求认证
kube-apiserver / aggregator -> kube-apiserver / aggregator: 鉴权
note:
3.Kube Apiserver 使用任何配置的鉴权方法（例如 RBAC）对请求的 URL 鉴权
kube-apiserver / aggregator -> 聚合的 apiserver:
note:
4.aggregator 使用 `--proxy-client-cert-file`，`--proxy-client-key-file`
客户端证书/密钥打开与聚合 Apiserver 的连接以保护通道
5.aggregator 将步骤 1 中的用户信息作为 http 标头发送到聚合的 Apiserver，
如以下标志所定义：
* `--requestheader-username-headers`
* `--requestheader-group-headers`
* `--requestheader-extra-headers-prefix`
kube-apiserver / aggregator -> 聚合的 apiserver: 认证
note:
6.聚合的 apiserver 使用代理身份验证方法对传入的请求认证：
* 验证请求是否具有公认的身份验证代理客户端证书
* 从传入请求的 HTTP 标头中提取用户信息
默认情况下，它从 kube-apiserver 发布的 kube-system 命名空间中的 configmap
中获取配置信息，其中包含提供给 kube-apiserver 的`--requestheader-...`
标志中的信息（要使用的 CA 包，要允许的身份验证代理客户端证书名称，
要使用的 HTTP 标头名称等）
kube-apiserver / aggregator -> 聚合的 apiserver: 鉴权
note:
7.聚合的 apiserver 通过 SubjectAccessReview 请求 kube-apiserver 鉴权
kube-apiserver / aggregator -> 聚合的 apiserver: 准入
note:
8.对于可变请求，聚合的 apiserver 运行准入检查。
默认情况下，namespace 生命周期准入插件可确保在 kube-apiserver
中存在的 namespace 中创建指定 namespace 下的资源
-----END-----
-->
<!--
### Kubernetes Apiserver Authentication and Authorization
A request to an API path that is served by an extension apiserver begins the same way as all API requests: communication to the Kubernetes apiserver. This path already has been registered with the Kubernetes apiserver by the extension apiserver.
The user communicates with the Kubernetes apiserver, requesting access to the path. The Kubernetes apiserver uses standard authentication and authorization configured with the Kubernetes apiserver to authenticate the user and authorize access to the specific path.
For an overview of authenticating to a Kubernetes cluster, see ["Authenticating to a Cluster"](/docs/reference/access-authn-authz/authentication/). For an overview of authorization of access to Kubernetes cluster resources, see ["Authorization Overview"](/docs/reference/access-authn-authz/authorization/).
Everything to this point has been standard Kubernetes API requests, authentication and authorization.
The Kubernetes apiserver now is prepared to send the request to the extension apiserver.
-->
### Kubernetes Apiserver 认证和授权
由扩展 apiserver 服务的对 API 路径的请求以与所有 API 请求相同的方式开始：
与 Kubernetes apiserver 的通信。该路径已通过扩展 apiserver 在
Kubernetes apiserver 中注册。
用户与 Kubernetes apiserver 通信，请求访问路径。
Kubernetes apiserver 使用它的标准认证和授权配置来对用户认证，以及对特定路径的鉴权。
有关对 Kubernetes 集群认证的概述，请参见
[对集群认证](/zh/docs/reference/access-authn-authz/authentication/)。
有关对Kubernetes集群资源的访问鉴权的概述，请参见
[鉴权概述](/zh/docs/reference/access-authn-authz/authorization/)。
到目前为止，所有内容都是标准的 Kubernetes API 请求，认证与鉴权。
Kubernetes apiserver 现在准备将请求发送到扩展 apiserver。
<!--
### Kubernetes Apiserver Proxies the Request
The Kubernetes apiserver now will send, or proxy, the request to the extension apiserver that registered to handle the request. In order to do so, it needs to know several things:
1. How should the Kubernetes apiserver authenticate to the extension apiserver, informing the extension apiserver that the request, which comes over the network, is coming from a valid Kubernetes apiserver?
2. How should the Kubernetes apiserver inform the extension apiserver of the username and group for which the original request was authenticated?
In order to provide for these two, you must configure the Kubernetes apiserver using several flags.
-->
### Kubernetes Apiserver 代理请求
Kubernetes apiserver 现在将请求发送或代理到注册以处理该请求的扩展 apiserver。
为此，它需要了解几件事：
1. Kubernetes apiserver 应该如何向扩展 apiserver 认证，以通知扩展
apiserver 通过网络发出的请求来自有效的 Kubernetes apiserver？
2. Kubernetes apiserver 应该如何通知扩展 apiserver 原始请求
已通过认证的用户名和组？
为提供这两条信息，你必须使用若干标志来配置 Kubernetes apiserver。
<!--
#### Kubernetes Apiserver Client Authentication
The Kubernetes apiserver connects to the extension apiserver over TLS, authenticating itself using a client certificate. You must provide the following to the Kubernetes apiserver upon startup, using the provided flags:
* private key file via `--proxy-client-key-file`
* signed client certificate file via `--proxy-client-cert-file`
* certificate of the CA that signed the client certificate file via `--requestheader-client-ca-file`
* valid Common Names (CN) in the signed client certificate via `--requestheader-allowed-names`
-->
#### Kubernetes Apiserver 客户端认证
Kubernetes apiserver 通过 TLS 连接到扩展 apiserver，并使用客户端证书认证。
你必须在启动时使用提供的标志向 Kubernetes apiserver 提供以下内容：
* 通过 `--proxy-client-key-file` 指定私钥文件
* 通过 `--proxy-client-cert-file` 签名的客户端证书文件
* 通过 `--requestheader-client-ca-file` 签署客户端证书文件的 CA 证书
* 通过 `--requestheader-allowed-names` 在签署的客户证书中有效的公用名（CN）
<!--
The Kubernetes apiserver will use the files indicated by `--proxy-client-*-file` to authenticate to the extension apiserver. In order for the request to be considered valid by a compliant extension apiserver, the following conditions must be met:
1. The connection must be made using a client certificate that is signed by the CA whose certificate is in `--requestheader-client-ca-file`.
2. The connection must be made using a client certificate whose CN is one of those listed in `--requestheader-allowed-names`. **Note:** You can set this option to blank as `--requestheader-allowed-names=""`. This will indicate to an extension apiserver that _any_ CN is acceptable.
-->
Kubernetes apiserver 将使用由 `--proxy-client-*-file` 指示的文件来验证扩展 apiserver。
为了使合规的扩展 apiserver 能够将该请求视为有效，必须满足以下条件：
1. 连接必须使用由 CA 签署的客户端证书，该证书的证书位于 `--requestheader-client-ca-file` 中。
2. 连接必须使用客户端证书，该客户端证书的 CN 是 `--requestheader-allowed-names` 中列出的证书之一。
{{< note >}}
你可以将此选项设置为空白，即为`--requestheader-allowed-names`。
这将向扩展 apiserver 指示任何 CN 是可接受的。
{{< /note >}}
<!--
When started with these options, the Kubernetes apiserver will:
1. Use them to authenticate to the extension apiserver.
2. Create a configmap in the `kube-system` namespace called `extension-apiserver-authentication`, in which it will place the CA certificate and the allowed CNs. These in turn can be retrieved by extension apiservers to validate requests.
Note that the same client certificate is used by the Kubernetes apiserver to authenticate against _all_ extension apiservers. It does not create a client certificate per extension apiserver, but rather a single one to authenticate as the Kubernetes apiserver. This same one is reused for all extension apiserver requests.
-->
使用这些选项启动时，Kubernetes apiserver 将：
1. 使用它们向扩展 apiserver 认证。
2. 在 `kube-system` 命名空间中
创建一个名为 `extension-apiserver-authentication` 的 ConfigMap，
它将在其中放置 CA 证书和允许的 CN。
反过来，扩展 apiserver 可以检索这些内容以验证请求。
请注意，Kubernetes apiserver 使用相同的客户端证书对所有扩展 apiserver 认证。
它不会为每个扩展 apiserver 创建一个客户端证书，而是创建一个证书作为
Kubernetes apiserver 认证。所有扩展 apiserver 请求都重复使用相同的请求。
<!--
#### Original Request Username and Group
When the Kubernetes apiserver proxies the request to the extension apiserver, it informs the extension apiserver of the username and group with which the original request successfully authenticated. It provides these in http headers of its proxied request. You must inform the Kubernetes apiserver of the names of the headers to be used.
* the header in which to store the username via `-requestheader-username-headers`
* the header in which to store the group via `-requestheader-group-headers`
* the prefix to append to all extra headers via `-requestheader-extra-headers-prefix`
These header names are also placed in the `extension-apiserver-authentication` configmap, so they can be retrieved and used by extension apiservers.
-->
#### 原始请求用户名和组
当 Kubernetes apiserver 将请求代理到扩展 apiserver 时，
它将向扩展 apiserver 通知原始请求已成功通过其验证的用户名和组。
它在其代理请求的 HTTP 头部中提供这些。你必须将要使用的标头名称告知
Kubernetes apiserver。
* 通过`--requestheader-username-headers` 标明用来保存用户名的头部
* 通过`--requestheader-group-headers` 标明用来保存 group 的头部
* 通过`--requestheader-extra-headers-prefix` 标明用来保存拓展信息前缀的头部
这些头部名称也放置在 `extension-apiserver-authentication` ConfigMap 中，
因此扩展 apiserver 可以检索和使用它们。
<!--
### Extension Apiserver Authenticates the Request
The extension apiserver, upon receiving a proxied request from the Kubernetes apiserver, must validate that the request actually did come from a valid authenticating proxy, which role the Kubernetes apiserver is fulfilling. The extension apiserver validates it via:
1. Retrieve the following from the configmap in `kube-system`, as described above:
* Client CA certificate
* List of allowed names (CNs)
* Header names for username, group and extra info
2. Check that the TLS connection was authenticated using a client certificate which:
* Was signed by the CA whose certificate matches the retrieved CA certificate.
* Has a CN in the list of allowed CNs, unless the list is blank, in which case all CNs are allowed.
* Extract the username and group from the appropriate headers
-->
### 扩展 Apiserver 认证
扩展 apiserver 在收到来自 Kubernetes apiserver 的代理请求后，
必须验证该请求确实确实来自有效的身份验证代理，
该认证代理由 Kubernetes apiserver 履行。扩展 apiserver 通过以下方式对其认证：
1. 如上所述，从`kube-system`中的 configmap 中检索以下内容：
* 客户端 CA 证书
* 允许名称（CN）列表
* 用户名，组和其他信息的头部
2. 使用以下证书检查 TLS 连接是否已通过认证：
* 由其证书与检索到的 CA 证书匹配的 CA 签名。
* 在允许的 CN 列表中有一个 CN，除非列表为空，在这种情况下允许所有 CN。
* 从适当的头部中提取用户名和组
<!--
If the above passes, then the request is a valid proxied request from a legitimate authenticating proxy, in this case the Kubernetes apiserver.
Note that it is the responsibility of the extension apiserver implementation to provide the above. Many do it by default, leveraging the `k8s.io/apiserver/` package. Others may provide options to override it using command-line options.
In order to have permission to retrieve the configmap, an extension apiserver requires the appropriate role. There is a default role named `extension-apiserver-authentication-reader` in the `kube-system` namespace which can be assigned.
-->
如果以上均通过，则该请求是来自合法认证代理（在本例中为 Kubernetes apiserver）
的有效代理请求。
请注意，扩展 apiserver 实现负责提供上述内容。
默认情况下，许多扩展 apiserver 实现利用 `k8s.io/apiserver/` 软件包来做到这一点。
也有一些实现可能支持使用命令行选项来覆盖这些配置。
为了具有检索 configmap 的权限，扩展 apiserver 需要适当的角色。
在 `kube-system` 名字空间中有一个默认角色
`extension-apiserver-authentication-reader` 可用于设置。
<!--
### Extension Apiserver Authorizes the Request
The extension apiserver now can validate that the user/group retrieved from the headers are authorized to execute the given request. It does so by sending a standard [SubjectAccessReview](/docs/reference/access-authn-authz/authorization/) request to the Kubernetes apiserver.
In order for the extension apiserver to be authorized itself to submit the `SubjectAccessReview` request to the Kubernetes apiserver, it needs the correct permissions. Kubernetes includes a default `ClusterRole` named `system:auth-delegator` that has the appropriate permissions. It can be granted to the extension apiserver's service account.
-->
### 扩展 Apiserver 对请求鉴权
扩展 apiserver 现在可以验证从标头检索的`user/group`是否有权执行给定请求。
通过向 Kubernetes apiserver 发送标准
[SubjectAccessReview](/zh/docs/reference/access-authn-authz/authorization/) 请求来实现。
为了使扩展 apiserver 本身被鉴权可以向 Kubernetes apiserver 提交 SubjectAccessReview 请求，
它需要正确的权限。
Kubernetes 包含一个具有相应权限的名为 `system:auth-delegator` 的默认 `ClusterRole`，
可以将其授予扩展 apiserver 的服务帐户。
<!--
### Extension Apiserver Executes
If the `SubjectAccessReview` passes, the extension apiserver executes the request.
## Enable Kubernetes Apiserver flags
Enable the aggregation layer via the following kube-apiserver flags. They may have already been taken care of by your provider.
-->
### 扩展 Apiserver 执行
如果 `SubjectAccessReview` 通过，则扩展 apiserver 执行请求。
## 启用 Kubernetes Apiserver 标志
通过以下 kube-apiserver 标志启用聚合层。
你的服务提供商可能已经为你完成了这些工作：
```
--requestheader-client-ca-file=<path to aggregator CA cert>
--requestheader-allowed-names=front-proxy-client
--requestheader-extra-headers-prefix=X-Remote-Extra-
--requestheader-group-headers=X-Remote-Group
--requestheader-username-headers=X-Remote-User
--proxy-client-cert-file=<path to aggregator proxy cert>
--proxy-client-key-file=<path to aggregator proxy key>
```
<!--
### CA Reusage and Conflicts
The Kubernetes apiserver has two client CA options:
-->
### CA-重用和冲突 {#ca-reusage-and-conflicts}
Kubernetes apiserver 有两个客户端 CA 选项：
* `--client-ca-file`
* `--requestheader-client-ca-file`
<!--
Each of these functions independently and can conflict with each other, if not used correctly.
* `--client-ca-file`: When a request arrives to the Kubernetes apiserver, if this option is enabled, the Kubernetes apiserver checks the certificate of the request. If it is signed by one of the CA certificates in the file referenced by `--client-ca-file`, then the request is treated as a legitimate request, and the user is the value of the common name `CN=`, while the group is the organization `O=`. See the [documentaton on TLS authentication](/docs/reference/access-authn-authz/authentication/#x509-client-certs).
* `--requestheader-client-ca-file`: When a request arrives to the Kubernetes apiserver, if this option is enabled, the Kubernetes apiserver checks the certificate of the request. If it is signed by one of the CA certificates in the file reference by `--requestheader-client-ca-file`, then the request is treated as a potentially legitimate request. The Kubernetes apiserver then checks if the common name `CN=` is one of the names in the list provided by `--requestheader-allowed-names`. If the name is allowed, the request is approved; if it is not, the request is not.
-->
这些功能中的每个功能都是独立的；如果使用不正确，可能彼此冲突。
* `--client-ca-file`：当请求到达 Kubernetes apiserver 时，如果启用了此选项，
则 Kubernetes apiserver 会检查请求的证书。
如果它是由 `--client-ca-file` 引用的文件中的 CA 证书之一签名的，
并且用户是公用名`CN=`的值，而组是组织`O=` 的取值，则该请求被视为合法请求。
请参阅[关于 TLS 身份验证的文档](/zh/docs/reference/access-authn-authz/authentication/#x509-client-certs)。
* `--requestheader-client-ca-file`：当请求到达 Kubernetes apiserver 时，
如果启用此选项，则 Kubernetes apiserver 会检查请求的证书。
如果它是由文件引用中的 --requestheader-client-ca-file 所签署的 CA 证书之一签名的，
则该请求将被视为潜在的合法请求。
然后，Kubernetes apiserver 检查通用名称 `CN=` 是否是
`--requestheader-allowed-names` 提供的列表中的名称之一。
如果名称允许，则请求被批准；如果不是，则请求被拒绝。
<!--
If _both_ `--client-ca-file` and `--requestheader-client-ca-file` are provided, then the request first checks the `--requestheader-client-ca-file` CA and then the `--client-ca-file`. Normally, different CAs, either root CAs or intermediate CAs, are used for each of these options; regular client requests match against `--client-ca-file`, while aggregation requests match against `--requestheader-client-ca-file`. However, if both use the _same_ CA, then client requests that normally would pass via `--client-ca-file` will fail, because the CA will match the CA in `--requestheader-client-ca-file`, but the common name `CN=` will **not** match one of the acceptable common names in `--requestheader-allowed-names`. This can cause your kubelets and other control plane components, as well as end-users, to be unable to authenticate to the Kubernetes apiserver.
For this reason, use different CA certs for the `--client-ca-file` option - to authorize control plane components and end-users - and the `--requestheader-client-ca-file` option - to authorize aggregation apiserver requests.
-->
如果同时提供了 `--client-ca-file` 和 `--requestheader-client-ca-file`，
则首先检查 `--requestheader-client-ca-file` CA，然后再检查`--client-ca-file`。
通常，这些选项中的每一个都使用不同的 CA（根 CA 或中间 CA）。
常规客户端请求与 `--client-ca-file` 相匹配，而聚合请求要与
`--requestheader-client-ca-file` 相匹配。
但是，如果两者都使用同一个 CA，则通常会通过 `--client-ca-file`
传递的客户端请求将失败，因为 CA 将与 `--requestheader-client-ca-file`
中的 CA 匹配，但是通用名称 `CN=` 将不匹配 `--requestheader-allowed-names`
中可接受的通用名称之一。
这可能导致你的 kubelet 和其他控制平面组件以及最终用户无法向 Kubernetes
apiserver 认证。
因此，请对用于控制平面组件和最终用户鉴权的 `--client-ca-file` 选项和
用于聚合 apiserver 鉴权的 `--requestheader-client-ca-file` 选项使用
不同的 CA 证书。
<!--
Do **not** reuse a CA that is used in a different context unless you understand the risks and the mechanisms to protect the CA's usage.
-->
{{< warning >}}
除非你了解风险和保护 CA 用法的机制，否则 *不要* 重用在不同上下文中使用的 CA。
{{< /warning >}}
<!--
If you are not running kube-proxy on a host running the API server, then you must make sure that the system is enabled with the following `kube-apiserver` flag:
-->
如果你未在运行 API 服务器的主机上运行 kube-proxy，则必须确保使用以下
`kube-apiserver` 标志启用系统：
```
--enable-aggregator-routing=true
```
<!--
### Register APIService objects
You can dynamically configure what client requests are proxied to extension
apiserver. The following is an example registration:
-->
### 注册 APIService 对象
你可以动态配置将哪些客户端请求代理到扩展 apiserver。以下是注册示例：
```yaml
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
name: <注释对象名称>
spec:
group: <扩展 Apiserver 的 API 组名>
version: <扩展 Apiserver 的 API 版本>
groupPriorityMinimum: <APIService 对应组的优先级, 参考 API 文档>
versionPriority: <版本在组中的优先排序, 参考 API 文档>
service:
namespace: <拓展 Apiserver 服务的名字空间>
name: <拓展 Apiserver 服务的名称>
caBundle: <PEM 编码的 CA 证书，用于对 Webhook 服务器的证书签名>
```
<!--
The name of an APIService object must be a valid
[path segment name](/docs/concepts/overview/working-with-objects/names#path-segment-names).
-->
APIService 对象的名称必须是合法的
[路径片段名称](/zh/docs/concepts/overview/working-with-objects/names#path-segment-names)。
<!--
#### Contacting the extension apiserver
Once the Kubernetes apiserver has determined a request should be sent to an extension apiserver,
it needs to know how to contact it.
The `service` stanza is a reference to the service for an extension apiserver.
The service namespace and name are required. The port is optional and defaults to 443.
The path is optional and defaults to "/".
Here is an example of an extension apiserver that is configured to be called on port "1234"
at the subpath "/my-path", and to verify the TLS connection against the ServerName
`my-service-name.my-service-namespace.svc` using a custom CA bundle.
-->
#### 调用扩展 apiserver
一旦 Kubernetes apiserver 确定应将请求发送到扩展 apiserver，
它需要知道如何调用它。
`service` 部分是对扩展 apiserver 的服务的引用。
服务的名字空间和名字是必需的。端口是可选的，默认为 443。
路径配置是可选的，默认为 `/`。
下面是为可在端口 `1234` 上调用的扩展 apiserver 的配置示例
服务位于子路径 `/my-path` 下，并针对 ServerName
`my-service-name.my-service-namespace.svc`
使用自定义的 CA 包来验证 TLS 连接
使用自定义 CA 捆绑包的`my-service-name.my-service-namespace.svc`。
```yaml
apiVersion: apiregistration.k8s.io/v1
kind: APIService
...
spec:
...
service:
namespace: my-service-namespace
name: my-service-name
port: 1234
caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
...
```
## {{% heading "whatsnext" %}}
<!--
* [Setup an extension api-server](/docs/tasks/access-kubernetes-api/setup-extension-api-server/) to work with the aggregation layer.
* For a high level overview, see [Extending the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/).
* Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/).
-->
* 使用聚合层[安装扩展 API 服务器](/zh/docs/tasks/extend-kubernetes/setup-extension-api-server/)。
* 有关高级概述，请参阅[使用聚合层扩展 Kubernetes API](/zh/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)。
* 了解如何[使用自定义资源扩展 Kubernetes API](/zh/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)。
content/zh-cn/docs/tasks/extend-kubernetes/configure-multiple-schedulers.md
+374
View File
@@ -0,0 +1,374 @@
---
title: 配置多个调度器
content_type: task
weight: 20
---
<!--
reviewers:
- davidopp
- madhusudancs
title: Configure Multiple Schedulers
content_type: task
weight: 20
-->
<!-- overview -->
<!--
Kubernetes ships with a default scheduler that is described
[here](/docs/reference/command-line-tools-reference/kube-scheduler/).
If the default scheduler does not suit your needs you can implement your own scheduler.
Moreover, you can even run multiple schedulers simultaneously alongside the default
scheduler and instruct Kubernetes what scheduler to use for each of your pods. Let's
learn how to run multiple schedulers in Kubernetes with an example.
-->
Kubernetes 自带了一个默认调度器，其详细描述请查阅
[这里](/zh/docs/reference/command-line-tools-reference/kube-scheduler/)。
如果默认调度器不适合你的需求，你可以实现自己的调度器。
而且，你甚至可以和默认调度器一起同时运行多个调度器，并告诉 Kubernetes 为每个
Pod 使用哪个调度器。
让我们通过一个例子讲述如何在 Kubernetes 中运行多个调度器。
<!--
A detailed description of how to implement a scheduler is outside the scope of this
document. Please refer to the kube-scheduler implementation in
[pkg/scheduler](https://github.com/kubernetes/kubernetes/tree/master/pkg/scheduler)
in the Kubernetes source directory for a canonical example.
-->
关于实现调度器的具体细节描述超出了本文范围。
请参考 kube-scheduler 的实现，规范示例代码位于
[pkg/scheduler](https://github.com/kubernetes/kubernetes/tree/master/pkg/scheduler)。
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!-- steps -->
<!--
## Package the scheduler
Package your scheduler binary into a container image. For the purposes of this example,
you can use the default scheduler (kube-scheduler) as your second scheduler.
Clone the [Kubernetes source code from GitHub](https://github.com/kubernetes/kubernetes)
and build the source.
-->
## 打包调度器
将调度器可执行文件打包到容器镜像中。出于示例目的，可以使用默认调度器
（kube-scheduler）作为第二个调度器。
克隆 [GitHub 上 Kubernetes 源代码](https://github.com/kubernetes/kubernetes)，
并编译构建源代码。
```shell
git clone https://github.com/kubernetes/kubernetes.git
cd kubernetes
make
```
<!--
Create a container image containing the kube-scheduler binary. Here is the `Dockerfile`
to build the image:
-->
创建一个包含 kube-scheduler 二进制文件的容器镜像。用于构建镜像的 `Dockerfile` 内容如下：
```docker
FROM busybox
ADD ./_output/local/bin/linux/amd64/kube-scheduler /usr/local/bin/kube-scheduler
```
<!--
Save the file as `Dockerfile`, build the image and push it to a registry. This example
pushes the image to
[Google Container Registry (GCR)](https://cloud.google.com/container-registry/).
For more details, please read the GCR
[documentation](https://cloud.google.com/container-registry/docs/).
-->
将文件保存为 `Dockerfile`，构建镜像并将其推送到镜像仓库。
此示例将镜像推送到 [Google 容器镜像仓库（GCR）](https://cloud.google.com/container-registry/)。
有关详细信息，请阅读 GCR [文档](https://cloud.google.com/container-registry/docs/)。
```shell
docker build -t gcr.io/my-gcp-project/my-kube-scheduler:1.0 .
gcloud docker -- push gcr.io/my-gcp-project/my-kube-scheduler:1.0
```
<!--
## Define a Kubernetes Deployment for the scheduler
Now that you have your scheduler in a container image, create a pod
configuration for it and run it in your Kubernetes cluster. But instead of creating a pod
directly in the cluster, you can use a [Deployment](/docs/concepts/workloads/controllers/deployment/)
for this example. A [Deployment](/docs/concepts/workloads/controllers/deployment/) manages a
[Replica Set](/docs/concepts/workloads/controllers/replicaset/) which in turn manages the pods,
thereby making the scheduler resilient to failures. Here is the deployment
config. Save it as `my-scheduler.yaml`:
-->
## 为调度器定义 Kubernetes Deployment
现在将调度器放在容器镜像中，为它创建一个 Pod 配置，并在 Kubernetes 集群中
运行它。但是与其在集群中直接创建一个 Pod，不如使用
[Deployment](/zh/docs/concepts/workloads/controllers/deployment/)。
Deployment 管理一个 [ReplicaSet](/zh/docs/concepts/workloads/controllers/replicaset/)，
ReplicaSet 再管理 Pod，从而使调度器能够免受一些故障的影响。
以下是 Deployment 配置，将其保存为 `my-scheduler.yaml`：
{{< codenew file="admin/sched/my-scheduler.yaml" >}}
<!--
In the above manifest, you use a [KubeSchedulerConfiguration](/docs/reference/scheduling/config/)
to customize the behavior of your scheduler implementation. This configuration has been passed to
the `kube-scheduler` during initialization with the `--config` option. The `my-scheduler-config` ConfigMap stores the configuration file. The Pod of the`my-scheduler` Deployment mounts the `my-scheduler-config` ConfigMap as a volume.
-->
在以上的清单中，你使用 [KubeSchedulerConfiguration](/zh/docs/reference/scheduling/config/)
来自定义调度器实现的行为。当使用 `--config` 选项进行初始化时，该配置被传递到 `kube-scheduler`。
`my-scheduler-config` ConfigMap 存储配置数据。
`my-scheduler` Deployment 的 Pod 将 `my-scheduler-config` ConfigMap 挂载为一个卷。
<!--
In the aforementioned Scheduler Configuration, your scheduler implementation is represented via
a [KubeSchedulerProfile](/docs/reference/config-api/kube-scheduler-config.v1beta3/#kubescheduler-config-k8s-io-v1beta3-KubeSchedulerProfile).
{{< note >}}
To determine if a scheduler is responsible for scheduling a specific Pod, the `spec.schedulerName` field in a
PodTemplate or Pod manifest must match the `schedulerName` field of the `KubeSchedulerProfile`.
All schedulers running in the cluster must have unique names.
{{< /note >}}
-->
在前面提到的调度器配置中，你的调度器通过 [KubeSchedulerProfile](/docs/reference/config-api/kube-scheduler-config.v1beta3/#kubescheduler-config-k8s-io-v1beta3-KubeSchedulerProfile) 进行实现。
{{< note >}}
要确定一个调度器是否可以调度特定的 Pod，PodTemplate 或 Pod 清单中的 `spec.schedulerName`
字段必须匹配 `KubeSchedulerProfile` 中的 `schedulerName` 字段。
所有运行在集群中的调度器必须拥有唯一的名称。
{{< /note >}}
<!--
Also, note that you create a dedicated service account `my-scheduler` and bind the ClusterRole
`system:kube-scheduler` to it so that it can acquire the same privileges as `kube-scheduler`.
-->
还要注意，我们创建了一个专用服务账号 `my-scheduler` 并将集群角色 `system:kube-scheduler`
绑定到它，以便它可以获得与 `kube-scheduler` 相同的权限。
<!--
Please see the
[kube-scheduler documentation](/docs/reference/command-line-tools-reference/kube-scheduler/) for
detailed description of other command line arguments and
[Scheduler Configuration reference](/docs/reference/config-api/kube-scheduler-config.v1beta3/) for
detailed description of other customizable `kube-scheduler` configurations.
-->
请参阅 [kube-scheduler 文档](/docs/reference/command-line-tools-reference/kube-scheduler/)
获取其他命令行参数以及 [Scheduler 配置参考](/docs/reference/config-api/kube-scheduler-config.v1beta3/)
获取自定义 `kube-scheduler` 配置的详细说明。
<!--
## Run the second scheduler in the cluster
In order to run your scheduler in a Kubernetes cluster, create the deployment
specified in the config above in a Kubernetes cluster:
-->
## 在集群中运行第二个调度器
为了在 Kubernetes 集群中运行我们的第二个调度器，在 Kubernetes 集群中创建上面配置中指定的 Deployment：
```shell
kubectl create -f my-scheduler.yaml
```
<!--
Verify that the scheduler pod is running:
-->
验证调度器 Pod 正在运行：
```shell
kubectl get pods --namespace=kube-system
```
输出类似于：
```
NAME READY STATUS RESTARTS AGE
....
my-scheduler-lnf4s-4744f 1/1 Running 0 2m
...
```
<!--
You should see a "Running" my-scheduler pod, in addition to the default kube-scheduler
pod in this list.
-->
此列表中，除了默认的 `kube-scheduler` Pod 之外，你应该还能看到处于 “Running” 状态的
`my-scheduler` Pod。
<!--
### Enable leader election
To run multiple-scheduler with leader election enabled, you must do the following:
Update the following fields for the KubeSchedulerConfiguration in the `my-scheduler-config` ConfigMap in your YAML file:
-->
### 启用领导者选举
要在启用了 leader 选举的情况下运行多调度器，你必须执行以下操作：
更新你的 YAML 文件中的 `my-scheduler-config` ConfigMap 里的 KubeSchedulerConfiguration 相关字段如下：
* `leaderElection.leaderElect` to `true`
* `leaderElection.resourceNamespace` to `<lock-object-namespace>`
* `leaderElection.resourceName` to `<lock-object-name>`
{{< note >}}
<!--
The control plane creates the lock objects for you, but the namespace must already exist.
You can use the `kube-system` namespace.
-->
控制平面会为你创建锁对象，但是命名空间必须已经存在。
你可以使用 `kube-system` 命名空间。
{{< /note >}}
<!--
If RBAC is enabled on your cluster, you must update the `system:kube-scheduler` cluster role.
Add your scheduler name to the resourceNames of the rule applied for `endpoints` and `leases` resources, as in the following example:
-->
如果在集群上启用了 RBAC，则必须更新 `system：kube-scheduler` 集群角色。
将调度器名称添加到应用了 `endpoints` 和 `leases` 资源的规则的 resourceNames 中，如以下示例所示：
```shell
kubectl edit clusterrole system:kube-scheduler
```
{{< codenew file="admin/sched/clusterrole.yaml" >}}
<!--
## Specify schedulers for pods
-->
## 为 Pod 指定调度器
<!--
Now that your second scheduler is running, create some pods, and direct them
to be scheduled by either the default scheduler or the one you deployed.
In order to schedule a given pod using a specific scheduler, specify the name of the
scheduler in that pod spec. Let's look at three examples.
-->
现在第二个调度器正在运行，创建一些 Pod，并指定它们由默认调度器或部署的调度器进行调度。
为了使用特定的调度器调度给定的 Pod，在那个 Pod 的 spec 中指定调度器的名称。让我们看看三个例子。
<!--
- Pod spec without any scheduler name
-->
- Pod spec 没有任何调度器名称
{{< codenew file="admin/sched/pod1.yaml" >}}
<!--
When no scheduler name is supplied, the pod is automatically scheduled using the
default-scheduler.
-->
如果未提供调度器名称，则会使用 default-scheduler 自动调度 pod。
<!--
Save this file as `pod1.yaml` and submit it to the Kubernetes cluster.
-->
将此文件另存为 `pod1.yaml`，并将其提交给 Kubernetes 集群。
```shell
kubectl create -f pod1.yaml
```
<!--
- Pod spec with `default-scheduler`
-->
- Pod spec 设置为 `default-scheduler`
{{< codenew file="admin/sched/pod2.yaml" >}}
<!--
A scheduler is specified by supplying the scheduler name as a value to `spec.schedulerName`. In this case, we supply the name of the
default scheduler which is `default-scheduler`.
-->
通过将调度器名称作为 `spec.schedulerName` 参数的值来指定调度器。
在这种情况下，我们提供默认调度器的名称，即 `default-scheduler`。
<!--
Save this file as `pod2.yaml` and submit it to the Kubernetes cluster.
-->
将此文件另存为 `pod2.yaml`，并将其提交给 Kubernetes 集群。
```shell
kubectl create -f pod2.yaml
```
<!--
- Pod spec with `my-scheduler`
-->
- Pod spec 设置为 `my-scheduler`
{{< codenew file="admin/sched/pod3.yaml" >}}
<!--
In this case, we specify that this pod should be scheduled using the scheduler that we
deployed - `my-scheduler`. Note that the value of `spec.schedulerName` should match the name supplied for the scheduler
in the `schedulerName` field of the mapping `KubeSchedulerProfile`.
-->
在这种情况下，我们指定此 Pod 使用我们部署的 `my-scheduler` 来调度。
请注意，`spec.schedulerName` 参数的值应该与调度器提供的 `KubeSchedulerProfile` 中的 `schedulerName` 字段相匹配。
<!--
Save this file as `pod3.yaml` and submit it to the Kubernetes cluster.
-->
将此文件另存为 `pod3.yaml`，并将其提交给 Kubernetes 集群。
```shell
kubectl create -f pod3.yaml
```
<!--
Verify that all three pods are running.
-->
确认所有三个 pod 都在运行。
```shell
kubectl get pods
```
<!-- discussion -->
<!--
### Verifying that the pods were scheduled using the desired schedulers
-->
### 验证是否使用所需的调度器调度了 pod
<!--
In order to make it easier to work through these examples, we did not verify that the
pods were actually scheduled using the desired schedulers. We can verify that by
changing the order of pod and deployment config submissions above. If we submit all the
pod configs to a Kubernetes cluster before submitting the scheduler deployment config,
we see that the pod `annotation-second-scheduler` remains in "Pending" state forever
while the other two pods get scheduled. Once we submit the scheduler deployment config
and our new scheduler starts running, the `annotation-second-scheduler` pod gets
scheduled as well.
-->
为了更容易地完成这些示例，我们没有验证 Pod 实际上是使用所需的调度程序调度的。
我们可以通过更改 Pod 的顺序和上面的部署配置提交来验证这一点。
如果我们在提交调度器部署配置之前将所有 Pod 配置提交给 Kubernetes 集群，
我们将看到注解了 `annotation-second-scheduler` 的 Pod 始终处于 “Pending” 状态，
而其他两个 Pod 被调度。
一旦我们提交调度器部署配置并且我们的新调度器开始运行，注解了
`annotation-second-scheduler` 的 pod 就能被调度。
<!--
Alternatively, you can look at the "Scheduled" entries in the event logs to
verify that the pods were scheduled by the desired schedulers.
-->
或者，可以查看事件日志中的 “Scheduled” 条目，以验证是否由所需的调度器调度了 Pod。
```shell
kubectl get events
```
<!--
You can also use a [custom scheduler configuration](/docs/reference/scheduling/config/#multiple-profiles)
or a custom container image for the cluster's main scheduler by modifying its static pod manifest
on the relevant control plane nodes.
-->
你也可以使用[自定义调度器配置](/zh/docs/reference/scheduling/config/#multiple-profiles)
或自定义容器镜像，用于集群的主调度器，方法是在相关控制平面节点上修改其静态 pod 清单。
content/zh-cn/docs/tasks/extend-kubernetes/custom-resources/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: "使用自定义资源"
weight: 10
---
content/zh-cn/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md
+1437
View File
File diff suppressed because it is too large Load Diff
content/zh-cn/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md
+2700
View File
File diff suppressed because it is too large Load Diff
content/zh-cn/docs/tasks/extend-kubernetes/http-proxy-access-api.md
+128
View File
@@ -0,0 +1,128 @@
---
title: 使用 HTTP 代理访问 Kubernetes API
content_type: task
weight: 40
---
<!--
---
title: Use an HTTP Proxy to Access the Kubernetes API
content_type: task
weight: 40
---
-->
<!-- overview -->
<!--
This page shows how to use an HTTP proxy to access the Kubernetes API.
-->
本文说明如何使用 HTTP 代理访问 Kubernetes API。
## {{% heading "prerequisites" %}}
* {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!--
* If you do not already have an application running in your cluster, start
a Hello world application by entering this command:
-->
* 如果你的集群中还没有任何应用，使用如下命令启动一个 Hello World 应用：
```shell
kubectl create deployment node-hello --image=gcr.io/google-samples/node-hello:1.0 --port=8080
```
<!-- steps -->
<!--
## Using kubectl to start a proxy server
-->
## 使用 kubectl 启动代理服务器
<!--
This command starts a proxy to the Kubernetes API server:
-->
使用如下命令启动 Kubernetes API 服务器的代理：
kubectl proxy --port=8080
<!--
## Exploring the Kubernetes API
-->
## 探究 Kubernetes API
<!--
When the proxy server is running, you can explore the API using `curl`, `wget`,
or a browser.
-->
当代理服务器在运行时，你可以通过 `curl`、`wget` 或者浏览器访问 API。
<!--
Get the API versions:
-->
获取 API 版本：
curl http://localhost:8080/api/
<!--
The output should look similar to this:
-->
输出应该类似这样：
{
"kind": "APIVersions",
"versions": [
"v1"
],
"serverAddressByClientCIDRs": [
{
"clientCIDR": "0.0.0.0/0",
"serverAddress": "10.0.2.15:8443"
}
]
}
<!--
Get a list of pods:
-->
获取 Pod 列表：
curl http://localhost:8080/api/v1/namespaces/default/pods
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {
"resourceVersion": "33074"
},
"items": [
{
"metadata": {
"name": "kubernetes-bootcamp-2321272333-ix8pt",
"generateName": "kubernetes-bootcamp-2321272333-",
"namespace": "default",
"uid": "ba21457c-6b1d-11e6-85f7-1ef9f1dab92b",
"resourceVersion": "33003",
"creationTimestamp": "2016-08-25T23:43:30Z",
"labels": {
"pod-template-hash": "2321272333",
"run": "kubernetes-bootcamp"
},
...
}
## {{% heading "whatsnext" %}}
<!--
Learn more about [kubectl proxy](/docs/reference/generated/kubectl/kubectl-commands#proxy).
-->
想了解更多信息，请参阅 [kubectl 代理](/docs/reference/generated/kubectl/kubectl-commands#proxy)。
content/zh-cn/docs/tasks/extend-kubernetes/setup-extension-api-server.md
+116
View File
@@ -0,0 +1,116 @@
---
title: 安装一个扩展的 API server
content_type: task
weight: 15
---
<!--
title: Setup an extension API server
reviewers:
- lavalamp
- cheftako
- chenopis
content_type: task
weight: 15
-->
<!-- overview -->
<!--
Setting up an extension API server to work the aggregation layer allows the Kubernetes apiserver to be extended with additional APIs, which are not part of the core Kubernetes APIs.
-->
安装扩展的 API 服务器来使用聚合层以让 Kubernetes API 服务器使用
其它 API 进行扩展，
这些 API 不是核心 Kubernetes API 的一部分。
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!--
* You must [configure the aggregation layer](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) and enable the apiserver flags.
-->
* 你必须[配置聚合层](/zh/docs/tasks/extend-kubernetes/configure-aggregation-layer/)
并且启用 API 服务器的相关参数。
<!-- steps -->
<!--
## Setup an extension api-server to work with the aggregation layer
The following steps describe how to set up an extension-apiserver *at a high level*. These steps apply regardless if you're using YAML configs or using APIs. An attempt is made to specifically identify any differences between the two. For a concrete example of how they can be implemented using YAML configs, you can look at the [sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/README.md) in the Kubernetes repo.
Alternatively, you can use an existing 3rd party solution, such as [apiserver-builder](https://github.com/Kubernetes-incubator/apiserver-builder/blob/master/README.md), which should generate a skeleton and automate all of the following steps for you.
-->
## 安装一个扩展的 API 服务器来使用聚合层
以下步骤描述如何 *在一个高层次* 设置一个扩展的 apiserver。无论你使用的是 YAML 配置还是使用 API，这些步骤都适用。
目前我们正在尝试区分出两者的区别。有关使用 YAML 配置的具体示例，你可以在 Kubernetes 库中查看
[sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/README.md)。
或者，你可以使用现有的第三方解决方案，例如
[apiserver-builder](https://github.com/Kubernetes-incubator/apiserver-builder/blob/master/README.md)，
它将生成框架并自动执行以下所有步骤。
<!--
1. Make sure the APIService API is enabled (check `-runtime-config`). It should be on by default, unless it's been deliberately turned off in your cluster.
1. You may need to make an RBAC rule allowing you to add APIService objects, or get your cluster administrator to make one. (Since API extensions affect the entire cluster, it is not recommended to do testing/development/debug of an API extension in a live cluster.)
1. Create the Kubernetes namespace you want to run your extension api-service in.
1. Create/get a CA cert to be used to sign the server cert the extension api-server uses for HTTPS.
1. Create a server cert/key for the api-server to use for HTTPS. This cert should be signed by the above CA. It should also have a CN of the Kube DNS name. This is derived from the Kubernetes service and be of the form `<service name>.<service name namespace>.svc`
1. Create a Kubernetes secret with the server cert/key in your namespace.
1. Create a Kubernetes deployment for the extension api-server and make sure you are loading the secret as a volume. It should contain a reference to a working image of your extension api-server. The deployment should also be in your namespace.
-->
1. 确保启用了 APIService API（检查 `--runtime-config`）。默认应该是启用的，除非被特意关闭了。
2. 你可能需要制定一个 RBAC 规则，以允许你添加 APIService 对象，或让你的集群管理员创建一个。
（由于 API 扩展会影响整个集群，因此不建议在实时集群中对 API 扩展进行测试/开发/调试）
3. 创建 Kubernetes 命名空间，扩展的 api-service 将运行在该命名空间中。
4. 创建（或获取）用来签署服务器证书的 CA 证书，扩展 api-server 中将使用该证书做 HTTPS 连接。
5. 为 api-server 创建一个服务端的证书（或秘钥）以使用 HTTPS。这个证书应该由上述的 CA 签署。
同时应该还要有一个 Kube DNS 名称的 CN，这是从 Kubernetes 服务派生而来的，
格式为 `<service name>.<service name namespace>.svc`。
6. 使用命名空间中的证书（或秘钥）创建一个 Kubernetes secret。
7. 为扩展 api-server 创建一个 Kubernetes Deployment，并确保以卷的方式挂载了 Secret。
它应该包含对扩展 api-server 镜像的引用。Deployment 也应该在同一个命名空间中。
<!--
1. Make sure that your extension-apiserver loads those certs from that volume and that they are used in the HTTPS handshake.
1. Create a Kubernetes service account in your namespace.
1. Create a Kubernetes cluster role for the operations you want to allow on your resources.
1. Create a Kubernetes cluster role binding from the service account in your namespace to the cluster role you created.
1. Create a Kubernetes cluster role binding from the service account in your namespace to the `system:auth-delegator` cluster role to delegate auth decisions to the Kubernetes core API server.
1. Create a Kubernetes role binding from the service account in your namespace to the `extension-apiserver-authentication-reader` role. This allows your extension api-server to access the `extension-apiserver-authentication` configmap.
-->
8. 确保你的扩展 apiserver 从该卷中加载了那些证书，并在 HTTPS 握手过程中使用它们。
9. 在你的命名空间中创建一个 Kubernetes 服务账号。
10. 为资源允许的操作创建 Kubernetes 集群角色。
11. 用你命名空间中的服务账号创建一个 Kubernetes 集群角色绑定，绑定到你创建的角色上。
12. 用你命名空间中的服务账号创建一个 Kubernetes 集群角色绑定，绑定到 `system:auth-delegator`
集群角色，以将 auth 决策委派给 Kubernetes 核心 API 服务器。
13. 以你命名空间中的服务账号创建一个 Kubernetes 集群角色绑定，绑定到
`extension-apiserver-authentication-reader` 角色。
这将让你的扩展 api-server 能够访问 `extension-apiserver-authentication` configmap。
<!--
1. Create a Kubernetes apiservice. The CA cert above should be base64 encoded, stripped of new lines and used as the spec.caBundle in the apiservice. This should not be namespaced. If using the [kube-aggregator API](https://github.com/kubernetes/kube-aggregator/), only pass in the PEM encoded CA bundle because the base 64 encoding is done for you.
1. Use kubectl to get your resource. When run, kubectl should return "No resources found.". This message indicates that everything worked but you currently have no objects of that resource type created.
-->
14. 创建一个 Kubernetes apiservice。
上述的 CA 证书应该使用 base64 编码，剥离新行并用作 apiservice 中的 spec.caBundle。
该资源不应放到任何名字空间。如果使用了
[kube-aggregator API](https://github.com/kubernetes/kube-aggregator/)，那么只需要传入
PEM 编码的 CA 绑定，因为 base 64 编码已经完成了。
15. 使用 kubectl 来获得你的资源。
它应该返回 "找不到资源"。此消息表示一切正常，但你目前还没有创建该资源类型的对象。
## {{% heading "whatsnext" %}}
<!--
* If you haven't already, [configure the aggregation layer](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) and enable the apiserver flags.
* For a high level overview, see [Extending the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation).
* Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/).
-->
* 如果你还未配置，请[配置聚合层](/zh/docs/tasks/extend-kubernetes/configure-aggregation-layer/)
并启用 apiserver 的相关参数。
* 高级概述，请参阅[使用聚合层扩展 Kubernetes API](/zh/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation)。
* 了解如何[使用 Custom Resource Definition 扩展 Kubernetes API](/zh/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)。
content/zh-cn/docs/tasks/extend-kubernetes/setup-konnectivity.md
+144
View File
@@ -0,0 +1,144 @@
---
title: 设置 Konnectivity 服务
content_type: task
weight: 70
---
<!-- overview -->
<!--
The Konnectivity service provides a TCP level proxy for the control plane to cluster
communication.
-->
Konnectivity 服务为控制平面提供集群通信的 TCP 级别代理。
## {{% heading "prerequisites" %}}
<!--
You need to have a Kubernetes cluster, and the kubectl command-line tool must
be configured to communicate with your cluster. It is recommended to run this
tutorial on a cluster with at least two nodes that are not acting as control
plane hosts. If you do not already have a cluster, you can create one by using
[minikube](https://minikube.sigs.k8s.io/docs/tutorials/multi_node/).
-->
你需要有一个 Kubernetes 集群，并且 kubectl 命令可以与集群通信。
建议在至少有两个不充当控制平面主机的节点的集群上运行本教程。
如果你还没有集群，可以使用
[minikube](https://minikube.sigs.k8s.io/docs/tutorials/multi_node/) 创建一个集群。
<!-- steps -->
<!--
## Configure the Konnectivity service
The following steps require an egress configuration, for example:
-->
## 配置 Konnectivity 服务
接下来的步骤需要出口配置，比如：
{{< codenew file="admin/konnectivity/egress-selector-configuration.yaml" >}}
<!--
You need to configure the API Server to use the Konnectivity service
and direct the network traffic to the cluster nodes:
1. Make sure that
[Service Account Token Volume Projection](/docs/tasks/configure-pod-container/configure-service-account/#service-account-token-volume-projection)
feature enabled in your cluster. It is enabled by default since Kubernetes v1.20.
1. Create an egress configuration file such as `admin/konnectivity/egress-selector-configuration.yaml`.
1. Set the `--egress-selector-config-file` flag of the API Server to the path of
your API Server egress configuration file.
1. If you use UDS connection, add volumes config to the kube-apiserver:
```yaml
spec:
containers:
volumeMounts:
- name: konnectivity-uds
mountPath: /etc/kubernetes/konnectivity-server
readOnly: false
volumes:
- name: konnectivity-uds
hostPath:
path: /etc/kubernetes/konnectivity-server
type: DirectoryOrCreate
```
-->
你需要配置 API 服务器来使用 Konnectivity 服务，并将网络流量定向到集群节点：
确保[服务账号令牌卷投射](/zh/docs/tasks/configure-pod-container/configure-service-account/#service-account-token-volume-projection)
特性被启用。该特性自 Kubernetes v1.20 起默认已被启用。
1. 创建一个出站流量配置文件，比如 `admin/konnectivity/egress-selector-configuration.yaml`。
1. 将 API 服务器的 `--egress-selector-config-file` 参数设置为你的 API 服务器的
离站流量配置文件路径。
1. 如果你在使用 UDS 连接，须将卷配置添加到 kube-apiserver：
```yaml
spec:
containers:
volumeMounts:
- name: konnectivity-uds
mountPath: /etc/kubernetes/konnectivity-server
readOnly: false
volumes:
- name: konnectivity-uds
hostPath:
path: /etc/kubernetes/konnectivity-server
type: DirectoryOrCreate
```
<!--
Generate or obtain a certificate and kubeconfig for konnectivity-server.
For example, you can use the OpenSSL command line tool to issue a X.509 certificate,
using the cluster CA certificate `/etc/kubernetes/pki/ca.crt` from a control-plane host.
-->
为 konnectivity-server 生成或者取得证书和 kubeconfig 文件。
例如，你可以使用 OpenSSL 命令行工具，基于存放在某控制面主机上
`/etc/kubernetes/pki/ca.crt` 文件中的集群 CA 证书来
发放一个 X.509 证书，
```bash
openssl req -subj "/CN=system:konnectivity-server" -new -newkey rsa:2048 -nodes -out konnectivity.csr -keyout konnectivity.key -out konnectivity.csr
openssl x509 -req -in konnectivity.csr -CA /etc/kubernetes/pki/ca.crt -CAkey /etc/kubernetes/pki/ca.key -CAcreateserial -out konnectivity.crt -days 375 -sha256
SERVER=$(kubectl config view -o jsonpath='{.clusters..server}')
kubectl --kubeconfig /etc/kubernetes/konnectivity-server.conf config set-credentials system:konnectivity-server --client-certificate konnectivity.crt --client-key konnectivity.key --embed-certs=true
kubectl --kubeconfig /etc/kubernetes/konnectivity-server.conf config set-cluster kubernetes --server "$SERVER" --certificate-authority /etc/kubernetes/pki/ca.crt --embed-certs=true
kubectl --kubeconfig /etc/kubernetes/konnectivity-server.conf config set-context system:konnectivity-server@kubernetes --cluster kubernetes --user system:konnectivity-server
kubectl --kubeconfig /etc/kubernetes/konnectivity-server.conf config use-context system:konnectivity-server@kubernetes
rm -f konnectivity.crt konnectivity.key konnectivity.csr
```
<!--
Next, you need to deploy the Konnectivity server and agents.
[kubernetes-sigs/apiserver-network-proxy](https://github.com/kubernetes-sigs/apiserver-network-proxy)
is a reference implementation.
Deploy the Konnectivity server on your control plane node. The provided
`konnectivity-server.yaml` manifest assumes
that the Kubernetes components are deployed as a {{< glossary_tooltip text="static Pod"
term_id="static-pod" >}} in your cluster. If not, you can deploy the Konnectivity
server as a DaemonSet.
-->
接下来，你需要部署 Konnectivity 服务器和代理。
[kubernetes-sigs/apiserver-network-proxy](https://github.com/kubernetes-sigs/apiserver-network-proxy)
是一个参考实现。
在控制面节点上部署 Konnectivity 服务。
下面提供的 `konnectivity-server.yaml` 配置清单假定在你的集群中
Kubernetes 组件都是部署为{{< glossary_tooltip text="静态 Pod" term_id="static-pod" >}} 的。
如果不是，你可以将 Konnectivity 服务部署为 DaemonSet。
{{< codenew file="admin/konnectivity/konnectivity-server.yaml" >}}
<!--
Then deploy the Konnectivity agents in your cluster:
-->
在你的集群中部署 Konnectivity 代理：
{{< codenew file="admin/konnectivity/konnectivity-agent.yaml" >}}
<!--
Last, if RBAC is enabled in your cluster, create the relevant RBAC rules:
-->
最后，如果你的集群启用了 RBAC，请创建相关的 RBAC 规则：
{{< codenew file="admin/konnectivity/konnectivity-rbac.yaml" >}}
content/zh-cn/docs/tasks/extend-kubernetes/socks5-proxy-access-api.md
+246
View File
@@ -0,0 +1,246 @@
---
title: 使用 SOCKS5 代理访问 Kubernetes API
content_type: task
weight: 42
min-kubernetes-server-version: v1.24
---
<!-- overview -->
{{< feature-state for_k8s_version="v1.24" state="stable" >}}
<!--
This page shows how to use a SOCKS5 proxy to access the API of a remote Kubernetes cluster.
This is useful when the cluster you want to access does not expose its API directly on the public internet.
-->
本文展示了如何使用 SOCKS5 代理访问远程 Kubernetes 集群的 API。
当你要访问的集群不直接在公共 Internet 上公开其 API 时，这很有用。
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
<!--
You need SSH client software (the `ssh` tool), and an SSH service running on the remote server.
You must be able to log in to the SSH service on the remote server.
-->
你需要 SSH 客户端软件（`ssh` 工具），并在远程服务器上运行 SSH 服务。
你必须能够登录到远程服务器上的 SSH 服务。
<!-- steps -->
<!--
## Task context
-->
## 任务上下文
<!--
This example tunnels traffic using SSH, with the SSH client and server acting as a SOCKS proxy.
You can instead use any other kind of [SOCKS5](https://en.wikipedia.org/wiki/SOCKS#SOCKS5) proxies.
-->
{{< note >}}
此示例使用 SSH 隧道传输流量，SSH 客户端和服务器充当 SOCKS 代理。
你可以使用其他任意类型的 [SOCKS5](https://zh.wikipedia.org/wiki/SOCKS#SOCKS5) 代理代替。
{{</ note >}}
<!--
Figure 1 represents what you're going to achieve in this task.
* You have a client computer, referred to as local in the steps ahead, from where you're going to create requests to talk to the Kubernetes API.
* The Kubernetes server/API is hosted on a remote server.
* You will use SSH client and server software to create a secure SOCKS5 tunnel between the local and
the remote server. The HTTPS traffic between the client and the Kubernetes API will flow over the SOCKS5
tunnel, which is itself tunnelled over SSH.
-->
图 1 表示你将在此任务中实现的目标。
* 你有一台在后面的步骤中被称为本地计算机的客户端计算机，你将在这台计算机上创建与 Kubernetes API 对话的请求。
* Kubernetes 服务器/API 托管在远程服务器上。
* 你将使用 SSH 客户端和服务器软件在本地和远程服务器之间创建安全的 SOCKS5 隧道。
客户端和 Kubernetes API 之间的 HTTPS 流量将流经 SOCKS5 隧道，该隧道本身通过 SSH 进行隧道传输。
<!--
graph LR;
subgraph local[Local client machine]
client([client])-- local <br> traffic .-> local_ssh[Local SSH <br> SOCKS5 proxy];
end
local_ssh[SSH <br>SOCKS5 <br> proxy]-- SSH Tunnel --\>sshd
subgraph remote[Remote server]
sshd[SSH <br> server]-- local traffic --\>service1;
end
client([client])-. proxied HTTPs traffic <br> going through the proxy .->service1[Kubernetes API];
classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
class ingress,service1,service2,pod1,pod2,pod3,pod4 k8s;
class client plain;
class cluster cluster;
-->
{{< mermaid >}}
graph LR;
subgraph local[本地客户端机器]
client([客户端])-- 本地 <br> 流量.-> local_ssh[本地 SSH <br> SOCKS5 代理];
end
ocal_ssh[SSH <br>SOCKS5 <br> 代理]-- SSH 隧道 -->sshd
subgraph remote[远程服务器]
sshd[SSH <br> 服务器]-- 本地流量 -->service1;
end
client([客户端])-. 通过代理传递的 <br> HTTPS 流量 .->service1[Kubernetes API];
classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
class ingress,service1,service2,pod1,pod2,pod3,pod4 k8s;
class client plain;
class cluster cluster;
{{</ mermaid >}}
<!--
Figure 1. SOCKS5 tutorial components
-->
图 1. SOCKS5 教程组件
<!--
## Using ssh to create a SOCKS5 proxy
-->
## 使用 ssh 创建 SOCKS5 代理
<!--
This command starts a SOCKS5 proxy between your client machine and the remote server.
The SOCKS5 proxy lets you connect to your cluster's API server.
-->
此命令在你的客户端计算机和远程服务器之间启动一个 SOCKS5 代理。
SOCKS5 代理允许你连接到集群的 API 服务器。
```shell
# 运行此命令后，SSH 隧道继续在前台运行
ssh -D 1080 -q -N username@kubernetes-remote-server.example
```
<!--
* `-D 1080`: opens a SOCKS proxy on local port :1080.
* `-q`: quiet mode. Causes most warning and diagnostic messages to be suppressed.
* `-N`: Do not execute a remote command. Useful for just forwarding ports.
* `username@kubernetes-remote-server.example`: the remote SSH server where the Kubernetes cluster is running.
-->
* `-D 1080`: 在本地端口 1080 上打开一个 SOCKS 代理。
* `-q`: 静音模式。导致大多数警告和诊断消息被抑制。
* `-N`: 不执行远程命令。仅用于转发端口。
* `username@kubernetes-remote-server.example`: 运行 Kubernetes 集群的远程 SSH 服务器。
<!--
## Client configuration
-->
## 客户端配置
<!--
To explore the Kubernetes API you'll first need to instruct your clients to send their queries through
the SOCKS5 proxy we created earlier.
For command-line tools, set the `https_proxy` environment variable and pass it to commands that you run.
-->
要探索 Kubernetes API，你首先需要指示你的客户端通过我们之前创建的 SOCKS5 代理发送他们的查询。
对于命令行工具，设置 `https_proxy` 环境变量并将其传递给你运行的命令。
```shell
export https_proxy=socks5h://localhost:1080
```
<!--
When you set the `https_proxy` variable, tools such as `curl` route HTTPS traffic through the proxy
you configured. For this to work, the tool must support SOCKS5 proxying.
{{< note >}}
In the URL https://localhost/api, `localhost` does not refer to your local client computer.
Instead, it refers to the endpoint on the remote server knows as `localhost`.
The `curl` tool sends the hostname from the HTTPS URL over SOCKS, and the remote server
resolves that locally (to an address that belongs to its loopback interface).
{{</ note >}}
-->
当你设置 `https_proxy` 变量时，`curl` 等工具会通过你配置的代理路由 HTTPS 流量。
为此，该工具必须支持 SOCKS5 代理。
{{< note >}}
在 URL https://localhost/api 中，`localhost` 不是指你的本地客户端计算机。
它指的是远程服务器上称为 “localhost” 的端点。
`curl` 工具通过 SOCKS 从 HTTPS URL 发送主机名，远程服务器在本地解析（到属于其环回接口的地址）。
{{</ note >}}
```shell
curl -k -v https://localhost/api
```
<!--
To use the official Kubernetes client `kubectl` with a proxy, set the `proxy-url` element
for the relevant `cluster` entry within your `~/.kube/config` file. For example:
-->
要将官方 Kubernetes 客户端 `kubectl` 与代理一起使用，请在 `~/.kube/config` 文件中为相关的
`cluster` 条目设置 `proxy-url` 元素。 例如：
```yaml
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: LRMEMMW2 # 为了便于阅读缩短
server: https://localhost # 上图中的“Kubernetes API”
proxy-url: socks5://localhost:1080 # 上图中的“SSH SOCKS5代理”（内置DNS解析）
name: default
contexts:
- context:
cluster: default
user: default
name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
user:
client-certificate-data: LS0tLS1CR== # 为了便于阅读缩短
client-key-data: LS0tLS1CRUdJT= # 为了便于阅读缩短
```
<!--
If the tunnel is operating and you use `kubectl` with a context that uses this cluster, you can interact with your cluster through that proxy. For example:
-->
如果隧道能够正常工作，并且你调用 `kubectl` 时使用此集群的上下文，
则可以通过该代理与你的集群交互。 例如：
```shell
kubectl get pods
```
```console
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system coredns-85cb69466-klwq8 1/1 Running 0 5m46s
```
<!--
## Clean up
-->
## 清理
<!--
Stop the ssh port-forwarding process by pressing `CTRL+C` on the terminal where it is running.
Type `unset https_proxy` in a terminal to stop forwarding http traffic through the proxy.
-->
通过在运行它的终端上按“CTRL+C”来停止 ssh 端口转发进程。
在终端中键入 `unset https_proxy` 以停止通过代理转发 http 流量。
<!--
## Further reading
-->
## 进一步阅读
<!--
* [OpenSSH remote login client](https://man.openbsd.org/ssh)
-->
* [OpenSSH远程登录客户端](https://man.openbsd.org/ssh)