Replace the ACL entries in a Managed Kafka ACL

This document describes how to update a Managed Kafka ACL resource with a new list of ACL entries.

You can't update an ACL with an empty list of entries. To remove all ACL entries for an ACL, delete the Managed Kafka ACL resource. For more information, see Delete a Managed Kafka ACL.

You can also add or remove individual ACL entries. For more information, see the following documents:

Required roles and permissions

To get the permissions that you need to update a Managed Kafka ACL, ask your administrator to grant you the Managed Kafka ACL Editor (roles/managedkafka.aclEditor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to update a Managed Kafka ACL. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to update a Managed Kafka ACL:

  • All: managedkafka.acls.update

You might also be able to get these permissions with custom roles or other predefined roles.

Retrieve the ETag for the ACL

When you perform an update operation on a Managed Kafka ACL, you must provide an ETag. The ETag ensures that changes are applied to the same version of the ACL entries that exists in the Kafka cluster.

To get the current ETag for an ACL, see View a Managed Kafka ACL.

If the ETag contains a terminal 'T' character, it indicates that the ACL entries are truncated. In that case, you can't use the Managed Kafka API to perform the update operation. Instead, use standard Apache Kafka tools such as kafka-acls.sh or AdminClient to manage the ACLs directly.

Replace ACL entries

gcloud

Run the gcloud managed-kafka acls update command:

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-entry= ...

Replace the following:

  • ACL_ID: The ID of the Managed Kafka ACL resource to update. For more information, see ACL ID.

  • CLUSTER_ID: The ID of your Kafka cluster.

  • LOCATION: The region of your Kafka cluster.

  • ETAG_VALUE: The ETag for the ACL.

For each ACL entry that you want to include in the updated ACL, specify a separate --acl-entry flag and replace the following:

  • PRINCIPAL: The principal for the ACL entry.

  • OPERATION: The operation type, such as READ or CREATE.

  • PERMISSION_TYPE: The permission that the principal has for the operation. Specify either ALLOW or DENY.

Example for replacing ACL entries

This command replaces all existing ACL entries for the topic/orders resource pattern in the test-kafka-cluster located in us-central1 with a single new entry. This new entry grants WRITE permission to the service account producer-app@test-project.iam.gserviceaccount.com. The command requires the current etag of the ACL resource which is "AYk=Ags=" in this example.

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='*'

If the command is successful, the output shows the updated ACL resource configuration, including the new aclEntries list and a new etag. Any previously existing entries for this ACL resource are removed.

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

What's next

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.