Add an ACL entry to a Managed Kafka ACL

The document describes how to create an ACL entry and add it to a Managed Kafka ACL resource. If the Managed Kafka ACL resource doesn't exist, this operation also creates the ACL resource.

This operation is analogous to creating a single Apache Kafka ACL binding. Unlike the update operation, it doesn't require an ETag for concurrency control.

Required roles and permissions

To get the permission 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 managedkafka.acls.updateEntries permission, which is required to add an ACL entry.

You might also be able to get this permission with custom roles or other predefined roles.

Add an ACL entry

Console

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. Click the name of the cluster where you want to add an ACL entry.

  3. Click the Access control tab.

  4. Click Create ACL entry.

  5. In the Create ACL entry panel, enter the details of the ACL entry:

    1. In the Resource type list, select the type of cluster resource that this ACL applies to. For more information, see ACL ID.

    2. If the resource type is Topic, Consumer group, or Transactional ID, select or enter the ID of the resource.

    3. If the resource type is Topic prefix, Consumer group prefix, or Transactional ID prefix, enter the prefix for the ACL to match against.

    4. In the Principal field, enter the principal for the ACL entry.

    5. In the Permission type list, select ALLOW or DENY.

    6. In the Operation list, select the operation type for the ACL entry.

  6. Click Create.

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.