142 lines
9.0 KiB
Markdown
142 lines
9.0 KiB
Markdown
---
|
||
title: 声明式 API 验证
|
||
content_type: concept
|
||
weight: 20
|
||
---
|
||
<!--
|
||
title: Declarative API Validation
|
||
reviewers:
|
||
- aaron-prindle
|
||
- yongruilin
|
||
- jpbetz
|
||
- thockin
|
||
content_type: concept
|
||
weight: 20
|
||
-->
|
||
|
||
{{< feature-state for_k8s_version="v1.33" state="beta" >}}
|
||
|
||
<!--
|
||
Kubernetes {{< skew currentVersion >}} includes optional _declarative validation_ for APIs. When enabled, the Kubernetes API server can use this mechanism rather than the legacy approach that relies on hand-written Go
|
||
code (`validation.go` files) to ensure that requests against the API are valid.
|
||
Kubernetes developers, and people [extending the Kubernetes API](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/),
|
||
can define validation rules directly alongside the API type definitions (`types.go` files). Code authors define
|
||
pecial comment tags (e.g., `+k8s:minimum=0`). A code generator (`validation-gen`) then uses these tags to produce
|
||
optimized Go code for API validation.
|
||
-->
|
||
Kubernetes {{< skew currentVersion >}} 包含可选用于 API的**声明式验证**特性。
|
||
当启用时，Kubernetes API 服务器可以使用此机制而不是依赖手写的
|
||
Go 代码（`validation.go` 文件）来确保针对 API 的请求是有效的。
|
||
Kubernetes 开发者和[扩展 Kubernetes API](/zh-cn/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)
|
||
的人员可以直接在 API 类型定义（`types.go` 文件）旁边定义验证规则。
|
||
代码作者定义特殊的注释标签（例如，`+k8s:minimum=0`）。
|
||
然后，一个代码生成器（`validation-gen`）会使用这些标签来生成用于 API 验证的优化 Go 代码。
|
||
|
||
<!--
|
||
While primarily a feature impacting Kubernetes contributors and potentially developers of [extension API servers](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/), cluster administrators should understand its behavior, especially during its rollout phases.
|
||
-->
|
||
虽然这个特性主要影响 Kubernetes
|
||
贡献者和潜在的[扩展 API 服务器](/zh-cn/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)开发者，
|
||
但集群管理员应了解其行为，特别是在其推出阶段。
|
||
|
||
<!--
|
||
Declarative validation is being rolled out gradually.
|
||
In Kubernetes {{< skew currentVersion >}}, the APIs that use declarative validation include:
|
||
|
||
* [ReplicationController](/docs/concepts/workloads/controllers/replicationcontroller/)
|
||
-->
|
||
声明式验证正在逐步推出。
|
||
在 Kubernetes {{< skew currentVersion >}} 中，使用声明式验证的 API 包括：
|
||
|
||
* [ReplicationController](/zh-cn/docs/concepts/workloads/controllers/replicationcontroller/)
|
||
|
||
{{< note >}}
|
||
<!--
|
||
For the beta of this feature, Kubernetes is intentionally using a superseded API as a test bed for the change.
|
||
Future Kubernetes releases may roll this out to more APIs.
|
||
-->
|
||
对于此特性的 Beta 版，Kubernetes 故意使用一个被取代的 API 作为变更的试验场。
|
||
未来的 Kubernetes 版本可能会将此更改推广到更多 API。
|
||
{{< /note >}}
|
||
|
||
<!--
|
||
* `DeclarativeValidation`: (Beta, Default: `true`) When enabled, the API server runs *both* the new declarative validation and the old hand-written validation for migrated types/fields. The results are compared internally.
|
||
* `DeclarativeValidationTakeover`: (Beta, Default: `false`) This gate determines which validation result is *authoritative* (i.e., returned to the user and used for admission decisions).
|
||
-->
|
||
* `DeclarativeValidation：（Beta， 默认值：`true`）当启用时，
|
||
API 服务器对迁移的类型/字段同时运行新的声明式验证和旧的手写验证。结果在内部进行比较。
|
||
* `DeclarativeValidationTakeover`**：（Beta， 默认值：`false`）
|
||
此开关决定哪个验证结果是**权威的**（即返回给用户并用于准入决策）。
|
||
|
||
<!--
|
||
**Default Behavior (Kubernetes {{< skew currentVersion >}}):**
|
||
|
||
* With `DeclarativeValidation=true` and `DeclarativeValidationTakeover=false` (the default values for the gates), both validation systems run.
|
||
* **The results of the *hand-written* validation are used.** The declarative validation runs in a mismatch mode for comparison.
|
||
* Mismatches between the two validation systems are logged by the API server and increment the `declarative_validation_mismatch_total` metric. This helps developers identify and fix discrepancies during the Beta phase.
|
||
* **Cluster upgrades should be safe** regarding this feature, as the authoritative validation logic doesn't change by default.
|
||
-->
|
||
**默认行为（Kubernetes {{< skew currentVersion >}}）：**
|
||
|
||
* 当 `DeclarativeValidation=true` 和 `DeclarativeValidationTakeover=false` （开关的默认值），两种验证系统都会运行。
|
||
* **使用手写验证的结果。**声明式验证以不匹配模式运行进行比较。
|
||
* 两种验证系统之间的不匹配将由 API 服务器记录，并增加
|
||
`declarative_validation_mismatch_total` 指标。这有助于开发人员在
|
||
Beta 阶段识别并修复不一致之处。
|
||
* 关于此特性的**集群升级应该是安全的**，默认情况下权威的验证逻辑不会改变。
|
||
|
||
<!--
|
||
Administrators can choose to explicitly enable `DeclarativeValidationTakeover=true` to make the *declarative* validation authoritative for migrated fields, typically after verifying stability in their environment (e.g., by monitoring the mismatch metric).
|
||
-->
|
||
管理员可以选择显式启用 `DeclarativeValidationTakeover=true`
|
||
以使**声明式**验证对于迁移的字段具有权威性，通常是在验证其环境中的稳定性之后
|
||
（例如，通过监控不匹配指标）。
|
||
|
||
<!--
|
||
## Disabling declarative validation {#opt-out}
|
||
|
||
As a cluster administrator, you might consider disabling declarative validation whilst it is still beta, under specific circumstances:
|
||
-->
|
||
## 禁用声明式验证 {#opt-out}
|
||
|
||
作为集群管理员，在特定情况下，你可能会考虑在声明式验证仍然是测试版时禁用它：
|
||
|
||
<!--
|
||
* **Unexpected Validation Behavior:** If enabling `DeclarativeValidationTakeover` leads to unexpected validation errors or allows objects that were previously invalid.
|
||
* **Performance Regressions:** If monitoring indicates significant latency increases (e.g., in `apiserver_request_duration_seconds`) correlated with the feature's enablement.
|
||
* **High Mismatch Rate:** If the `declarative_validation_mismatch_total` metric shows frequent mismatches, suggesting potential bugs in the declarative rules affecting the cluster's workloads, even if `DeclarativeValidationTakeover` is false.
|
||
-->
|
||
* **意外的验证行为：** 如果启用 `DeclarativeValidationTakeover`
|
||
导致了未预期的验证错误或允许之前无效的对象。
|
||
* **性能回归：** 如果监控显示显著的延迟增加（例如，在 `apiserver_request_duration_seconds` 中），
|
||
且与该特性的启用相关联。
|
||
* **不匹配率高：** 如果 `declarative_validation_mismatch_total`
|
||
指标显示出频繁的不匹配，这暗示声明式规则中可能存在影响集群工作负载的潜在错误，
|
||
即使 `DeclarativeValidationTakeover` 为 false。
|
||
|
||
<!--
|
||
To revert to only using hand-written validation (as used before Kubernetes v1.33), disable the `DeclarativeValidation` feature gate, for example
|
||
via command-line arguments: (`--feature-gates=DeclarativeValidation=false`). This also implicitly disables the effect of `DeclarativeValidationTakeover`.
|
||
-->
|
||
要恢复为仅使用手写验证（如 Kubernetes v1.33 之前所用），请禁用
|
||
`DeclarativeValidation` 特性门控，例如
|
||
通过命令行参数：(`--feature-gates=DeclarativeValidation=false`)。
|
||
这也会隐式禁用 `DeclarativeValidationTakeover` 的效果。
|
||
|
||
<!--
|
||
## Considerations for downgrade and rollback
|
||
|
||
Disabling the feature acts as a safety mechanism. However, be aware of a potential edge case (considered unlikely due to extensive testing): If a bug in declarative validation (when `DeclarativeValidationTakeover=true`) *incorrectly allowed* an invalid object to be persisted, disabling the feature gates might then cause subsequent updates to that specific object to be blocked by the now-authoritative (and correct) hand-written validation. Resolving this might require manual correction of the stored object, potentially via direct etcd modification in rare cases.
|
||
|
||
For details on managing feature gates, see [Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/).
|
||
-->
|
||
## 降级和回滚的考虑事项
|
||
|
||
禁用特性特性充当一种安全机制。然而，要注意一个潜在的极端情况
|
||
（由于广泛测试，这种情况被认为是不太可能发生的）：
|
||
如果声明式验证中存在一个错误（当 `DeclarativeValidationTakeover=true` 时）
|
||
**错误地允许**无效对象被持久化，那么禁用特性门可能会导致后续对该特定对象的更新被现在权威的（且正确的）
|
||
手写验证所阻止。解决此问题可能需要手动更正存储的对象，在极少数情况下，可能需要通过直接修改 etcd 来进行。
|
||
|
||
有关管理特性门控的详细信息，请参阅[特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)。
|