Skip to content

Commit 7955eb6

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #40819 from windsonsea/openapi
[zh] sync 2023-04-24-openapi-v3-field-validation-ga.md
2 parents b8c83b2 + 88124ea commit 7955eb6

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

‎content/zh-cn/blog/_posts/2023-04-24-openapi-v3-field-validation-ga.md

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
layout: blog
3+
title: "Kubernetes 1.27：服务器端字段校验和 OpenAPI V3 进阶至 GA"
4+
date: 2023-04-24
5+
slug: openapi-v3-field-validation-ga
6+
---
7+
<!--
8+
layout: blog
9+
title: "Kubernetes 1.27: Server Side Field Validation and OpenAPI V3 move to GA"
10+
date: 2023-04-24
11+
slug: openapi-v3-field-validation-ga
12+
-->
13+
14+
<!--
15+
**Author**: Jeffrey Ying (Google), Antoine Pelisse (Google)
16+
-->
17+
**作者**：Jeffrey Ying (Google), Antoine Pelisse (Google)
18+
19+
**译者**：Michael Yao (DaoCloud)
20+
21+
<!--
22+
Before Kubernetes v1.8 (!), typos, mis-indentations or minor errors in
23+
YAMLs could have catastrophic consequences (e.g. a typo like
24+
forgetting the trailing s in `replica: 1000` could cause an outage,
25+
because the value would be ignored and missing, forcing a reset of
26+
replicas back to 1). This was solved back then by fetching the OpenAPI
27+
v2 in kubectl and using it to verify that fields were correct and
28+
present before applying. Unfortunately, at that time, Custom Resource
29+
Definitions didn’t exist, and the code was written under that
30+
assumption. When CRDs were later introduced, the lack of flexibility
31+
in the validation code forced some hard decisions in the way CRDs
32+
exposed their schema, leaving us in a cycle of bad validation causing
33+
bad OpenAPI and vice-versa. With the new OpenAPI v3 and Server Field
34+
Validation being GA in 1.27, we’ve now solved both of these problems.
35+
-->
36+
在 Kubernetes v1.8 之前，YAML 文件中的拼写错误、缩进错误或其他小错误可能会产生灾难性后果
37+
（例如像在 `replica: 1000` 中忘记了结尾的字母 “s”，可能会导致宕机。
38+
因为该值会被忽略并且丢失，并强制将副本重置回 1）。当时解决这个问题的办法是：
39+
在 kubectl 中获取 OpenAPI v2 并在应用之前使用 OpenAPI v2 来校验字段是否正确且存在。
40+
不过当时没有自定义资源定义 (CRD)，相关代码是在当时那样的假设下编写的。
41+
之后引入了 CRD，发现校验代码缺乏灵活性，迫使 CRD 在公开其模式定义时做出了一些艰难的决策，
42+
使得我们进入了不良校验造成不良 OpenAPI，不良 OpenAPI 无法校验的循环。
43+
随着新的 OpenAPI v3 和服务器端字段校验在 1.27 中进阶至 GA，我们现在已经解决了这两个问题。
44+
45+
<!--
46+
Server Side Field Validation offers resource validation on create,
47+
update and patch requests to the apiserver and was added to Kubernetes
48+
in v1.25, beta in v1.26 and is now GA in v1.27. It provides all the
49+
functionality of kubectl validate on the server side.
50+
-->
51+
服务器端字段校验针对通过 create、update 和 patch 请求发送到 apiserver 上的资源进行校验，
52+
此特性是在 Kubernetes v1.25 中添加的，在 v1.26 时进阶至 Beta，
53+
如今在 v1.27 进阶至 GA。它在服务器端提供了 kubectl 校验的所有功能。
54+
55+
<!--
56+
[OpenAPI](https://swagger.io/specification/) is a standard, language
57+
agnostic interface for discovering the set of operations and types
58+
that a Kubernetes cluster supports. OpenAPI V3 is the latest standard
59+
of the OpenAPI and is an improvement upon [OpenAPI
60+
V2](https://kubernetes.io/blog/2016/12/kubernetes-supports-openapi/)
61+
which has been supported since Kubernetes 1.5. OpenAPI V3 support was
62+
added in Kubernetes in v1.23, moved to beta in v1.24 and is now GA in
63+
v1.27.
64+
-->
65+
[OpenAPI](https://swagger.io/specification/) 是一个标准的、与编程语言无关的接口，
66+
用于发现 Kubernetes 集群支持的操作集和类型集。
67+
OpenAPI v3 是 OpenAPI 的最新标准，它是自 Kubernetes 1.5 开始支持的
68+
[OpenAPI v2](https://kubernetes.io/blog/2016/12/kubernetes-supports-openapi/)
69+
的改进版本。对 OpenAPI v3 的支持是在 Kubernetes v1.23 中添加的，
70+
v1.24 时进阶至 Beta，如今在 v1.27 进阶至 GA。
71+
72+
<!--
73+
## OpenAPI V3
74+
75+
### What does OpenAPI V3 offer over V2
76+
77+
#### Built-in types
78+
-->
79+
## OpenAPI v3
80+
81+
### OpenAPI v3 相比 v2 提供了什么？
82+
83+
#### 插件类型
84+
85+
<!--
86+
Kubernetes offers certain annotations on fields that are not
87+
representable in OpenAPI V2, or sometimes not represented in the
88+
OpenAPI v2 that Kubernetes generate. Most notably, the "default" field
89+
is published in OpenAPI V3 while omitted in OpenAPI V2. A single type
90+
that can represent multiple types is also expressed correctly in
91+
OpenAPI V3 with the oneOf field. This includes proper representations
92+
for IntOrString and Quantity.
93+
-->
94+
Kubernetes 对 OpenAPI v2 中不能表示或有时在 Kubernetes 生成的 OpenAPI v2
95+
中未表示的某些字段提供了注解。最明显地，OpenAPI v3 发布了 “default” 字段，
96+
而在 OpenAPI v2 中被省略。表示多种类型的单个类型也能在 OpenAPI v3 中使用
97+
oneOf 字段被正确表达。这包括针对 IntOrString 和 Quantity 的合理表示。
98+
99+
<!--
100+
#### Custom Resource Definitions
101+
102+
In Kubernetes, Custom Resource Definitions use a structural OpenAPI V3
103+
schema that cannot be represented as OpenAPI V2 without a loss of
104+
certain fields. Some of these include nullable, default, anyOf, oneOf,
105+
not, etc. OpenAPI V3 is a completely lossless representation of the
106+
CustomResourceDefinition structural schema.
107+
-->
108+
#### CRD
109+
110+
在 Kubernetes 中，自定义资源定义 (CRD) 使用结构化的 OpenAPI v3 模式定义，
111+
无法在不损失某些字段的情况下将其表示为 OpenAPI v2。这些包括
112+
nullable、default、anyOf、oneOf、not 等等。OpenAPI v3 是
113+
CustomResourceDefinition 结构化模式定义的完全无损表示。
114+
115+
<!--
116+
### How do I use it?
117+
118+
The OpenAPI V3 root discovery can be found at the `/openapi/v3`
119+
endpoint of a Kubernetes API server. OpenAPI V3 documents are grouped
120+
by group-version to reduce the size of the data transported, the
121+
separate documents can be accessed at
122+
`/openapi/v3/apis/<group>/<version>` and `/openapi/v3/api/v1`
123+
representing the legacy group version. Please refer to the [Kubernetes
124+
API Documentation](/docs/concepts/overview/kubernetes-api/) for more
125+
information around this endpoint.
126+
-->
127+
### 如何使用？
128+
129+
Kubernetes API 服务器的 `/openapi/v3` 端点包含了 OpenAPI v3 的根发现文档。
130+
为了减少传输的数据量，OpenAPI v3 文档以 group-version 的方式进行分组，
131+
不同的文档可以通过 `/openapi/v3/apis/<group>/<version>` 和 `/openapi/v3/api/v1`
132+
（表示旧版 group）进行访问。有关此端点的更多信息请参阅
133+
[Kubernetes API 文档](/zh-cn/docs/concepts/overview/kubernetes-api/)。
134+
135+
<!--
136+
Various consumers of the OpenAPI have already been updated to consume
137+
v3, including the entirety of kubectl, and server side apply. An
138+
OpenAPI V3 Golang client is available in
139+
[client-go](https://github.com/kubernetes/client-go/blob/release-1.27/openapi3/root.go).
140+
-->
141+
众多使用 OpenAPI 的客户侧组件已更新到了 v3，包括整个 kubectl 和服务器端应用。
142+
在 [client-go](https://github.com/kubernetes/client-go/blob/release-1.27/openapi3/root.go)
143+
中也提供了 OpenAPI V3 Golang 客户端。
144+
145+
<!--
146+
## Server Side Field Validation
147+
148+
The query parameter `fieldValidation` may be used to indicate the
149+
level of field validation the server should perform. If the parameter
150+
is not passed, server side field validation is in `Warn` mode by
151+
default.
152+
-->
153+
## 服务器端字段校验
154+
155+
查询参数 `fieldValidation` 可用于指示服务器应执行的字段校验级别。
156+
如果此参数未被传递，服务器端字段校验默认采用 `Warn` 模式。
157+
158+
<!--
159+
- Strict: Strict field validation, errors on validation failure
160+
- Warn: Field validation is performed, but errors are exposed as
161+
warnings rather than failing the request
162+
- Ignore: No server side field validation is performed
163+
-->
164+
- Strict：严格的字段校验，在验证失败时报错
165+
- Warn：执行字段校验，但错误会以警告的形式给出，而不是使请求失败
166+
- Ignore：不执行服务器端的字段校验
167+
168+
<!--
169+
kubectl will skip client side validation and will automatically use
170+
server side field validation in `Strict` mode. Controllers by default
171+
use server side field validation in `Warn` mode.
172+
173+
With client side validation, we had to be extra lenient because some
174+
fields were missing from OpenAPI V2 and we didn’t want to reject
175+
possibly valid objects. This is all fixed in server side validation.
176+
Additional documentation may be found
177+
[here](/docs/reference/using-api/api-concepts/#field-validation)
178+
-->
179+
kubectl 将跳过客户端校验，并将自动使用 `Strict` 模式下的服务器端字段校验。
180+
控制器默认使用 `Warn` 模式进行服务器端字段校验。
181+
182+
使用客户端校验时，由于 OpenAPI v2 中缺少某些字段，所以我们必须更加宽容，
183+
以免拒绝可能有效的对象。而在服务器端校验中，所有这些问题都被修复了。
184+
可以在[此处](/zh-cn/docs/reference/using-api/api-concepts/#field-validation)找到更多文档。
185+
186+
<!--
187+
## What's next?
188+
189+
With Server Side Field Validation and OpenAPI V3 released as GA, we
190+
introduce more accurate representations of Kubernetes resources. It is
191+
recommended to use server side field validation over client side, but
192+
with OpenAPI V3, clients are free to implement their own validation if
193+
necessary (to “shift things left”) and we guarantee a full lossless
194+
schema published by OpenAPI.
195+
-->
196+
## 未来展望
197+
198+
随着服务器端字段校验和 OpenAPI v3 以 GA 发布，我们引入了更准确的 Kubernetes 资源表示。
199+
建议使用服务器端字段校验而非客户端校验，但是通过 OpenAPI v3，
200+
客户端可以在必要时自行实现其自身的校验（“左移”），我们保证 OpenAPI 发布的是完全无损的模式定义。
201+
202+
<!--
203+
Some existing efforts will further improve the information available
204+
through OpenAPI including [CEL validation and
205+
admission](/docs/reference/using-api/cel/), along with OpenAPI
206+
annotations on built-in types.
207+
208+
Many other tools can be built for authoring and transforming resources
209+
using the type information found in the OpenAPI v3.
210+
-->
211+
现在的一些工作将进一步改善通过 OpenAPI 提供的信息，例如
212+
[CEL 校验和准入](/zh-cn/docs/reference/using-api/cel/)以及对内置类型的 OpenAPI 注解。
213+
214+
使用在 OpenAPI v3 中的类型信息还可以构建许多其他工具来编写和转换资源。
215+
216+
<!--
217+
## How to get involved?
218+
219+
These two features are driven by the SIG API Machinery community,
220+
available on the slack channel \#sig-api-machinery, through the
221+
[mailing
222+
list](https://groups.google.com/g/kubernetes-sig-api-machinery) and we
223+
meet every other Wednesday at 11:00 AM PT on Zoom.
224+
-->
225+
## 如何参与？
226+
227+
这两个特性由 SIG API Machinery 社区驱动，欢迎加入 Slack 频道 \#sig-api-machinery，
228+
请查阅[邮件列表](https://groups.google.com/g/kubernetes-sig-api-machinery)，
229+
我们每周三 11:00 AM PT 在 Zoom 上召开例会。
230+
231+
<!--
232+
We offer a huge thanks to all the contributors who helped design,
233+
implement, and review these two features.
234+
-->
235+
我们对所有曾帮助设计、实现和审查这两个特性的贡献者们表示衷心的感谢。
236+
237+
- Alexander Zielenski
238+
- Antoine Pelisse
239+
- Daniel Smith
240+
- David Eads
241+
- Jeffrey Ying
242+
- Jordan Liggitt
243+
- Kevin Delgado
244+
- Sean Sullivan

0 commit comments

Comments
 (0)