Update a Managed Kafka ACL

After creating a Managed Service for Apache Kafka ACL resource, you can edit its configuration to update the list of ACL entries.

Updating a Managed Service for Apache Kafka ACL resource can be done in two ways:

Full replacement: overwrites the entire list of ACL entries as documented in this page.
Incremental update: adds or removes a single ACL entry as documented in Add an ACL entry and Remove an ACL entry pages.

You cannot modify the ACL entries list to be empty by using an update operation. To remove all entries for a resource pattern, delete the Managed Service for Apache Kafka ACL resource instead.

Required roles and permissions

To get the permissions that you need to update a Managed Service for Apache 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 Service for Apache 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 Service for Apache Kafka ACL:

Grant this permission on the requested ACL to update using full replacement (UpdateAcl API): managedkafka.acls.update
Grant this permission on the requested ACL to update using incremental changes (AddAclEntry or RemoveAclEntry API): managedkafka.acls.updateEntries

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

For more information about the Managed Kafka ACL Editor role, see Google Cloud Managed Service for Apache Kafka predefined roles.

The etag property

The etag field is used for optimistic concurrency control. An etag is returned in the response to the GetAcl and CreateAcl operations. You must include this etag in the UpdateAcl request to ensure that your changes apply to the same version of the Managed Service for Apache Kafka ACL resource that you retrieved. This prevents lost updates if the resource was modified concurrently.

A terminal T character in the etag indicates that the ACL entries list was truncated in the response because it exceeded the maximum number of repeatable field items. More entries for this resource pattern exist directly on the Kafka cluster but couldn't be represented in the Managed Service for Apache Kafka ACL resource. Full replacement updates are not supported for resources with truncated ACL entries. In this scenario, use standard Apache Kafka APIs like kafka-acls.sh or the AdminClient to manage the ACLs directly.

Full replacement of ACL entries

You can use the UpdateAcl API method or the gcloud managed-kafka acls update command to perform a full replacement of the ACL entries list. The entire acl_entries field in the resource is overwritten by the list sent in the update request.

To modify the list using this method, for example, to add or remove a single ACL entry while keeping others, perform the following steps:

Retrieve the current list of ACL entries and the etag by using the describe command.
Construct the new list of ACL entries.
Run the gcloud managed-kafka acls update command along with the retrieved etag.

The following section shows how to use the gcloud managed-kafka acls update command to perform a full replacement of the ACL entries list.

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
```
Run the gcloud managed-kafka acls update command to replace all existing ACL entries with the specified ones:

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

Replace the following:

ACL_ID (required): the ID of the Managed Service for Apache Kafka ACL resource to update. For more information about the ACL ID, see ACL ID.
CLUSTER_ID (required): the ID of the cluster containing the ACL resource.
LOCATION (required): the region where the cluster is located. For more information about the region, see Supported locations.
ETAG_VALUE (required): the etag value obtained from a previous describe or create operation for this ACL resource.
--acl-entry (required): Specifies an ACL entry to include in the new list. You can repeat this flag to include multiple entries. The entire existing list is replaced by the entries specified in the command.

PRINCIPAL (required): the principal for this ACL entry. Use the format User:{google_service_account_email} or the wildcard User:*.
OPERATION_TYPE (required): the operation type for this ACL entry. Allowed values include ALL, READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, CLUSTER_ACTION, DESCRIBE_CONFIGS, ALTER_CONFIGS, and IDEMPOTENT_WRITE.
PERMISSION_TYPE (required): the type of permission to update: ALLOW or DENY.
HOST (required): the client host of the ACL entry to update. For Google Cloud Managed Service for Apache Kafka, this value must be set to the wildcard '*'.

Example for full replacement

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

Incremental update of ACL entries

You can add or remove individual ACL entry items without replacing the entire list using the AddAclEntry and RemoveAclEntry API methods or the corresponding gcloud managed-kafka acls add-acl-entry and gcloud managed-kafka acls remove-acl-entry commands. These methods don't require an etag.

Using AddAclEntry adds a single new ACL entry to the Managed Service for Apache Kafka ACL resource. This is analogous to creating a single new Apache Kafka AclBinding. For more information, see Add an ACL entry.
Using RemoveAclEntry removes a single existing ACL entry from the Managed Service for Apache Kafka ACL resource. This is analogous to deleting a single Apache Kafka AclBinding. For more information, see Remove an ACL entry.

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.