[zh] Resync using-api section

2021-06-09 19:58:54 +08:00 · 2021-06-09 19:58:54 +08:00 · f44e3ff8c8
parent 4502d3b438
commit f44e3ff8c8
3 changed files with 46 additions and 40 deletions
--- a/content/zh/docs/reference/using-api/api-concepts.md
+++ b/content/zh/docs/reference/using-api/api-concepts.md
@ -463,7 +463,7 @@ Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1, application/json
 <!--
 ## Alternate representations of resources

-By default Kubernetes returns objects serialized to JSON with content type `application/json`. This is the default serialization format for the API. However, clients may request the more efficient Protobuf representation of these objects for better performance at scale. The Kubernetes API implements standard HTTP content type negotiation: passing an `Accept` header with a `GET` call will request that the server return objects in the provided content type, while sending an object in Protobuf to the server for a `PUT` or `POST` call takes the `Content-Type` header. The server will return a `Content-Type` header if the requested format is supported, or the `406 Not acceptable` error if an invalid content type is provided.
+By default, Kubernetes returns objects serialized to JSON with content type `application/json`. This is the default serialization format for the API. However, clients may request the more efficient Protobuf representation of these objects for better performance at scale. The Kubernetes API implements standard HTTP content type negotiation: passing an `Accept` header with a `GET` call will request that the server return objects in the provided content type, while sending an object in Protobuf to the server for a `PUT` or `POST` call takes the `Content-Type` header. The server will return a `Content-Type` header if the requested format is supported, or the `406 Not acceptable` error if an invalid content type is provided.

 See the API documentation for a list of supported content types for each API.

@ -983,7 +983,7 @@ The meaning of the get and list semantics are:
 - **Any:** Return data at any resource version. The newest available resource version is preferred,
  but strong consistency is not required; data at any resource version may be served. It is possible
  for the request to return data at a much older resource version that the client has previously
-  observed, particularly in high availabiliy configurations, due to partitions or stale
+  observed, particularly in high availability configurations, due to partitions or stale
  caches. Clients that cannot tolerate this should not use this semantic.
 -->
 GET 和 LIST 操作的语义含义如下：
@ -1142,7 +1142,7 @@ reply with a `410 Gone` HTTP response.
 <!--
 ### Unavailable resource versions

-Servers are not required to serve unrecognized resource versions. List and Get requests for unrecognized resource versions may wait briefly for the resource version to become available, should timeout with a `504 (Gateway Timeout)` if the provided resource versions does not become available in a resonable amount of time, and may respond with a `Retry-After` response header indicating how many seconds a client should wait before retrying the request. Currently the kube-apiserver also identifies these responses with a "Too large resource version" message. Watch requests for a unrecognized resource version may wait indefinitely (until the request timeout) for the resource version to become available.
+Servers are not required to serve unrecognized resource versions. List and Get requests for unrecognized resource versions may wait briefly for the resource version to become available, should timeout with a `504 (Gateway Timeout)` if the provided resource versions does not become available in a reasonable amount of time, and may respond with a `Retry-After` response header indicating how many seconds a client should wait before retrying the request. Currently the kube-apiserver also identifies these responses with a "Too large resource version" message. Watch requests for a unrecognized resource version may wait indefinitely (until the request timeout) for the resource version to become available.
 -->
 ### 不可用的资源版本  {#unavailable-resource-versions}

--- a/content/zh/docs/reference/using-api/client-libraries.md
+++ b/content/zh/docs/reference/using-api/client-libraries.md
@ -5,13 +5,11 @@ weight: 30
 ---

 <!--
---
 title: Client Libraries
 reviewers:
 - ahmetb
 content_type: concept
 weight: 30
---
 -->

 <!-- overview -->
@ -58,22 +56,21 @@ The following client libraries are officially maintained by
 <!--
 | Language | Client Library | Sample Programs |
 |----------|----------------|-----------------|
