Skip to content

Commit 869ce6a

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #28348 from tengqm/zh-sync-usingapi
[zh] Resync using-api section
2 parents 6b324fe + f44e3ff commit 869ce6a

File tree

3 files changed

+44
-38
lines changed

3 files changed

+44
-38
lines changed

‎content/zh/docs/reference/using-api/api-concepts.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -463,7 +463,7 @@ Accept: application/json;as=Table;g=meta.k8s.io;v=v1beta1, application/json
463463
<!--
464464
## Alternate representations of resources
465465
466-
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.
466+
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.
467467
468468
See the API documentation for a list of supported content types for each API.
469469
@@ -983,7 +983,7 @@ The meaning of the get and list semantics are:
983983
- **Any:** Return data at any resource version. The newest available resource version is preferred,
984984
but strong consistency is not required; data at any resource version may be served. It is possible
985985
for the request to return data at a much older resource version that the client has previously
986-
observed, particularly in high availabiliy configurations, due to partitions or stale
986+
observed, particularly in high availability configurations, due to partitions or stale
987987
caches. Clients that cannot tolerate this should not use this semantic.
988988
-->
989989
GET 和 LIST 操作的语义含义如下：
@@ -1142,7 +1142,7 @@ reply with a `410 Gone` HTTP response.
11421142
<!--
11431143
### Unavailable resource versions
11441144

1145-
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.
1145+
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.
11461146
-->
11471147
### 不可用的资源版本 {#unavailable-resource-versions}
11481148

‎content/zh/docs/reference/using-api/client-libraries.md

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,11 @@ weight: 30
55
---
66

77
<!--
8-
---
98
title: Client Libraries
109
reviewers:
1110
- ahmetb
1211
content_type: concept
1312
weight: 30
14-
---
1513
-->
1614

