The document describes how to create an
[ACL entry](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#acl-entries)
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](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/update-kafka-acls.md.txt),
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](https://docs.cloud.google.com/iam/docs/roles-permissions/managedkafka.md.txt#managedkafka.aclEditor) (`roles/managedkafka.aclEditor`) IAM role on your project.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


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](https://docs.cloud.google.com/iam/docs/creating-custom-roles.md.txt) or
other [predefined roles](https://docs.cloud.google.com/iam/docs/roles-overview.md.txt#predefined).

## Add an ACL entry

### Console

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


   [Go to Clusters](https://console.cloud.google.com/managedkafka/clusters)

   <br />

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](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#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](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#acl-principal)
      for the ACL entry.

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

   6. In the **Operation** list, select the
      [operation type](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#acl-operation)
      for the ACL entry.

6. Click **Create**.

### gcloud

Run the
[`gcloud managed-kafka acls add-acl-entry`](https://docs.cloud.google.com/sdk/gcloud/reference/managed-kafka/acls/add-acl-entry)
command:

```bash
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](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#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](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#acl-principal)
  for the new ACL entry.

- `OPERATION`: The
  [operation type](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt#acl-operation),
  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.

```bash
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:

```bash
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](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/create-kafka-acls.md.txt)

- [View an ACL](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/view-kafka-acl.md.txt)

- [Update an ACL](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/update-kafka-acls.md.txt)

- [Delete an ACL](https://docs.cloud.google.com/managed-service-for-apache-kafka/docs/kafka-acls/delete-kafka-acl.md.txt)

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