-| Go       | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [browse](https://github.com/kubernetes/client-go/tree/master/examples)
-| Python       | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [browse](https://github.com/kubernetes-client/python/tree/master/examples)
-| Java     | [github.com/kubernetes-client/java](https://github.com/kubernetes-client/java/) | [browse](https://github.com/kubernetes-client/java#installation)
 | dotnet   | [github.com/kubernetes-client/csharp](https://github.com/kubernetes-client/csharp) | [browse](https://github.com/kubernetes-client/csharp/tree/master/examples/simple)
-| JavaScript   | [github.com/kubernetes-client/javascript](https://github.com/kubernetes-client/javascript) | [browse](https://github.com/kubernetes-client/javascript/tree/master/examples)
+| Go       | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [browse](https://github.com/kubernetes/client-go/tree/master/examples)
 | Haskell  | [github.com/kubernetes-client/haskell](https://github.com/kubernetes-client/haskell) | [browse](https://github.com/kubernetes-client/haskell/tree/master/kubernetes-client/example)
+| Java     | [github.com/kubernetes-client/java](https://github.com/kubernetes-client/java/) | [browse](https://github.com/kubernetes-client/java#installation)
+| JavaScript   | [github.com/kubernetes-client/javascript](https://github.com/kubernetes-client/javascript) | [browse](https://github.com/kubernetes-client/javascript/tree/master/examples)
+| Python   | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [browse](https://github.com/kubernetes-client/python/tree/master/examples)
 -->
-|   语言   |     客户端库    |     样例程序     |
-|----------|----------------|-----------------|
-| Go       | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [浏览](https://github.com/kubernetes/client-go/tree/master/examples)
-| Python       | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [浏览](https://github.com/kubernetes-client/python/tree/master/examples)
-| Java     | [github.com/kubernetes-client/java](https://github.com/kubernetes-client/java/) | [浏览](https://github.com/kubernetes-client/java#installation)
+|   语言  |     客户端库    |     样例程序    |
+|---------|-----------------|-----------------|
 | dotnet   | [github.com/kubernetes-client/csharp](https://github.com/kubernetes-client/csharp) | [浏览](https://github.com/kubernetes-client/csharp/tree/master/examples/simple)
-| JavaScript   | [github.com/kubernetes-client/javascript](https://github.com/kubernetes-client/javascript) | [浏览](https://github.com/kubernetes-client/javascript/tree/master/examples)
+| Go       | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [浏览](https://github.com/kubernetes/client-go/tree/master/examples)
 | Haskell  | [github.com/kubernetes-client/haskell](https://github.com/kubernetes-client/haskell) | [浏览](https://github.com/kubernetes-client/haskell/tree/master/kubernetes-client/example)
-
+| Java     | [github.com/kubernetes-client/java](https://github.com/kubernetes-client/java/) | [浏览](https://github.com/kubernetes-client/java#installation)
+| JavaScript   | [github.com/kubernetes-client/javascript](https://github.com/kubernetes-client/javascript) | [浏览](https://github.com/kubernetes-client/javascript/tree/master/examples)
+| Python   | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [浏览](https://github.com/kubernetes-client/python/tree/master/examples)

 <!--
 ## Community-maintained client libraries
@ -92,6 +89,10 @@ their authors, not the Kubernetes team.
 | Language             | Client Library                           |
 | -------------------- | ---------------------------------------- |
 | Clojure              | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) |
+| DotNet               | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
+| DotNet (RestSharp)   | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
+| Elixir               | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
+| Elixir               | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
 | Go                   | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) |
 | Java (OSGi)          | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) |
 | Java (Fabric8, OSGi) | [github.com/fabric8io/kubernetes-client](https://github.com/fabric8io/kubernetes-client) |
@ -114,19 +115,20 @@ their authors, not the Kubernetes team.
 | Python               | [github.com/Frankkkkk/pykorm](https://github.com/Frankkkkk/pykorm) |
 | Ruby                 | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) |
 | Ruby                 | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) |
+| Ruby                 | [github.com/k8s-ruby/k8s-ruby](https://github.com/k8s-ruby/k8s-ruby) |
 | Ruby                 | [github.com/kontena/k8s-client](https://github.com/kontena/k8s-client) |
 | Rust                 | [github.com/clux/kube-rs](https://github.com/clux/kube-rs) |
 | Rust                 | [github.com/ynqa/kubernetes-rust](https://github.com/ynqa/kubernetes-rust) |
 | Scala                | [github.com/hagay3/skuber](https://github.com/hagay3/skuber) |
 | Scala                | [github.com/joan38/kubernetes-client](https://github.com/joan38/kubernetes-client) |
-| DotNet               | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
-| DotNet (RestSharp)   | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
-| Elixir               | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
-| Elixir               | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
 -->
 | 语言                 | 客户端库                                  |
 | -------------------- | ---------------------------------------- |
 | Clojure              | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) |
+| DotNet               | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
+| DotNet (RestSharp)   | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
+| Elixir               | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
+| Elixir               | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
 | Go                   | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) |
 | Java (OSGi)          | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) |
 | Java (Fabric8, OSGi) | [github.com/fabric8io/kubernetes-client](https://github.com/fabric8io/kubernetes-client) |
@ -149,16 +151,11 @@ their authors, not the Kubernetes team.
 | Python               | [github.com/Frankkkkk/pykorm](https://github.com/Frankkkkk/pykorm) |
 | Ruby                 | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) |
 | Ruby                 | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) |
+| Ruby                 | [github.com/k8s-ruby/k8s-ruby](https://github.com/k8s-ruby/k8s-ruby) |
 | Ruby                 | [github.com/kontena/k8s-client](https://github.com/kontena/k8s-client) |
 | Rust                 | [github.com/clux/kube-rs](https://github.com/clux/kube-rs) |
 | Rust                 | [github.com/ynqa/kubernetes-rust](https://github.com/ynqa/kubernetes-rust) |
 | Scala                | [github.com/hagay3/skuber](https://github.com/hagay3/skuber) |
 | Scala                | [github.com/joan38/kubernetes-client](https://github.com/joan38/kubernetes-client) |
 | Swift                | [github.com/swiftkube/client](https://github.com/swiftkube/client) |
-| DotNet               | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
-| DotNet (RestSharp)   | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
-| Elixir               | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
-| Elixir               | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
-
-

--- a/content/zh/docs/reference/using-api/deprecation-policy.md
+++ b/content/zh/docs/reference/using-api/deprecation-policy.md
@ -171,7 +171,8 @@ This covers the [maximum supported version skew of 2 releases](/docs/setup/relea
   * **Beta: 9 个月或者 3 个发布版本（取其较长者）**
   * **Alpha: 0 个发布版本**

-这里也包含了关于[最大支持 2 个发布版本的版本偏差](/zh/docs/setup/release/version-skew-policy/)的约定。
+这里也包含了关于[最大支持 2 个发布版本的版本偏差](/zh/docs/setup/release/version-skew-policy/)
+的约定。

 <!--
 Until [#52185](https://github.com/kubernetes/kubernetes/issues/52185) is
@ -181,7 +182,7 @@ deprecation timelines in this document), but the API server must remain capable
 of decoding/converting previously persisted data from storage.
 -->
 {{< note >}}
-在[#52185](https://github.com/kubernetes/kubernetes/issues/52185)被解决之前，
+在 [#52185](https://github.com/kubernetes/kubernetes/issues/52185) 被解决之前，
 已经被保存到持久性存储中的 API 版本都不可以被去除。
 你可以禁止这些版本所对应的 REST 末端（在符合本文中弃用时间线的前提下），
 但是 API 服务器必须仍能解析和转换存储中以前写入的数据。
@ -699,6 +700,14 @@ therefore the rules for deprecation are as follows:

 特性门控的版本管理与之前讨论的组件版本管理不同，因此其对应的弃用策略如下：

+<!--
+**Rule #8: Feature gates must be deprecated when the corresponding feature they control
+transitions a lifecycle stage as follows. Feature gates must function for no less than:**
+
+   * **Beta feature to GA: 6 months or 2 releases (whichever is longer)**
+   * **Beta feature to EOL: 3 months or 1 release (whichever is longer)**
+   * **Alpha feature to EOL: 0 releases**
+-->
 **规则 #8：特性门控所对应的功能特性经历下面所列的成熟性阶段转换时，特性门控
 必须被弃用。特性门控弃用时必须在以下时长内保持其功能可用：**

@ -730,8 +739,7 @@ this impacts removal of a metric during a Kubernetes release. These classes
 are determined by the perceived importance of the metric. The rules for
 deprecating and removing a metric are as follows:
 -->
-
-### 弃用度量值    {#Deprecating a metric}
+### 弃用度量值    {#deprecating-a-metric}

 Kubernetes 控制平面的每个组件都公开度量值（通常是 `/metrics` 端点），它们通常由集群管理员使用。
 并不是所有的度量值都是同样重要的：一些度量值通常用作 SLIs 或被使用来确定 SLOs，这些往往比较重要。
@ -755,20 +763,25 @@ Kubernetes 控制平面的每个组件都公开度量值（通常是 `/metrics`
 -->
 **规则 #9a: 对于相应的稳定性类别，度量值起作用的周期必须不小于：**

-   * **STABLE: 4 个发布版本或者 12 个月 (取其较长者)**
-   * **ALPHA: 0 个发布版本**
+* **STABLE: 4 个发布版本或者 12 个月 (取其较长者)**
+* **ALPHA: 0 个发布版本**

 **规则 #9b: 在度量值被宣布启用之后，它起作用的周期必须不小于：**

-   * **STABLE: 3 个发布版本或者 9 个月 (取其较长者)**
-   * **ALPHA: 0 个发布版本**
+* **STABLE: 3 个发布版本或者 9 个月 (取其较长者)**
+* **ALPHA: 0 个发布版本**

 <!--
 Deprecated metrics will have their description text prefixed with a deprecation notice
 string '(Deprecated from x.y)' and a warning log will be emitted during metric
 registration. Like their stable undeprecated counterparts, deprecated metrics will
 be automatically registered to the metrics endpoint and therefore visible.
+-->
+已弃用的度量值将在其描述文本前加上一个已弃用通知字符串 '(Deprecated from x.y)'，
+并将在度量值被记录期间发出警告日志。就像稳定的、未被弃用的度量指标一样，
+被弃用的度量值将自动注册到 metrics 端点，因此被弃用的度量值也是可见的。

+<!--
 On a subsequent release (when the metric's `deprecatedVersion` is equal to
 _current_kubernetes_version - 3_)), a deprecated metric will become a _hidden_ metric.
 **_Unlike_** their deprecated counterparts, hidden metrics will _no longer_ be
@ -779,15 +792,11 @@ escape hatch to properly migrate off of a deprecated metric, if they were not
 able to react to the earlier deprecation warnings. Hidden metrics should be
 deleted after one release.
 -->
-已弃用的度量值将在其描述文本前加上一个已弃用通知字符串 '(Deprecated from x.y)'，
-并将在度量值被记录期间发出警告日志。就像稳定的、未被弃用的度量指标一样，
-被弃用的度量值将自动注册到 metrics 端点，因此被弃用的度量值也是可见的。
-
 在随后的版本中（当度量值 `deprecatedVersion` 等于_当前 Kubernetes 版本 - 3_），
 被弃用的度量值将变成 _隐藏（Hidden）_ metric 度量值。
 与被弃用的度量值不同，隐藏的度量值将不再被自动注册到 metrics 端点（因此被隐藏）。
-但是，它们可以通过可执行文件的命令行标志显式启用（`--show-hidden-metrics-for-version=`）。
-
+但是，它们可以通过可执行文件的命令行标志显式启用
+（`--show-hidden-metrics-for-version=`）。
 如果集群管理员不能对早期的弃用警告作出反应，这一设计就为他们提供了抓紧迁移弃用度量值的途径。
 隐藏的度量值应该在再过一个发行版本后被删除。