根据集群 ID，更新指定集群的 Secret 落盘加密功能配置。
接口说明
- 开启或关闭落盘加密功能的过程中以及成功开启该功能后，请勿使用 KMS 控制台或 OpenAPI 禁用或删除该功能所使用的 KMS 密钥，否则会导致集群 API Server 不可用，继而无法正常获取 Secret 和 ServiceAccount 等对象，影响业务应用的正常运行。更多信息，请参见使用阿里云 KMS 进行 Secret 的落盘加密。
- 调用该 API 的用户或角色需要额外被授予所需的集群 RBAC 权限（需要被授予运维人员或管理员权限），否则将返回“ForbiddenUpdateKMSState”错误码。
- 成功调用该 API 后，集群状态将被变更为“更新中”，待变更完成后集群状态将恢复为“运行中”。针对同一个集群的变更完成后，需要间隔 5 分钟以上才能再次调用该 API，否则将返回“409”状态码。
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
- 操作：是指具体的权限点。
- 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
- 资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用
全部资源表示。
- 条件关键字：是指云产品自身定义的条件关键字。
- 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
| 操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
|---|---|---|---|---|
| cs:UpdateKMSEncryption | none | *Cluster acs:cs:{#regionId}:{#accountId}:cluster/{#ClusterId} |
| 无 |
请求语法
PUT /clusters/{ClusterId}/kms HTTP/1.1
请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| ClusterId | string | 是 | 集群 ID。 | c4fe1e3a721544*** |
| body | object | 否 | 请求体参数。 | |
| kms_key_id | string | 否 | Secret 落盘加密功能使用的 KMS 密钥 ID。 注意 不能使用服务密钥，只能使用主密钥或者用户主密钥。该密钥的密钥类型必须是 Aliyun_AES_256，密钥用途必须是 ENCRYPT/DECRYPT。
警告 开启或关闭落盘加密功能的过程中以及成功开启该功能后，请勿使用 KMS 控制台或 OpenAPI 禁用或删除该 KMS 密钥，否则会导致集群 API Server 不可用，继而无法正常获取 Secret 和 ServiceAccount 等对象，影响业务应用的正常运行。 | key-abc*** |
| disable_encryption | boolean | 否 | 是否禁用 Secret 落盘加密功能。
| false |
返回参数
示例
正常返回示例
JSON格式
{}错误码
访问错误中心查看更多错误码。
变更历史
| 变更时间 | 变更内容概要 | 操作 |
|---|---|---|
| 2026-02-26 | 新增 OpenAPI | 查看变更详情 |