Add an ACL entry to a Managed Kafka ACL

The document describes how to add an ACL entry to a Managed Kafka ACL resource.

This operation is analogous to creating a single Apache Kafka ACL binding. Unlike the update operation, this operation doesn't 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:

Required permissions

The following permissions are required to add an ACL entry:

  • Grant this permission on the parent cluster: managedkafka.acls.updateEntries

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

Add an ACL entry

gcloud

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

Replace the following:

  • ACL_ID. The ID of the Managed Kafka ACL resource to update. For more information, see ACL ID. If a Managed Kafka ACL with this ID doesn't exist, one is automatically created.

  • CLUSTER_ID: The ID of your Kafka cluster.

  • LOCATION: The region of your Kafka cluster.

  • PRINCIPAL: The principal for the new 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.

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 \
  --principal='User:service-account@test-project.iam.gserviceaccount.com' \
  --operation=READ \
  --permission-type=ALLOW \
  --host='*'

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

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