From 7850bcaa101518ed603cc419318b04d8791f09c8 Mon Sep 17 00:00:00 2001 From: Harshini Rangaswamy Date: Fri, 6 Dec 2024 16:19:42 +0100 Subject: [PATCH] update: clarify content and cross link --- docs/tools/cli/service/acl.md | 51 +++++++++++---------- docs/tools/cli/service/kafka-acl.md | 71 +++++++++++++++++------------ 2 files changed, 70 insertions(+), 52 deletions(-) diff --git a/docs/tools/cli/service/acl.md b/docs/tools/cli/service/acl.md index 4701d119..a10310b8 100644 --- a/docs/tools/cli/service/acl.md +++ b/docs/tools/cli/service/acl.md @@ -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 @@ -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). diff --git a/docs/tools/cli/service/kafka-acl.md b/docs/tools/cli/service/kafka-acl.md index a453ff29..70da311a 100644 --- a/docs/tools/cli/service/kafka-acl.md +++ b/docs/tools/cli/service/kafka-acl.md @@ -4,64 +4,73 @@ 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`,
`Alter`,`IdempotentWrite`,`Read`,`Delete`,`Create`,`ClusterAction`,
`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:` | +| `--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`,
`Alter`, `IdempotentWrite`, `Read`, `Delete`, `Create`, `ClusterAction`,
`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 @@ -69,3 +78,7 @@ ID PERMISSION_TYPE PRINCIPAL OPERATION RESOURCE_TYPE PATTERN_T 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).