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

[zh] Tidy up and fix links in tasks section (9/10)

Browse Source
This commit is contained in:
Qiming Teng
2020-08-16 16:31:39 +08:00
parent fb6364da0a
commit dabb6d6896
9 changed files with 780 additions and 716 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/zh/docs/tasks/extend-kubernetes/configure-aggregation-layer.md
+75 -81
View File
@@ -1,14 +1,9 @@
---
title: 配置聚合层
reviewers:
- lavalamp
- cheftako
- chenopis
content_type: task
weight: 10
---
<!--
---
title: Configure the Aggregation Layer
reviewers:
- lavalamp
@@ -16,7 +11,6 @@ reviewers:
- chenopis
content_type: task
weight: 10
---
-->
<!-- overview -->
@@ -24,35 +18,29 @@ weight: 10
<!--
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 的一部分。
配置 [聚合层](/zh/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) 允许
Kubernetes apiserver 使用其它 API 扩展，这些 API 不是核心 Kubernetes API 的一部分。
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
{{< note >}}
<!--
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 master CA.
-->
要使聚合层在您的环境中正常工作以支持代理服务器和扩展 apiserver 之间的相互 TLS 身份验证，需要满足一些设置要求。Kubernetes 和 kube-apiserver 具有多个 CA，因此请确保代理是由聚合层 CA 签名的，而不是由主 CA 签名的。
{{< caution >}}
{{< note >}}
要使聚合层在您的环境中正常工作以支持代理服务器和扩展 apiserver 之间的相互 TLS 身份验证，
需要满足一些设置要求。Kubernetes 和 kube-apiserver 具有多个 CA，
因此请确保代理是由聚合层 CA 签名的，而不是由主 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).
-->
对不同的客户端类型重复使用相同的 CA 会对群集的功能产生负面影响。有关更多信息，请参见 [CA重用和冲突](#ca-重用和冲突)。
{{< caution >}}
对不同的客户端类型重复使用相同的 CA 会对群集的功能产生负面影响。有关更多信息，请参见
[CA 重用和冲突](#ca-reusage-and-conflicts)。
{{< /caution >}}
{{< /note >}}
<!-- steps -->
@@ -62,7 +50,14 @@ Reusing the same CA for different client types can negatively impact the cluster
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.
@@ -79,13 +74,6 @@ The flow can be seen in the following diagram.
The source for the above swimlanes can be found in the source of this document.
-->
## 认证流程
与自定义资源定义（CRD）不同，除标准的 Kubernetes apiserver 外，Aggregation API 还涉及另一个服务器：扩展 apiserver。Kubernetes apiserver 将需要与您的扩展 apiserver 通信，并且您的扩展 apiserver 也需要与 Kubernetes apiserver 通信。为了确保此通信的安全，Kubernetes apiserver 使用 x509 证书向扩展 apiserver 认证。
本节介绍身份认证和鉴权流程的工作方式以及如何配置它们。
大致流程如下：
1. Kubernetes apiserver：对发出请求的用户身份认证，并对请求的 API 路径执行鉴权。
@@ -264,20 +252,7 @@ The Kubernetes apiserver connects to the extension apiserver over TLS, authentic
* 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`
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.
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 客户端认证
Kubernetes apiserver 通过 TLS 连接到扩展 apiserver，并使用客户端证书认证。您必须在启动时使用提供的标志向 Kubernetes apiserver 提供以下内容：
@@ -287,12 +262,29 @@ Kubernetes apiserver 通过 TLS 连接到扩展 apiserver，并使用客户端
* 通过 `--requestheader-client-ca-file` 签署客户端证书文件的 CA 证书
* 通过 `--requestheader-allowed-names` 在签署的客户证书中有效的公用名（CN）
Kubernetes apiserver 将使用由 --proxy-client-*-file 指示的文件来验证扩展 apiserver。为了使合规的扩展 apiserver 能够将该请求视为有效，必须满足以下条件：
<!--
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` 中列出的证书之一。
**注意：**您可以将此选项设置为空白，即为`--requestheader-allowed-names`。这将向扩展 apiserver 指示任何 CN 是可接受的。
{{< 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 认证。
@@ -305,9 +297,9 @@ Kubernetes apiserver 将使用由 --proxy-client-*-file 指示的文件来验证
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`
* 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.
-->
@@ -336,14 +328,7 @@ The extension apiserver, upon receiving a proxied request from the Kubernetes ap
* 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
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.
-->
### 扩展 Apiserver 认证
扩展 apiserver 在收到来自 Kubernetes apiserver 的代理请求后，必须验证该请求确实确实来自有效的身份验证代理，该认证代理由 Kubernetes apiserver 履行。扩展 apiserver 通过以下方式对其认证：
@@ -358,6 +343,13 @@ In order to have permission to retrieve the configmap, an extension apiserver re
* 在允许的 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/` 软件包来做到这一点。也有一些实现可能支持使用命令行选项来覆盖这些配置。
@@ -371,10 +363,11 @@ The extension apiserver now can validate that the user/group retrieved from the
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 现在可以验证从标头检索的`user/group`是否有权执行给定请求。
通过向 Kubernetes apiserver 发送标准
[SubjectAccessReview](/zh/docs/reference/access-authn-authz/authorization/) 请求来实现。
为了使扩展 apiserver 本身被鉴权可以向 Kubernetes apiserver 提交 SubjectAccessReview 请求，它需要正确的权限。Kubernetes 包含一个具有相应权限的名为`system：auth-delegator` 的默认 `ClusterRole`，可以将其授予扩展 apiserver 的服务帐户。
@@ -383,21 +376,19 @@ In order for the extension apiserver to be authorized itself to submit the `Subj
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 执行请求。
如果 `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-
@@ -405,13 +396,14 @@ Enable the aggregation layer via the following kube-apiserver flags. They may ha
--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-重用和冲突 {#ca-reusage-and-conflicts}
Kubernetes apiserver 有两个客户端 CA 选项：
@@ -423,40 +415,38 @@ Each of these functions independently and can conflict with each other, if not u
* `--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.
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`：当请求到达 Kubernetes apiserver 时，如果启用了此选项，则 Kubernetes apiserver 会检查请求的证书。如果它是由 `--client-ca-file` 引用的文件中的 CA 证书之一签名的，并且用户是公用名`CN=`的值，而组是组织`O=` 的取值，则该请求被视为合法请求。请参阅 [关于 TLS 身份验证的文档](/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 证书。
{{< warning >}}
<!--
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
```
--enable-aggregator-routing=true
```
<!--
### Register APIService objects
@@ -464,13 +454,11 @@ If you are not running kube-proxy on a host running the API server, then you mus
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:
@@ -485,6 +473,14 @@ spec:
name: < 拓展 Apiserver 服务的 name >
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
@@ -499,8 +495,6 @@ Here is an example of an extension apiserver that is configured to be called on
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，它需要知道如何调用它。
@@ -536,8 +530,8 @@ spec:
* Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/).
-->
* 使用聚合层 [建立扩展 api-server](/zh/docs/tasks/access-kubernetes-api/setup-extension-api-server/)。
* 有关高级概述，请参阅 [使用聚合层扩展 Kubernetes API](/zh/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)。
* 了解如何 [使用自定义资源扩展 Kubernetes API](/docs/tasks/access-kubernetes-api/custom-resources/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/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md
+92 -105
View File
@@ -1,21 +1,17 @@
---
title: 用户自定义资源版本
reviewers:
- mbohlool
- sttts
- liggitt
title: 用户自定义资源的版本
content_type: task
weight: 30
min-kubernetes-server-version: v1.16
---
<!--
---
title: Versions in CustomResourceDefinitions
reviewers:
- sttts
- liggitt
content_type: task
weight: 30
---
min-kubernetes-server-version: v1.16
-->
<!-- overview -->
@@ -24,28 +20,22 @@ This page explains how to add versioning information to
[CustomResourceDefinitions](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#customresourcedefinition-v1beta1-apiextensions), to indicate the stability
level of your CustomResourceDefinitions or advance your API to a new version with conversion between API representations. It also describes how to upgrade an object from one version to another.
-->
本页介绍了如何添加版本信息到 [CustomResourceDefinitions](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#customresourcedefinition-v1beta1-apiextensions)，如何表示 CustomResourceDefinitions 的稳定水平或者用 API 之间的表征的转换提高您的 API 到一个新的版本。它还描述了如何将对象从一个版本升级到另一个版本。
本页介绍如何添加版本信息到
[CustomResourceDefinitions](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#customresourcedefinition-v1beta1-apiextensions)，
如何表示 CustomResourceDefinitions 的稳定水平或者用 API 之间的表征的转换提高您的 API 到一个新的版本。
本页还描述如何将对象从一个版本升级到另一个版本。
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
{{< include "task-tutorial-prereqs.md" >}}
<!--
* Make sure your Kubernetes cluster has a master version of 1.16.0 or higher for `apiextensions.k8s.io/v1`, or 1.11.0 or higher for `apiextensions.k8s.io/v1beta1`.
You should have a initial understanding of [custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
-->
* 确保您的 Kubernetes 集群的主版本为`apiextensions.k8s.io/v1`的1.16.0或更高版本，`apiextensions.k8s.io/v1beta1`的1.11.0或更高版本。
<!--
* Read about [custom resources](/docs/concepts/api-extension/custom-resources/).
-->
* 阅读 [custom resources](/docs/concepts/api-extension/custom-resources/)。
你应该对[自定义资源](/zh/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
有一些初步了解。
{{< version-check >}}
<!-- steps -->
@@ -54,8 +44,6 @@ level of your CustomResourceDefinitions or advance your API to a new version wit
-->
## 概览
{{< feature-state state="stable" for_kubernetes_version="1.16" >}}
<!--
The CustomResourceDefinition API provides a workflow for introducing and upgrading
to new versions of a CustomResourceDefinition.
@@ -70,7 +58,16 @@ Once the CustomResourceDefinition is created, clients may begin using the
`v1beta1` API.
Later it might be necessary to add new version such as `v1`.
-->
CustomResourceDefinition API 提供了用于引入和升级的工作流程到 CustomResourceDefinition 的新版本。
创建 CustomResourceDefinition 时，会在 CustomResourceDefinition `spec.versions` 列表设置适当的稳定级和版本号。例如`v1beta1`表示第一个版本尚未稳定。所有自定义资源对象将首先存储在这个版本
创建 CustomResourceDefinition 后，客户端可以开始使用 v1beta1 API。
稍后可能需要添加新版本，例如 v1。
<!--
Adding a new version:
1. Pick a conversion strategy. Since custom resource objects need to be able to
@@ -88,7 +85,17 @@ Adding a new version:
`spec.versions` list with `served:true`. Also, set `spec.conversion` field
to the selected conversion strategy. If using a conversion webhook, configure
`spec.conversion.webhookClientConfig` field to call the webhook.
-->
增加一个新版本：
1. 选择一种转化策略。由于自定义资源对象需要能够两种版本都可用，这意味着它们有时会以与存储版本不同的版本。为了能够做到这一点，
有时必须在它们存储的版本和提供的版本。如果转换涉及结构变更，并且需要自定义逻辑，转换应该使用 webhook。如果没有结构变更，
则使用 None 默认转换策略，不同版本时只有`apiVersion`字段有变更。
2. 如果使用转换 Webhook，请创建并部署转换 Webhook。希望看到更多详细信息，请参见 [Webhook conversion](#webhook转换)。
3. 更新 CustomResourceDefinition，来将新版本包含在具有`served：true`的 spec.versions 列表。另外，设置`spec.conversion`字段
到所选的转换策略。如果使用转换 Webhook，请配置`spec.conversion.webhookClientConfig`来调用 webhook。
<!--
Once the new version is added, clients may incrementally migrate to the new
version. It is perfectly safe for some clients to use the old version while
others use the new version.
@@ -99,7 +106,16 @@ Migrate stored objects to the new version:
It is safe for clients to use both the old and new version before, during and
after upgrading the objects to a new stored version.
-->
添加新版本后，客户端可以逐步迁移到新版本。对于某些客户而言，在使用旧版本的同时支持其他人使用新版本。
将存储的对象迁移到新版本：
1. 请参阅 [将现有对象升级到新的存储版本](#将现有对象升级到新的存储版本) 章节。
对于客户来说，在将对象升级到新的存储版本之前，期间和之后使用旧版本和新版本都是安全的。
<!--
Removing an old version:
1. Ensure all clients are fully migrated to the new version. The kube-apiserver
@@ -115,39 +131,7 @@ Removing an old version:
1. Verify that the old version is no longer listed in the CustomResourceDefinition `status.storedVersions`.
1. Remove the old version from the CustomResourceDefinition `spec.versions` list.
1. Drop conversion support for the old version in conversion webhooks.
## Specify multiple versions
The CustomResourceDefinition API `versions` field can be used to support multiple versions of custom resources that you
have developed. Versions can have different schemas, and conversion webhooks can convert custom resources between versions.
Webhook conversions should follow the [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) wherever applicable.
Specifically, See the [API change documentation](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md) for a set of useful gotchas and suggestions.
-->
CustomResourceDefinition API 提供了用于引入和升级的工作流程到 CustomResourceDefinition 的新版本。
创建 CustomResourceDefinition 时，会在 CustomResourceDefinition `spec.versions` 列表设置适当的稳定级和版本号。例如`v1beta1`表示第一个版本尚未稳定。所有自定义资源对象将首先存储在这个版本
创建 CustomResourceDefinition 后，客户端可以开始使用 v1beta1 API。
稍后可能需要添加新版本，例如 v1。
增加一个新版本：
1. 选择一种转化策略。由于自定义资源对象需要能够两种版本都可用，这意味着它们有时会以与存储版本不同的版本。为了能够做到这一点，
有时必须在它们存储的版本和提供的版本。如果转换涉及结构变更，并且需要自定义逻辑，转换应该使用 webhook。如果没有结构变更，
则使用 None 默认转换策略，不同版本时只有`apiVersion`字段有变更。
2. 如果使用转换 Webhook，请创建并部署转换 Webhook。希望看到更多详细信息，请参见 [Webhook conversion](#webhook转换)。
3. 更新 CustomResourceDefinition，来将新版本包含在具有`served：true`的 spec.versions 列表。另外，设置`spec.conversion`字段
到所选的转换策略。如果使用转换 Webhook，请配置`spec.conversion.webhookClientConfig`来调用 webhook。
添加新版本后，客户端可以逐步迁移到新版本。对于某些客户而言，在使用旧版本的同时支持其他人使用新版本。
将存储的对象迁移到新版本：
1. 请参阅 [将现有对象升级到新的存储版本](#将现有对象升级到新的存储版本) 章节。
对于客户来说，在将对象升级到新的存储版本之前，期间和之后使用旧版本和新版本都是安全的。
删除旧版本：
1. 确保所有客户端都已完全迁移到新版本。kube-apiserver 可以查看日志以帮助识别仍通过进行访问的所有客户端旧版本。
@@ -159,17 +143,28 @@ CustomResourceDefinition API 提供了用于引入和升级的工作流程到 Cu
4. 从 CustomResourceDefinition`spec.versions` 列表中删除旧版本。
5. 在转换 webhooks 中放弃对旧版本的转换支持。
## 指定多个版本
<!--
## Specify multiple versions
The CustomResourceDefinition API `versions` field can be used to support multiple versions of custom resources that you
have developed. Versions can have different schemas, and conversion webhooks can convert custom resources between versions.
Webhook conversions should follow the [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md) wherever applicable.
Specifically, See the [API change documentation](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md) for a set of useful gotchas and suggestions.
-->
## 指定多个版本 {#specify-multiple-versions}
CustomResourceDefinition API 的`versions`字段可用于支持您自定义资源的多个版本已经开发的。版本可以具有不同的架构，并且转换 Webhooks 可以在版本之间转换自定义资源。
在适用的情况下，Webhook 转换应遵循 [Kubernetes API](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md)。
{{< note >}}
<!--
In `apiextensions.k8s.io/v1beta1`, there was a `version` field instead of `versions`. The
`version` field is deprecated and optional, but if it is not empty, it must
match the first item in the `versions` field.
-->
{{< note >}}
在 `apiextensions.k8s.io/v1beta1` 版本中，有一个 `version` 字段，名字不叫做 `versions`。
`version` 字段已经被废弃，成为可选项。不过如果该字段不是空，则必须与
`versions` 字段中的第一个条目匹配。
{{< /note >}}
<!--
@@ -177,13 +172,13 @@ This example shows a CustomResourceDefinition with two versions. For the first
example, the assumption is all versions share the same schema with no conversion
between them. The comments in the YAML provide more context.
-->
此示例显示了两个版本的 CustomResourceDefinition。第一个例子，假设所有的版本共享相同的模式而它们之间没有转换。YAML 中的评论提供了更多背景信息。
{{< tabs name="CustomResourceDefinition_versioning_example_1" >}}
{{% tab name="apiextensions.k8s.io/v1" %}}
```yaml
apiVersion: apiextensions.k8s.io/v1beta1
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
# name must match the spec fields below, and be in the form: <plural>.<group>
@@ -304,21 +299,19 @@ After creation, the API server starts to serve each enabled version at an HTTP
REST endpoint. In the above example, the API versions are available at
`/apis/example.com/v1beta1` and `/apis/example.com/v1`.
-->
在创建之后，apiserver 开始在 HTTP REST 端点上为每个启用的版本提供服务。在上面的示例中，API 版本可以在`/apis/example.com/v1beta1` 和 `/apis/example.com/v1`中获得。
在创建之后，apiserver 开始在 HTTP REST 端点上为每个启用的版本提供服务。
在上面的示例中，API 版本可以在`/apis/example.com/v1beta1` 和 `/apis/example.com/v1`中获得。
<!--
### Version priority
-->
### 版本优先级
<!--
Regardless of the order in which versions are defined in a
CustomResourceDefinition, the version with the highest priority is used by
kubectl as the default version to access objects. The priority is determined
by parsing the _name_ field to determine the version number, the stability
(GA, Beta, or Alpha), and the sequence within that stability level.
-->
### 版本优先级
不考虑 CustomResourceDefinition 中版本被定义的顺序，kubectl 使用具有最高优先级的版本作为访问对象的默认版本。
通过解析 _name_ 字段确定优先级来决定版本号，稳定性（GA，Beta，或者 Alpha），以及该稳定性水平内的序列。
@@ -352,9 +345,11 @@ like `v2` or `v2beta1`. Versions are sorted using the following algorithm:
-->
- 遵循 Kubernetes 版本模式的条目在不符合条件的条目之前进行排序。
- 对于遵循 Kubernetes 版本模式的条目，版本字符串的数字部分从最大到最小排序。
- 如果字符串`beta` 或 `alpha`跟随第一数字部分，它们按顺序排序，在没有`beta` 或 `alpha`后缀（假定为 GA 版本）的等效字符串后面。
- 如果字符串 `beta` 或 `alpha` 跟随第一数字部分，它们按顺序排序，在没有 `beta` 或 `alpha`
后缀（假定为 GA 版本）的等效字符串后面。
- 如果另一个数字跟在`beta`或`alpha`之后，那么这些数字也是从最大到最小排序。
- 不符合上述格式的字符串按字母顺序排序，数字部分不经过特殊处理。请注意，在下面的示例中，`foo1`在 `foo10`上方排序。这与遵循 Kubernetes 版本模式的条目的数字部分排序不同。
- 不符合上述格式的字符串按字母顺序排序，数字部分不经过特殊处理。
请注意，在下面的示例中，`foo1`在 `foo10`上方排序。这与遵循 Kubernetes 版本模式的条目的数字部分排序不同。
<!--
This might make sense if you look at the following sorted version list:
@@ -380,24 +375,24 @@ version sort order is `v1`, followed by `v1beta1`. This causes the kubectl
command to use `v1` as the default version unless the provided object specifies
the version.
-->
对于 [指定多个版本](#指定多个版本) 中的示例，版本排序顺序为`v1`，后跟着`v1beta1`。
这导致了 kubectl 命令使用`v1`作为默认版本，除非提供对象指定版本。
对于 [指定多个版本](#specify-multiple-versions) 中的示例，版本排序顺序为 `v1`，后跟着 `v1beta1`。
这导致了 kubectl 命令使用 `v1` 作为默认版本，除非提供对象指定版本。
<!--
## Webhook conversion
Webhook conversion is available as beta since 1.15, and as alpha since Kubernetes 1.13. The
`CustomResourceWebhookConversion` feature should be enabled. Please refer to the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) documentation for more information.
-->
## Webhook转换
<!--
Webhook conversion is introduced in Kubernetes 1.13 as an alpha feature. To use it, the
`CustomResourceWebhookConversion` feature should be enabled. Please refer to the [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) documentation for more information.
-->
{{< feature-state state="stable" for_k8s_version="v1.16" >}}
{{< note >}}
Webhook 转换在 Kubernetes 1.13 中作为 alpha 功能引入。要使用它，应启用`CustomResourceWebhookConversion`功能。请参阅 [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) 文档以获得更多信息。
Webhook 转换在 Kubernetes 1.15 中作为 beta 功能。
要使用它，应启用`CustomResourceWebhookConversion`功能。
在大多数集群上，这类 beta 特性应该时自动启用的。
请参阅[特行门控](/zh/docs/reference/command-line-tools-reference/feature-gates/) 文档以获得更多信息。
{{< /note >}}
<!--
@@ -423,10 +418,7 @@ To cover all of these cases and to optimize conversion by the API server, the co
<!--
### Write a conversion webhook server
-->
### 编写一个转换webhook服务
<!--
Please refer to the implementation of the [custom resource conversion webhook
server](https://github.com/kubernetes/kubernetes/tree/v1.15.0/test/images/crd-conversion-webhook/main.go)
that is validated in a Kubernetes e2e test. The webhook handles the
@@ -436,8 +428,9 @@ contains a list of custom resources that need to be converted independently with
changing the order of objects.
The example server is organized in a way to be reused for other conversions. Most of the common code are located in the [framework file](https://github.com/kubernetes/kubernetes/tree/v1.15.0/test/images/crd-conversion-webhook/converter/framework.go) that leaves only [one function](https://github.com/kubernetes/kubernetes/blob/v1.15.0/test/images/crd-conversion-webhook/converter/example_converter.go#L29-L80) to be implemented for different conversions.
-->
### 编写一个转换 Webhook 服务器
请参考 [自定义资源转换 webhook 服务](https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/main.go) 的实施，这在 Kubernetes e2e 测试中得到验证。webhook 处理由 apiserver 发送的`ConversionReview`请求，并发送回包含在`ConversionResponse`中的转换结果。请注意，请求包含需要独立转换不改变对象顺序的自定义资源列表。示例服务器的组织方式使其可以重用于其他转换。大多数常见代码都位于 [框架文件](https://github.com/kubernetes/kubernetes/tree/v1.14.0/test/images/crd-conversion-webhook/converter/framework.go) 中，只留下 [示例](https://github.com/kubernetes/kubernetes/blob/v1.13.0/test/images/crd-conversion-webhook/converter/example_converter.go#L29-L80) 用于实施不同的转换。
请参考[自定义资源转换 webhook 服务](https://github.com/kubernetes/kubernetes/tree/v1.15.0/test/images/crd-conversion-webhook/main.go) 的实施，这在 Kubernetes e2e 测试中得到验证。webhook 处理由 apiserver 发送的`ConversionReview`请求，并发送回包含在`ConversionResponse`中的转换结果。请注意，请求包含需要独立转换不改变对象顺序的自定义资源列表。示例服务器的组织方式使其可以重用于其他转换。大多数常见代码都位于 [框架文件](https://github.com/kubernetes/kubernetes/tree/v1.14.0/test/images/crd-conversion-webhook/converter/framework.go) 中，只留下 [示例](https://github.com/kubernetes/kubernetes/blob/v1.13.0/test/images/crd-conversion-webhook/converter/example_converter.go#L29-L80) 用于实施不同的转换。
<!--
The example conversion webhook server leaves the `ClientAuth` field
@@ -447,27 +440,27 @@ authenticate the identity of the clients, supposedly API servers. If you need
mutual TLS or other ways to authenticate the clients, see
how to [authenticate API servers](/docs/reference/access-authn-authz/extensible-admission-controllers/#authenticate-apiservers).
-->
{{< note >}}
示例转换 webhook 服务器留下`ClientAuth`字段 [empty](https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/config.go#L47-L48)，默认为`NoClientCert`。
示例转换 webhook 服务器留下`ClientAuth`字段为
[空](https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/config.go#L47-L48)，
默认为`NoClientCert`。
这意味着 webhook 服务器没有验证客户端的身份，据称是 apiserver。
如果您需要相互 TLS 或者其他方式来验证客户端，请参阅如何 [验证 API 服务](/docs/reference/access-authn-authz/extensible-admission-controllers/#authenticate-apiservers)。
如果您需要相互 TLS 或者其他方式来验证客户端，请参阅如何
[验证 API 服务](/zh/docs/reference/access-authn-authz/extensible-admission-controllers/#authenticate-apiservers)。
{{< /note >}}
<!--
### Deploy the conversion webhook service
-->
### 部署转换webhook服务
<!--
Documentation for deploying the conversion webhook is the same as for the [admission webhook example service](/docs/reference/access-authn-authz/extensible-admission-controllers/#deploy_the_admission_webhook_service).
The assumption for next sections is that the conversion webhook server is deployed to a service named `example-conversion-webhook-server` in `default` namespace and serving traffic on path `/crdconvert`.
-->
用于部署转换 webhook 的文档与 [准入webhook示例服务](/docs/reference/access-authn-authz/extensible-admission-controllers/#deploy_the_admission_webhook_service)。
### 部署转换 Webhook 服务
用于部署转换 webhook 的文档与
[准入webhook示例服务](/zh/docs/reference/access-authn-authz/extensible-admission-controllers/#deploy_the_admission_webhook_service)。
下一节的假设是转换 webhook 服务器部署到`default`命名空间中名为`example-conversion-webhook-server`的服务器上，并在路径`/crdconvert`上提供流量。
<!--
@@ -484,14 +477,13 @@ if a different port is used for the service.
<!--
### Configure CustomResourceDefinition to use conversion webhooks
-->
### 配置CustomResourceDefinition以使用转换webhooks
<!--
The `None` conversion example can be extended to use the conversion webhook by modifying `conversion`
section of the `spec`:
-->
通过修改`spec`中的`conversion`部分，可以扩展`None`转换示例来使用转换 webhook。
### 配置 CustomResourceDefinition 以使用转换 Webhook
通过修改 `spec` 中的 `conversion` 部分，可以扩展 `None` 转换示例来使用转换 webhook。
{{< tabs name="CustomResourceDefinition_versioning_example_2" >}}
{{% tab name="apiextensions.k8s.io/v1" %}}
@@ -641,11 +633,7 @@ Make sure the conversion service is up and running before applying new changes.
<!--
### Contacting the webhook
-->
### 调用-webhook
<!--
Once the API server has determined a request should be sent to a conversion webhook,
it needs to know how to contact the webhook. This is specified in the `webhookClientConfig`
stanza of the webhook configuration.
@@ -653,10 +641,12 @@ stanza of the webhook configuration.
Conversion webhooks can either be called via a URL or a service reference,
and can optionally include a custom CA bundle to use to verify the TLS connection.
-->
### 调用 Webhook
apiserver 一旦确定请求应发送到转换 webhook，它需要知道如何调用 webhook。这是在`webhookClientConfig`中指定的 webhook 配置。
转换 webhook 可以通过调用 URL 或服务，并且可以选择包含自定义 CA 包，以用于验证 TLS 连接。
### URL
<!--
@@ -744,8 +734,6 @@ Here is an example of a webhook that is configured to call a service on port "12
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.
-->
### 服务引用
`webhookClientConfig`内部的`service`段是对转换 webhook 服务的引用。如果 Webhook 在集群中运行，则应使用`service`而不是`url`。
@@ -796,6 +784,7 @@ spec:
```
{{% /tab %}}
{{< /tabs >}}
<!--
## Webhook request and response
@@ -808,8 +797,7 @@ serialized to JSON as the body.
Webhooks can specify what versions of `ConversionReview` objects they accept
with the `conversionReviewVersions` field in their CustomResourceDefinition:
-->
## Webhook-请求和响应
## Webhook 请求和响应
### 请求
@@ -1112,7 +1100,6 @@ should be avoided whenever possible, and should not be used to enforce validatio
<!--
Example of a response from a webhook indicating a conversion request failed, with an optional message:
-->
来自 Webhook 的响应示例，指示转换请求失败，并带有可选消息：
{{< tabs name="ConversionReview_response_failure" >}}
content/zh/docs/tasks/extend-kubernetes/setup-extension-api-server.md
+54 -49
View File
@@ -1,15 +1,10 @@
---
title: 设置一个扩展的 API server
reviewers:
- lavalamp
- cheftako
- chenopis
title: 安装一个扩展的 API server
content_type: task
weight: 15
---
<!--
---
title: Setup an extension API server
reviewers:
- lavalamp
@@ -17,7 +12,6 @@ reviewers:
- chenopis
content_type: task
weight: 15
---
-->
<!-- overview -->
@@ -25,28 +19,18 @@ weight: 15
<!--
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 server 来使用聚合层以让 Kubernetes apiserver 使用其它 API 进行扩展，这些 API 不是核心 Kubernetes API 的一部分。
安装扩展的 API 服务器来使用聚合层以让 Kubernetes API 服务器使用其它 API 进行扩展，
这些 API 不是核心 Kubernetes API 的一部分。
## {{% heading "prerequisites" %}}
<!--
* You need to have a Kubernetes cluster running.
* You must [configure the aggregation layer](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) and enable the apiserver flags.
-->
* 您需要拥有一个运行的 Kubernetes 集群。
* 您必须 [配置聚合层](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) 并且启用 apiserver 的相关参数。
## {{% 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 -->
@@ -57,55 +41,76 @@ The following steps describe how to set up an extension-apiserver *at a high lev
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-server 来使用聚合层
## 安装一个扩展的 API 服务器来使用聚合层
以下步骤描述如何 *在一个高层次* 设置一个扩展的 apiserver。无论您使用的是 YAML 配置还是使用 API，这些步骤都适用。目前我们正在尝试区分出两者的区别。有关使用 YAML 配置的具体示例，您可以在 Kubernetes 库中查看 [sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/README.md)。
以下步骤描述如何 *在一个高层次* 设置一个扩展的 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)，它将生成框架并自动执行以下所有步骤。
或者，你可以使用现有的第三方解决方案，例如
[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. 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 just 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.
-->
1. 确保启用了 APIService API（检查 `--runtime-config`）。默认应该是启用的，除非被特意关闭了。
1. 您可能需要制定一个 RBAC 规则，以允许您添加 APIService 对象，或让您的集群管理员创建一个。（由于 API 扩展会影响整个集群，因此不建议在实时集群中对 API 扩展进行测试/开发/调试）
1. 创建 Kubernetes 命名空间，扩展的 api-service 将运行在该命名空间中。
1. 创建（或获取）用来签署服务器证书的 CA 证书，扩展 api-server 中将使用该证书做 HTTPS 连接。
1. 为 api-server 创建一个服务端的证书（或秘钥）以使用 HTTPS。这个证书应该由上述的 CA 签署。同时应该还要有一个 Kube DNS 名称的 CN，这是从 Kubernetes 服务派生而来的，格式为 `<service name>.<service name namespace>.svc`。
1. 使用命名空间中的证书（或秘钥）创建一个 Kubernetes secret。
1. 为扩展 api-server 创建一个 Kubernetes deployment，并确保以卷的方式挂载了 secret。它应该包含对扩展 api-server 镜像的引用。Deployment 也应该在同一个命名空间中。
1. 确保您的扩展 apiserver 从该卷中加载了那些证书，并在 HTTPS 握手过程中使用它们。
1. 在您的命令空间中创建一个 Kubernetes service account。
1. 为资源允许的操作创建 Kubernetes 集群角色。
1. 以您命令空间中的 service account 创建一个 Kubernetes 集群角色绑定，绑定到您刚创建的角色上。
1. 以您命令空间中的 service account 创建一个 Kubernetes 集群角色绑定，绑定到 `system:auth-delegator` 集群角色，以将 auth 决策委派给 Kubernetes 核心 API 服务器。
1. 以您命令空间中的 service account 创建一个 Kubernetes 集群角色绑定，绑定到 `extension-apiserver-authentication-reader` 角色。这将让您的扩展 api-server 能够访问 `extension-apiserver-authentication` configmap。
1. 创建一个 Kubernetes apiservice。上述的 CA 证书应该使用 base64 编码，剥离新行并用作 apiservice 中的 spec.caBundle。这不应该是命名空间化的。如果使用了 [kube-aggregator API](https://github.com/kubernetes/kube-aggregator/)，那么只需要传入 PEM 编码的 CA 绑定，因为 base 64 编码已经完成了。
1. 使用 kubectl 来获得您的资源。它应该返回 "找不到资源"。此消息表示一切正常，但您目前还没有创建该资源类型的对象。
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/).
-->
* 如果你还未配置，请 [配置聚合层](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) 并启用 apiserver 的相关参数。
* 高级概述，请参阅 [使用聚合层扩展 Kubernetes API](/docs/concepts/api-extension/apiserver-aggregation)。
* 了解如何 [使用 Custom Resource Definition 扩展 Kubernetes API](/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](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)。