更新 Managed Kafka ACL

创建 Managed Service for Apache Kafka ACL 资源后，您可以修改其配置以更新 ACL 条目列表。

您可以通过以下两种方式更新 Managed Service for Apache Kafka ACL 资源：

完全替换：覆盖整个 ACL 条目列表，如本页中所述。
增量更新：添加或移除单个 ACL 条目，如添加 ACL 条目和移除 ACL 条目页面中所述。

您无法使用更新操作将 ACL 条目列表修改为空。如需移除资源模式的所有条目，请改为删除 Managed Service for Apache Kafka ACL 资源。

所需的角色和权限

如需获得更新 Managed Service for Apache Kafka ACL 所需的权限，请让您的管理员为您授予项目的 Managed Kafka ACL Editor (roles/managedkafka.aclEditor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含更新 Managed Service for Apache Kafka ACL 所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需更新 Managed Service for Apache Kafka ACL，您需要具备以下权限：

在所请求的 ACL 上授予此权限，以使用完全替换 (UpdateAcl API) 进行更新： managedkafka.acls.update
授予对所请求 ACL 的此权限，以便使用增量更改（AddAclEntry 或 RemoveAclEntry API）进行更新： managedkafka.acls.updateEntries

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解 Managed Kafka ACL Editor 角色，请参阅 Google Cloud Managed Service for Apache Kafka 预定义角色。

etag 属性

etag 字段用于乐观并发控制。在对 GetAcl 和 CreateAcl 操作的响应中返回 etag。您必须在 UpdateAcl 请求中包含此 ETag，以确保您的更改应用于您检索到的 Managed Service for Apache Kafka ACL 资源的同一版本。这样可以防止在资源被同时修改时丢失更新。

如果 etag 中包含结尾字符 T，则表示 ACL 条目列表在响应中被截断，因为该列表超出了可重复字段项的最大数量。此资源模式的更多条目直接存在于 Kafka 集群中，但无法在 Managed Service for Apache Kafka ACL 资源中表示。对于具有截断 ACL 条目的资源，不支持完全替换更新。在这种情况下，请使用标准 Apache Kafka API（例如 kafka-acls.sh 或 AdminClient）直接管理 ACL。

完全替换 ACL 条目

您可以使用 UpdateAcl API 方法或 gcloud managed-kafka acls update 命令来完全替换 ACL 条目列表。资源中的整个 acl_entries 字段会被更新请求中发送的列表覆盖。

如需使用此方法修改列表（例如，在保留其他 ACL 条目的同时添加或移除单个 ACL 条目），请执行以下步骤：

使用 describe 命令检索当前 ACL 条目列表和 etag。
构建新的 ACL 条目列表。
运行 gcloud managed-kafka acls update 命令以及检索到的 etag。

以下部分展示了如何使用 gcloud managed-kafka acls update 命令来完全替换 ACL 条目列表。

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
运行 gcloud managed-kafka acls update 命令以将所有现有 ACL 条目替换为指定的条目：

gcloud managed-kafka acls update ACL_ID \
    --cluster=CLUSTER_ID \
    --location=LOCATION \
    --etag=ETAG_VALUE \
    --acl-entry=principal='PRINCIPAL',operation=OPERATION_TYPE,permission_type=PERMISSION_TYPE,host='*' \

替换以下内容：

ACL_ID（必需）：要更新的 Managed Service for Apache Kafka ACL 资源的 ID。如需详细了解 ACL ID，请参阅 ACL ID。
CLUSTER_ID（必需）：包含 ACL 资源的集群的 ID。
LOCATION（必需）：集群所在的区域。如需详细了解支持的区域，请参阅支持的位置。
ETAG_VALUE（必需）：从之前针对此 ACL 资源执行的 describe 或 create 操作中获得的 etag 值。
--acl-entry（必需）：指定要包含在新列表中的 ACL 条目。您可以重复使用此标志来添加多个条目。整个现有列表会被命令中指定的条目替换。

PRINCIPAL（必需）：相应 ACL 条目的正文。使用 User:{google_service_account_email} 格式或通配符 User:*。
OPERATION_TYPE（必需）：相应 ACL 条目的操作类型。允许的值包括 ALL、READ、WRITE、CREATE、DELETE、ALTER、DESCRIBE、CLUSTER_ACTION、DESCRIBE_CONFIGS、ALTER_CONFIGS 和 IDEMPOTENT_WRITE。
PERMISSION_TYPE（必需）：要更新的权限类型：ALLOW 或 DENY。
HOST（必需）：要更新的 ACL 条目的客户端主机。对于 Google Cloud Managed Service for Apache Kafka，此值必须设置为通配符 '*'。

完全替换示例

此命令会将 us-central1 中 test-kafka-cluster 内的 topic/orders 资源模式的所有现有 ACL 条目替换为一个新条目。此新条目向服务账号 producer-app@test-project.iam.gserviceaccount.com 授予了 WRITE 权限。该命令需要 ACL 资源的当前 etag，在本例中为 "AYk=Ags="。

gcloud managed-kafka acls update topic/orders \
    --cluster=test-kafka-cluster \
    --location=us-central1 \
    --project=test-project \
    --etag='"AYk=Ags="' \
    --acl-entry=principal='User:producer-app@test-project.iam.gserviceaccount.com',operation=WRITE,permission_type=ALLOW,host='*'

如果命令成功，输出会显示更新后的 ACL 资源配置，包括新的 aclEntries 列表和新的 etag。系统会移除此 ACL 资源的所有先前存在的条目。

aclEntries:
-   host: '*'
  operation: WRITE
  permissionType: ALLOW
  principal: User:producer-app@test-project.iam.gserviceaccount.com
etag: '"Bcn=Def="'  # Note: The etag value changes after a successful update.
name: projects/test-project/locations/us-central1/clusters/my-kafka-cluster/acls/topic/orders
resourcePatternType: TOPIC

ACL 条目的增量更新

您可以使用 AddAclEntry 和 RemoveAclEntry API 方法或相应的 gcloud managed-kafka acls add-acl-entry 和 gcloud managed-kafka acls remove-acl-entry 命令来添加或移除个别 ACL 条目，而无需替换整个列表。这些方法不需要 ETag。

使用 AddAclEntry 会向 Managed Service for Apache Kafka ACL 资源添加单个新的 ACL 条目。这类似于创建单个新的 Apache Kafka AclBinding。如需了解详情，请参阅添加 ACL 条目。
使用 RemoveAclEntry 可从 Managed Service for Apache Kafka ACL 资源中移除单个现有 ACL 条目。这类似于删除单个 Apache Kafka AclBinding。如需了解详情，请参阅移除 ACL 条目。

后续步骤

Apache Kafka® 是 Apache Software Foundation 或其关联公司在美国和/或其他国家/地区的注册商标。