diff --git a/content/zh-cn/docs/reference/command-line-tools-reference/feature-gates/allow-unsafe-malformed-object-deletion.md b/content/zh-cn/docs/reference/command-line-tools-reference/feature-gates/allow-unsafe-malformed-object-deletion.md new file mode 100644 index 0000000000000..82bd445fe5c73 --- /dev/null +++ b/content/zh-cn/docs/reference/command-line-tools-reference/feature-gates/allow-unsafe-malformed-object-deletion.md @@ -0,0 +1,22 @@ +--- +title: AllowUnsafeMalformedObjectDeletion +content_type: feature_gate +_build: + list: never + render: false + +stages: + - stage: alpha + defaultValue: false + fromVersion: "1.32" +--- + + +允许集群操作员使用 **list** 操作来辨别受损的资源, +引入一个 `ignoreStoreReadErrorWithClusterBreakingPotential` 选项, +集群操作员可以设置此选项并使用 Kubernetes API 对受损的资源执行不安全的强制 **delete** 操作。 diff --git a/content/zh-cn/docs/reference/command-line-tools-reference/feature-gates/cbor-serving-and-storage.md b/content/zh-cn/docs/reference/command-line-tools-reference/feature-gates/cbor-serving-and-storage.md new file mode 100644 index 0000000000000..747d6ebb98fb5 --- /dev/null +++ b/content/zh-cn/docs/reference/command-line-tools-reference/feature-gates/cbor-serving-and-storage.md @@ -0,0 +1,20 @@ +--- +title: CBORServingAndStorage +content_type: feature_gate +_build: + list: never + render: false + +stages: + - stage: alpha + defaultValue: false + fromVersion: "1.32" +--- + + +允许将 CBOR 用作[请求和响应所支持的编码方式](/zh-cn/docs/reference/using-api/api-concepts/#cbor-encoding), +同时允许将 CBOR 用作定制资源的首选存储编码方式。 diff --git a/content/zh-cn/docs/reference/using-api/api-concepts.md b/content/zh-cn/docs/reference/using-api/api-concepts.md index e102d898056fc..68b31375b0173 100644 --- a/content/zh-cn/docs/reference/using-api/api-concepts.md +++ b/content/zh-cn/docs/reference/using-api/api-concepts.md @@ -598,6 +598,64 @@ For example: Accept: application/vnd.kubernetes.protobuf, application/json ``` + +### CBOR 资源编码 {#cbor-encoding} + +{{< feature-state feature_gate_name="CBORServingAndStorage" >}} + + +启用 `CBORServingAndStorage` [特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/)后, +所有内置资源类型及所有由 {{< glossary_tooltip term_id="CustomResourceDefinition" text="CustomResourceDefinition" >}} +所定义的资源的请求体和响应体都可以被编码为 [CBOR](https://www.rfc-editor.org/rfc/rfc8949) 二进制数据格式。 +如果在各个聚合 API 服务器中启用了 CBOR, +则在{{< glossary_tooltip text="聚合层" term_id="aggregation-layer" >}}中也支持 CBOR。 + + +当请求体包含单个 CBOR [编码数据项](https://www.rfc-editor.org/rfc/rfc8949.html#section-1.2-4.2)时, +客户端应在 `Content-Type` HTTP 请求头中指明 IANA 媒体类型 `application/cbor`, +当准备接受响应中以 CBOR 编码的数据项时,客户端应在 `Accept` HTTP 请求头中指明 IANA 媒体类型 `application/cbor`。 +API 服务器将在响应体包含以 CBOR 编码的对象时在 `Content-Type` HTTP 响应头中使用 `application/cbor`。 + + +如果 API 服务器使用 CBOR 对 [watch 请求](#efficient-detection-of-changes)的响应进行编码, +则响应体将是一个 [CBOR 序列](https://www.rfc-editor.org/rfc/rfc8742), +而 `Content-Type` HTTP 响应头将使用 IANA 媒体类型 `application/cbor-seq`。 +此序列的每个条目(如果有的话)是一个以 CBOR 编码的 watch 事件。 + + +除了以 YAML 编码的[服务器端应用配置](#patch-and-apply)所用的现有 `application/apply-patch+yaml` 媒体类型之外, +启用 CBOR 的 API 服务器将接受 `application/apply-patch+cbor` 媒体类型用于以 CBOR 编码的服务器端应用配置。 +对于 `application/json-patch+json`、`application/merge-patch+json` 或 +`application/strategic-merge-patch+json`,没有支持的 CBOR 等效类型。 + 在大型集群检索某些资源类型的集合可能会导致控制平面的资源使用量(主要是 RAM)显著增加。 为了减轻其影响并简化 **list** + **watch** 模式的用户体验, -Kubernetes 1.27 版本引入了一个 alpha 功能,支持在 **watch** 请求中请求初始状态 -(之前在 **list** 请求中请求)。 +Kubernetes v1.32 将在 **watch** 请求中请求初始状态(之前在 **list** 请求中请求)的特性进阶至 Beta。 -如果启用了 `WatchList` [特性门控](/zh-cn/docs/reference/command-line-tools-reference/feature-gates/), -可以通过在 **watch** 请求中指定 `sendInitialEvents=true` 作为查询字符串参数来实现这一功能。 +在客户端,可以通过在 **watch** 请求中指定 `sendInitialEvents=true` 作为查询字符串参数来请求初始状态。 如果指定了这个参数,API 服务器将使用合成的初始事件(类型为 `ADDED`)来启动监视流, 以构建所有现有对象的完整状态;如果请求还带有 `allowWatchBookmarks=true` 选项, 则继续发送 [`BOOKMARK` 事件](/zh-cn/docs/reference/using-api/api-concepts/#watch-bookmarks)。 @@ -1360,6 +1422,77 @@ Once the last finalizer is removed, the resource is actually removed from etcd. 当最后一个终结器也被移除时,资源才真正从 etcd 中移除。 + +### 强制删除 {#force-deletion} + +{{< feature-state feature_gate_name="AllowUnsafeMalformedObjectDeletion" >}} + +{{< caution >}} + +如果强制删除依赖于正常的删除流程,这可能会破坏与正强制删除的资源关联的工作负载,因此可能会导致集群出现严重后果。 +{{< /caution >}} + + +通过启用删除选项 `ignoreStoreReadErrorWithClusterBreakingPotential`, +用户可以对无法解密或损坏的资源执行不安全的强制**删除**操作。 +使用此选项需要先启用一个 Alpha 特性门控,默认是禁用的。 +要使用此选项,集群操作员必须通过设置命令行选项 +`--feature-gates=AllowUnsafeMalformedObjectDeletion=true` 来启用此特性。 + +{{< note >}} + +执行强制**删除**操作的用户必须拥有对给定资源执行 **delete** 和 **unsafe-delete-ignore-read-errors** 动作的权限。 +{{< /note >}} + + +如果某资源由于 + +1. 转换错误(例如解密失败)或 +1. 对象解码失败 + +导致无法从存储中成功检索,则该资源被视为已损坏。 +API 服务器会先尝试正常删除,如果由于**资源损坏**的错误而删除失败,则触发强制删除。 +强制 **delete** 操作是不安全的,因为它会忽略终结器(Finalizer)约束,并跳过前置条件检查。 + + +此选项的默认值为 `false`,这是为了保持向后兼容性。对于将 +`ignoreStoreReadErrorWithClusterBreakingPotential` 设置为 `true` 的 **delete** 请求, +`dryRun`、`gracePeriodSeconds`、`orphanDependents`、`preconditions` 和 `propagationPolicy` 字段必须保持不设置。 + +{{< note >}} + +如果用户对一个可以以其他方式读取的资源发出将 `ignoreStoreReadErrorWithClusterBreakingPotential` +设置为 `true` 的 **delete** 请求,API 服务器将中止此请求并报错。 +{{< /note >}} +