Skip to content

Commit

Permalink
update: clarify content and cross link
Browse files Browse the repository at this point in the history
  • Loading branch information
@harshini-rangaswamy
harshini-rangaswamy committed Dec 6, 2024
1 parent 9291a33 commit 7850bca
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 52 deletions.
51 changes: 28 additions & 23 deletions docs/tools/cli/service/acl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,61 +4,62 @@ title: avn service acl

Full list of commands for `avn service acl`.

## Manage Apache Kafka® access control lists
## Manage Aiven ACL

Commands for managing Aiven for Apache Kafka® access control lists via
`avn` commands.
The `avn service acl` command manages access control lists (ACLs) in Aiven for Apache
Kafka®. ACLs define permissions for accessing topics and controlling user access. They
support wildcard patterns (`*` and `?`) for both topics and usernames. Supported
permissions are `read`, `write`, and `readwrite`.

### `avn service acl-add`

Adds an Aiven for Apache Kafka® ACL entry.
Add an Aiven for Apache Kafka® ACL entry.

| Parameter | Information |
| -------------- | ----------------------------------------------------------------------- |
| `service_name` | The name of the service |
| `--permission` | The permission type: possible values are `read`, `write` or `readwrite` |
| `--topic` | The topic name pattern: accepts `*` and `?` as wildcard characters |
| `--username` | The username pattern: accepts `*` and `?` as wildcard characters |
| `service_name` | Name of the service |
| `--permission` | Permission type: possible values are `read`, `write` or `readwrite` |
| `--topic` | Topic name pattern: accepts `*` and `?` as wildcard characters |
| `--username` | Username pattern: accepts `*` and `?` as wildcard characters |

**Example:** Add an ACLs for users with username ending with `userA` to
`readwrite` on topics having name starting with `topic2020` in the
service `kafka-doc`.
**Example:** Add an ACL for usernames ending with `userA` to have `readwrite` access to
topics starting with `topic2020` in service `kafka-doc`.

```
```bash
avn service acl-add kafka-doc --username *userA --permission readwrite --topic topic2020*
```

### `avn service acl-delete`

Deletes an Aiven for Apache Kafka® ACL entry.
Delete an Aiven for Apache Kafka® ACL entry.

| Parameter | Information |
| -------------- | --------------------------- |
| `service_name` | The name of the service |
| `acl_id` | The id of the ACL to delete |
| `service_name` | Name of the service |
| `acl_id` | ID of the ACL to delete |

**Example:** Delete the ACLs with id `acl3604f96c74a` on the Aiven for
Apache Kafka instance named `kafka-doc`.
**Example:** Delete the ACL with ID `acl3604f96c74a` from the Aiven for
Apache Kafka service `kafka-doc`.

```
```bash
avn service acl-delete kafka-doc acl3604f96c74a
```

### `avn service acl-list`

Lists Aiven for Apache Kafka® ACL entries.
List Aiven for Apache Kafka® ACL entries.

| Parameter | Information |
| -------------- | ----------------------- |
| `service_name` | The name of the service |
| `service_name` | Name of the service |

**Example:** List the ACLs defined for a service named `kafka-doc`.
**Example:** List ACLs defined for service `kafka-doc`.