1715
<!-- overview -->
@@ -58,22 +56,21 @@ The following client libraries are officially maintained by
5856
<!--
5957
| Language | Client Library | Sample Programs |
6058
|----------|----------------|-----------------|
59+
| dotnet | [github.com/kubernetes-client/csharp](https://github.com/kubernetes-client/csharp) | [browse](https://github.com/kubernetes-client/csharp/tree/master/examples/simple)
6160
| Go | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [browse](https://github.com/kubernetes/client-go/tree/master/examples)
62-
| Python | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [browse](https://github.com/kubernetes-client/python/tree/master/examples)
61+
| Haskell | [github.com/kubernetes-client/haskell](https://github.com/kubernetes-client/haskell) | [browse](https://github.com/kubernetes-client/haskell/tree/master/kubernetes-client/example)
6362
| Java | [github.com/kubernetes-client/java](https://github.com/kubernetes-client/java/) | [browse](https://github.com/kubernetes-client/java#installation)
64-
| dotnet | [github.com/kubernetes-client/csharp](https://github.com/kubernetes-client/csharp) | [browse](https://github.com/kubernetes-client/csharp/tree/master/examples/simple)
6563
| JavaScript | [github.com/kubernetes-client/javascript](https://github.com/kubernetes-client/javascript) | [browse](https://github.com/kubernetes-client/javascript/tree/master/examples)
66-
| Haskell | [github.com/kubernetes-client/haskell](https://github.com/kubernetes-client/haskell) | [browse](https://github.com/kubernetes-client/haskell/tree/master/kubernetes-client/example)
64+
| Python | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [browse](https://github.com/kubernetes-client/python/tree/master/examples)
6765
-->
68-
| 语言 | 客户端库 | 样例程序 |
69-
|----------|----------------|-----------------|
66+
| 语言 | 客户端库 | 样例程序 |
67+
|---------|-----------------|-----------------|
68+
| dotnet | [github.com/kubernetes-client/csharp](https://github.com/kubernetes-client/csharp) | [浏览](https://github.com/kubernetes-client/csharp/tree/master/examples/simple)
7069
| Go | [github.com/kubernetes/client-go/](https://github.com/kubernetes/client-go/) | [浏览](https://github.com/kubernetes/client-go/tree/master/examples)
71-
| Python | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [浏览](https://github.com/kubernetes-client/python/tree/master/examples)
70+
| Haskell | [github.com/kubernetes-client/haskell](https://github.com/kubernetes-client/haskell) | [浏览](https://github.com/kubernetes-client/haskell/tree/master/kubernetes-client/example)
7271
| Java | [github.com/kubernetes-client/java](https://github.com/kubernetes-client/java/) | [浏览](https://github.com/kubernetes-client/java#installation)
73-
| dotnet | [github.com/kubernetes-client/csharp](https://github.com/kubernetes-client/csharp) | [浏览](https://github.com/kubernetes-client/csharp/tree/master/examples/simple)
7472
| JavaScript | [github.com/kubernetes-client/javascript](https://github.com/kubernetes-client/javascript) | [浏览](https://github.com/kubernetes-client/javascript/tree/master/examples)
75-
| Haskell | [github.com/kubernetes-client/haskell](https://github.com/kubernetes-client/haskell) | [浏览](https://github.com/kubernetes-client/haskell/tree/master/kubernetes-client/example)
76-
73+
| Python | [github.com/kubernetes-client/python/](https://github.com/kubernetes-client/python/) | [浏览](https://github.com/kubernetes-client/python/tree/master/examples)
7774

7875
<!--
7976
## Community-maintained client libraries
@@ -92,6 +89,10 @@ their authors, not the Kubernetes team.
9289
| Language | Client Library |
9390
| -------------------- | ---------------------------------------- |
9491
| Clojure | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) |
92+
| DotNet | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
93+
| DotNet (RestSharp) | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
94+
| Elixir | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
95+
| Elixir | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
9596
| Go | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) |
9697
| Java (OSGi) | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) |
9798
| Java (Fabric8, OSGi) | [github.com/fabric8io/kubernetes-client](https://github.com/fabric8io/kubernetes-client) |
@@ -114,19 +115,20 @@ their authors, not the Kubernetes team.
114115
| Python | [github.com/Frankkkkk/pykorm](https://github.com/Frankkkkk/pykorm) |
115116
| Ruby | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) |
116117
| Ruby | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) |
118+
| Ruby | [github.com/k8s-ruby/k8s-ruby](https://github.com/k8s-ruby/k8s-ruby) |
117119
| Ruby | [github.com/kontena/k8s-client](https://github.com/kontena/k8s-client) |
118120
| Rust | [github.com/clux/kube-rs](https://github.com/clux/kube-rs) |
119121
| Rust | [github.com/ynqa/kubernetes-rust](https://github.com/ynqa/kubernetes-rust) |
120122
| Scala | [github.com/hagay3/skuber](https://github.com/hagay3/skuber) |
121123
| Scala | [github.com/joan38/kubernetes-client](https://github.com/joan38/kubernetes-client) |
122-
| DotNet | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
123-
| DotNet (RestSharp) | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
124-
| Elixir | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
125-
| Elixir | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
126124
-->
127125
| 语言 | 客户端库 |
128126
| -------------------- | ---------------------------------------- |
129127
| Clojure | [github.com/yanatan16/clj-kubernetes-api](https://github.com/yanatan16/clj-kubernetes-api) |
128+
| DotNet | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
129+
| DotNet (RestSharp) | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
130+
| Elixir | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
131+
| Elixir | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
130132
| Go | [github.com/ericchiang/k8s](https://github.com/ericchiang/k8s) |
131133
| Java (OSGi) | [bitbucket.org/amdatulabs/amdatu-kubernetes](https://bitbucket.org/amdatulabs/amdatu-kubernetes) |
132134
| Java (Fabric8, OSGi) | [github.com/fabric8io/kubernetes-client](https://github.com/fabric8io/kubernetes-client) |
@@ -149,16 +151,11 @@ their authors, not the Kubernetes team.
149151
| Python | [github.com/Frankkkkk/pykorm](https://github.com/Frankkkkk/pykorm) |
150152
| Ruby | [github.com/abonas/kubeclient](https://github.com/abonas/kubeclient) |
151153
| Ruby | [github.com/Ch00k/kuber](https://github.com/Ch00k/kuber) |
154+
| Ruby | [github.com/k8s-ruby/k8s-ruby](https://github.com/k8s-ruby/k8s-ruby) |
152155
| Ruby | [github.com/kontena/k8s-client](https://github.com/kontena/k8s-client) |
153156
| Rust | [github.com/clux/kube-rs](https://github.com/clux/kube-rs) |
154157
| Rust | [github.com/ynqa/kubernetes-rust](https://github.com/ynqa/kubernetes-rust) |
155158
| Scala | [github.com/hagay3/skuber](https://github.com/hagay3/skuber) |
156159
| Scala | [github.com/joan38/kubernetes-client](https://github.com/joan38/kubernetes-client) |
157160
| Swift | [github.com/swiftkube/client](https://github.com/swiftkube/client) |
158-
| DotNet | [github.com/tonnyeremin/kubernetes_gen](https://github.com/tonnyeremin/kubernetes_gen) |
159-
| DotNet (RestSharp) | [github.com/masroorhasan/Kubernetes.DotNet](https://github.com/masroorhasan/Kubernetes.DotNet) |
160-
| Elixir | [github.com/obmarg/kazan](https://github.com/obmarg/kazan/) |
161-
| Elixir | [github.com/coryodaniel/k8s](https://github.com/coryodaniel/k8s) |
162-
163-
164161

‎content/zh/docs/reference/using-api/deprecation-policy.md

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,8 @@ This covers the [maximum supported version skew of 2 releases](/docs/setup/relea
171171
* **Beta: 9 个月或者 3 个发布版本（取其较长者）**
172172
* **Alpha: 0 个发布版本**
173173

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

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

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

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

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

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

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

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

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

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

784+
<!--
772785
On a subsequent release (when the metric's `deprecatedVersion` is equal to
773786
_current_kubernetes_version - 3_)), a deprecated metric will become a _hidden_ metric.
774787
**_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
779792
able to react to the earlier deprecation warnings. Hidden metrics should be
780793
deleted after one release.
781794
-->
782-
已弃用的度量值将在其描述文本前加上一个已弃用通知字符串 '(Deprecated from x.y)'，
783-
并将在度量值被记录期间发出警告日志。就像稳定的、未被弃用的度量指标一样，
784-
被弃用的度量值将自动注册到 metrics 端点，因此被弃用的度量值也是可见的。
785-
786795
在随后的版本中（当度量值 `deprecatedVersion` 等于_当前 Kubernetes 版本 - 3_），
787796
被弃用的度量值将变成 _隐藏（Hidden）_ metric 度量值。
788797
与被弃用的度量值不同，隐藏的度量值将不再被自动注册到 metrics 端点（因此被隐藏）。
789-
但是，它们可以通过可执行文件的命令行标志显式启用（`--show-hidden-metrics-for-version=`）。
790-
798+
但是，它们可以通过可执行文件的命令行标志显式启用
799+
（`--show-hidden-metrics-for-version=`）。
791800
如果集群管理员不能对早期的弃用警告作出反应，这一设计就为他们提供了抓紧迁移弃用度量值的途径。
792801
隐藏的度量值应该在再过一个发行版本后被删除。
793802

0 commit comments

Comments
 (0)