Add an ACL entry to a Managed Kafka ACL

You can add a single new permission rule called an ACL entry to a Managed Kafka ACL resource without replacing the entire list of entries. This is useful for granting specific permissions incrementally.

This operation is analogous to creating a single Apache Kafka ACL binding. It does not require the ACL resource to already exist and does not require an eTag for concurrency control.

Required roles and permissions

To get the permissions that you need to add an ACL entry, 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 add an ACL entry. To see the exact permissions that are required, expand the Required permissions section:

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

The Managed Kafka ACL Editor (roles/managedkafka.aclEditor) role contains the necessary permission to add or remove individual ACL entries. For more details, see Google Cloud Managed Service for Apache Kafka predefined roles.

Add an ACL entry

1. Install the Google Cloud CLI.

2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Run the gcloud managed-kafka acls add-acl-entry command:

   gcloud managed-kafka acls add-acl-entry ACL_ID \
     --cluster=CLUSTER_ID \
     --location=LOCATION \
     --principal=PRINCIPAL \
     --operation=OPERATION \
     --permission-type=PERMISSION_TYPE \
     --host=HOST

   Replace the following:

   • ACL_ID (required): the unique ID of the Managed Kafka ACL resource where you want to add an ACL entry. This identifies the resource pattern to which the new entry applies. 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. See Supported locations.
   • PRINCIPAL (required): the principal (user or service account) to which the ACL entry applies. Use the format User:{google_service_account_email} or the wildcard User:*.
   • OPERATION (required): the operation type the ACL entry grants or denies. Allowed values include ALL, READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, CLUSTER_ACTION, DESCRIBE_CONFIGS, ALTER_CONFIGS, and IDEMPOTENT_WRITE.
   • PERMISSION_TYPE (optional, default value ALLOW): the type of access configured: ALLOW or DENY.
   • HOST (optional, default value *): the client host. For Google Cloud Managed Service for Apache Kafka, this must be set to the wildcard '*'.

Sample command

Run the following command to allow a specific service account to read from a topic named test-topic in the cluster test-cluster in the us-central1 region.

gcloud managed-kafka acls add-acl-entry topic/test-topic \
  --cluster=test-cluster \
  --location=us-central1 \
  --host='*' \
  --operation=READ \
  --permission-type=ALLOW \
  --principal='User:service-account@test-project.iam.gserviceaccount.com' \

Here is a sample output:

acl:
  aclEntries:
  - host: '*'
    operation: READ
    permissionType: ALLOW
    principal: 'User:service-account@test-project.iam.gserviceaccount.com'
  etag: W/another-new-etag
  name: projects/test-project/locations/us-central1/clusters/test-cluster/acls/topic/test-topic
  patternType: LITERAL
  resourceName: test-topic
  resourceType: TOPIC
aclCreated: false

The output of the add-acl-entry command provides information about the resulting ACL state:

• acl: this section describes the updated ACL resource after the new entry has been added.
  • aclEntries: this is a list containing all the access control entries for this ACL. In this example, it would now include the entry just added. Each entry has the following fields:
    • host: the host for the ACL entry.
    • operation: the Kafka operation this entry applies to.
    • permissionType: whether the access is ALLOW or DENY.
    • principal: the user or service account this entry is for.
  • etag: this is the entity tag for the updated ACL. It's used for optimistic concurrency control during subsequent updates. The value changes after an entry is added.
  • name: the unique identifier for the ACL resource. It follows the format projects/{project}/locations/{location}/clusters/{cluster}/acls/{acl_id}.
  • patternType: the type of resource pattern for this ACL.
  • resourceName: the name of the Kafka resource to which this ACL applies.
  • resourceType: the type of Kafka resource.
• aclCreated: a boolean value indicating whether the ACL resource was created as a result of adding this entry.

What's next

• Create an ACL

• View an ACL

• Update an ACL

• Delete an ACL