```
```bash
avn service acl-list kafka-doc
```

An example of `avn service acl-list` output:
Example output of `avn service acl-list`:

```text
ID USERNAME TOPIC PERMISSION
Expand All @@ -67,3 +68,7 @@ default * * admin
acl3604f96c74a Jon orders readwrite
acl3604fa706cb Frida invoices* write
```

## Related page

For managing Kafka-native ACLs, see [`avn service kafka-acl`](/docs/tools/cli/service/kafka-acl).
71 changes: 42 additions & 29 deletions docs/tools/cli/service/kafka-acl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,68 +4,81 @@ title: avn service kafka-acl

Full list of commands for `avn service kafka-acl`.

## Manage Kafka-native access control lists (ACLs)
## Manage Kafka-native ACLs

Commands for managing Kafka-native ACLs using `avn` commands.
The `avn service kafka-acl` command manages **Kafka-native access control lists (ACLs)**
in Aiven for Apache Kafka®. Kafka-native ACLs define advanced, resource-level
permissions for accessing resources such as topics, consumer groups, clusters, and
transactional IDs. They support fine-grained access control with
both `ALLOW` and `DENY` rules, and wildcard patterns (`*` and `?`) for
resources and usernames.

### `avn service kafka-acl-add`

Adds a Kafka-native ACL entry.
Add a Kafka-native ACL entry.

| Parameter | Information |
| ------------------------- | ------------------------------------------------------------------------------- |
| `service_name` | The name of the service |
| `--principal` | The principal for the ACLs, must be in the form User:name |
| `--topic` | Topic resource type to which ACL should be added |
| `--group` | Group resource type to which ACL should be added |
| `--cluster` | The ACL is applied to the clusger resource |
| `--transactional-id` | TransactionalId resource type to which ACL should be added |
| `--operation` | The operation type: possible values are `Describe`,`DescribeConfigs`,<br/>`Alter`,`IdempotentWrite`,`Read`,`Delete`,`Create`,`ClusterAction`,<br/>`All`,`Write`,`AlterConfigs`,`CreateTokens`,`DescribeTokens` |
| `--host` | The host for the ACLs, a value of '*' matches all hosts (default: *) |
| `--resource-pattern-type` | The type of the resource pattern, can be LITERAL or PREFIXED (default: LITERAL) |
! `--deny` | Create a DENY rule (default is ALLOW) |

**Example:** Add an ACLs for user `userA` to `Read` on topics having name starting
with `topic2020` in the service `kafka-doc`.

```
avn service kafka-acl-add kafka-doc --principal User:userA --operation Read --topic topic2020 --resource-pattern-type PREFIXED
| `service_name` | Name of the service |
| `--principal` | Principal for the ACL, in the form `User:<name>` |
| `--topic` | Topic resource for the ACL |
| `--group` | Consumer group resource for the ACL |
| `--cluster` | Cluster resource for the ACL |
| `--transactional-id` | `TransactionalId` resource for the ACL |
| `--operation` | Operation type: possible values are `Describe`, `DescribeConfigs`,<br/>`Alter`, `IdempotentWrite`, `Read`, `Delete`, `Create`, `ClusterAction`,<br/>`All`, `Write`, `AlterConfigs`, `CreateTokens`, `DescribeTokens` |
| `--host` | Host for the ACL, where `*` matches all hosts (default: `*`) |
| `--resource-pattern-type` | Resource pattern type, either `LITERAL` or `PREFIXED` (default: `LITERAL`) |
! `--deny` | Create a `DENY` rule (default: `ALLOW`) |

**Example:** Add a Kafka-native ACL for user `userA` to `Read` on topics with names
starting with `topic2020` in service `kafka-doc`.

```bash
avn service kafka-acl-add kafka-doc \
--principal User:userA \
--operation Read \
--topic topic2020 \
--resource-pattern-type PREFIXED
```

### `avn service kafka-acl-delete`

Deletes a Kafka-native ACL entry.
Delete a Kafka-native ACL entry.

| Parameter | Information |
| -------------- | --------------------------- |
| `service_name` | The name of the service |
| `acl_id` | The id of the ACL to delete |
| `service_name` | Name of the service |
| `acl_id` | ID of the ACL to delete |

**Example:** Delete the native ACL with id `acl3604f96c74a` on service named `kafka-doc`.
**Example:** Delete a Kafka-native ACL with ID `acl3604f96c74a` on service `kafka-doc`.

```
```bash
avn service kafka-acl-delete kafka-doc acl3604f96c74a
```

### `avn service kafka-acl-list`

Lists Kafka-native ACL entries.
List Kafka-native ACL entries.

| Parameter | Information |
| -------------- | ----------------------- |
| `service_name` | The name of the service |
| `service_name` | Name of the service |

**Example:** List the ACLs defined for a service named `kafka-doc`.
**Example:** List Kafka-native ACLs defined for service `kafka-doc`.

```
```bash
avn service kafka-acl-list kafka-doc
```

An example of `avn service kafka-acl-list` output:
Example output of `avn service kafka-acl-list`:

```text
ID PERMISSION_TYPE PRINCIPAL OPERATION RESOURCE_TYPE PATTERN_TYPE RESOURCE_NAME HOST
============== =============== ========== ========= ============= ============ ============= ====
acl4f9ed69c8aa ALLOW User:John Write Topic LITERAL orders *
acl4f9ed6e6371 ALLOW User:Frida Write Topic PREFIXED invoices *
```

## Related page

For managing Aiven ACLs, see [`avn service acl`](/docs/tools/cli/service/acl).

0 comments on commit 7850bca

Please sign in to comment.