From 1d03a6ca934e1a643b35d13ecc233ce499baafbc Mon Sep 17 00:00:00 2001 From: Harshini Rangaswamy Date: Wed, 4 Dec 2024 12:33:12 +0100 Subject: [PATCH] fix: address feedback --- docs/products/kafka/concepts/acl.md | 23 ++-- docs/products/kafka/howto/manage-acls.md | 133 +++++++++++++---------- 2 files changed, 87 insertions(+), 69 deletions(-) diff --git a/docs/products/kafka/concepts/acl.md b/docs/products/kafka/concepts/acl.md index dd82bbee..73fdf986 100644 --- a/docs/products/kafka/concepts/acl.md +++ b/docs/products/kafka/concepts/acl.md @@ -86,12 +86,12 @@ configure separate ACL entries for consumer group access. Kafka-native ACLs offer precise control with fine-grained permissions and resource-level management. Use them for complex scenarios requiring rules like `ALLOW` and `DENY`. -- **Fine-grained permissions**: Allow both `ALLOW` and `DENY` rules to provide +- **Fine-grained permissions**: Support both `ALLOW` and `DENY` rules to provide precise control over access. - **Expanded resource-level control**: Manage access to non-topic resources, such as consumer groups, clusters, and transactional IDs. -- **Pattern-based matching**: Specify how resource names are matched using `LITERAL` - for exact matches or `PREFIXED` for prefixes. +- **Pattern-based matching**: Use `LITERAL` for exact matches or `PREFIXED` for prefixes + to specify how resource names are matched. ### ACL structure @@ -107,8 +107,11 @@ A Kafka-native ACL entry consists of the following elements: - **LITERAL**: Matches an exact resource name, such as `my-topic`. - **PREFIXED**: Matches all resources sharing a specified prefix, such as `logs-*`. - **Resource**: The specific Apache Kafka resource, based on the selected pattern type. - For example, when the pattern type is `LITERAL`, a resource value of `*` is a special - case that matches all resources. This behavior follows standard Kafka conventions. + :::note + When the `pattern_type` is `LITERAL`, setting the `resource` to `*` is a special + case that matches all resources. This behavior follows standard Apache Kafka conventions. + ::: + - **Operation**: The Apache Kafka operation to allow or deny, such as `Read`, `Write`, or `Describe`. - **Permission type**: Specifies whether the action is `ALLOW` or `DENY`. @@ -175,18 +178,18 @@ consumer group, `DENY` rules take precedence over `ALLOW` rules. **Examples**: - An `ALLOW` rule grants access to resources matching a general pattern, such as: - - Topics starting with `test-*` - - All consumer groups + - Topics starting with `test-*`. + - All consumer groups. - A `DENY` rule restricts access to resources matching a specific pattern, such as: - - Topics starting with `test-sensitive-*` - - Consumer groups with `sensitive` in their names + - Topics starting with `test-sensitive-*`. + - Consumer groups with `sensitive` in their names. ## ACL permission mapping The following table summarizes the permissions supported by Aiven ACLs, along with corresponding Apache Kafka actions and Java APIs. -| **Action** | **Java API Link** | **Admin** | **Consume and Produce** | **Produce** | **Consume** | +| Action | Java API Link | Admin | Consume and Produce | Produce | Consume | |----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|--------------------------|-------------|-------------| | **Cluster** | | | | | | | → `CreateTopics` | [docs](https://kafka.apache.org/30/javadoc/org/apache/kafka/clients/admin/Admin.html#createTopics(java.util.Collection)) | ✓ | | | | diff --git a/docs/products/kafka/howto/manage-acls.md b/docs/products/kafka/howto/manage-acls.md index ade1d733..d2ade873 100644 --- a/docs/products/kafka/howto/manage-acls.md +++ b/docs/products/kafka/howto/manage-acls.md @@ -12,7 +12,7 @@ operations on these resources. ## Types of ACLs -Aiven for Apache Kafka® supports two types of ACLs: +Aiven for Apache Kafka supports two types of ACLs: - **Aiven ACLs**: These provide topic-level permissions and support wildcard patterns. - **Kafka-native ACLs**: These offer advanced, resource-level permissions with `ALLOW` @@ -20,11 +20,21 @@ Aiven for Apache Kafka® supports two types of ACLs: and clusters. :::note -ACL restrictions are controlled by a flag in the service's user configuration. By -default, ACLs do not apply to Kafka REST. If the flag is enabled, all ACLs are applied -to Kafka REST in the same way as they are for other interfaces. +ACL restrictions for Kafka REST are controlled by a user configuration parameter +in the service's advanced configuration settings. By default, ACLs do not apply to +Kafka REST. To enable ACLs for Kafka REST, set the `kafka_rest_authorization` parameter. +For more information, see +[Enable Kafka REST Proxy Authorization](https://aiven.io/docs/products/kafka/karapace/howto/enable-kafka-rest-proxy-authorization). ::: +## Prerequisites + +- [Aiven for Apache Kafka service](/docs/products/kafka/get-started) running. +- Access to the [Aiven Console](https://console.aiven.io/). +- Installed and authenticated [Aiven CLI](/docs/tools/cli). +- An [API token](https://aiven.io/docs/platform/howto/create_authentication_token) for + authenticating API requests. + ## Add a Kafka-native ACL entry @@ -32,13 +42,13 @@ to Kafka REST in the same way as they are for other interfaces. 1. Log in to [Aiven Console](https://console.aiven.io/) and select your service. -1. Click +1. Click . 1. Click **Add entry**. 1. On the **Add access control entry** screen: 1. Select **Kafka-native ACLs** as the ACL type. 1. Fill in the following fields: 1. **Permission type**: Select `ALLOW` or `DENY`. - 1. **Principal**:Enter the principal in the format `User:`. + 1. **Principal**: Enter the principal in the format `User:`. 1. **Operation**: Select the operation, such as `Read` or `Write`. 1. **Resource type**: Select the Apache Kafka resource to manage. 1. **Pattern type**: Select `LITERAL` for exact matches or `PREFIXED` for @@ -50,7 +60,7 @@ to Kafka REST in the same way as they are for other interfaces. -To add an Kafka-native ACL entry with the Aiven CLI, run: +To add an Kafka-native ACL entry using the Aiven CLI, run: ```bash avn service kafka-acl-add \ @@ -65,14 +75,15 @@ avn service kafka-acl-add \ Parameters: - `service_name`: Enter the name of your Aiven for Apache Kafka service. -- `--principal`: Provide the principal in the format `User:`. -- `--operation`: Specify the Apache Kafka operation, such as +- `--principal`: Enter the principal in the format `User:`. +- `--operation`: Enter the Apache Kafka operation, such as `Read`, `Write`, `Describe`, `Delete`, or any supported operation. -- `--topic`: Specify the topic resource for the ACL entry. Use this when working with - topic-based ACLs. -- `--group`: Specify the consumer group resource for the ACL entry. -- `--cluster`: Specify that the ACL applies to the cluster resource. -- `--transactional-id`: Specify the transactional ID resource for the ACL entry. +- Resource-specific parameters, specify at least one of the following based on your + requirements: + - `--topic`: Enter the topic resource. + - `--group`: Enter the consumer group resource. + - `--cluster`: Specify that the ACL applies to the Kafka cluster. + - `--transactional-id`: Enter the transactional ID resource. - `--resource-pattern-type`: Specify the resource pattern type. Use `LITERAL` for exact matches or `PREFIXED` for pattern-based matches (default: `LITERAL`). - `--host` Optional: Specify the allowed host. Use `*` to allow all hosts. @@ -105,7 +116,7 @@ curl --request POST \ "host": "", "resource_type": "", "resource_name": "", - "pattern_type": "", + "pattern_type": "", "operation": "", "permission_type": "" }' @@ -121,13 +132,15 @@ Parameter: - `resource_type`: Specify the resource type, such as `Cluster`, `Topic`, `Group`, or `TransactionalId`. - `resource_name`: Provide the resource name or prefix for pattern-based matching. -- `pattern_type`: Specify `LITERAL`. +- `pattern_type`: Specify `LITERAL` for an exact match or `PREFIXED` for + pattern-based matching. - `host`: Specify the allowed host or use `*` to match all hosts. -To add a Kafka-native ACL entry using Terraform, define the following resource in your Terraform configuration: +To add a Kafka-native ACL entry using Terraform, define the following resource in your +Terraform configuration: ```terraform resource "aiven_kafka_native_acl" "example" { @@ -143,19 +156,19 @@ resource "aiven_kafka_native_acl" "example" { } ``` -Required attributes: + Parameters: - `project`: Enter the name of your Aiven project. - `service_name`: Enter the name of your Aiven for Apache Kafka service. -- `resource_name`: Specify the resource name or prefix for pattern-based matching. -- `resource_type`: Specify the type of resource to manage, such as +- `resource_name`: Enter the resource name or prefix for pattern-based matching. +- `resource_type`: Enter the type of resource to manage, such as `Topic`, `Group`, `Cluster`, or `TransactionalId`. -- `pattern_type`: Specify the pattern type for resource matching. Use `LITERAL` for +- `pattern_type`: Enter the pattern type for resource matching. Use `LITERAL` for exact matches or `PREFIXED` for pattern-based matching. - `principal`: Enter the principal in the format `User:`. -- `operation`: Specify the Kafka operation, such as `Read`, `Write`, or `Create`. -- `permission_type`: Specify the type of permission. Use `ALLOW` or `DENY`. -- `host`: Specify the allowed host, or use `*` to apply to all hosts. +- `operation`: Enter the Apache Kafka operation, such as `Read`, `Write`, or `Create`. +- `permission_type`: Enter the type of permission. Use `ALLOW` or `DENY`. +- `host`: Enter the allowed host, or use `*` to apply to all hosts. @@ -180,14 +193,15 @@ Required attributes: 1. Click **Submit**. :::tip -After defining custom ACLs, delete the default `avnadmin` ACL entry by clicking - under **Actions**. +After defining custom ACLs, delete the default `avnadmin` ACL entry by +clicking under **Actions** to prevent unintended +access via wildcard permissions. ::: -To add an Aiven ACL entry with the Aiven CLI, run: +To add an Aiven ACL entry using the Aiven CLI, run: ```bash avn service acl-add \ @@ -198,11 +212,11 @@ avn service acl-add \ Parameters: -- ``: Specify the name of your Aiven for Apache Kafka service. -- `--username`: Specify the username or pattern to apply. Supports wildcards `*` and `?`. -- `--permission`: Specify the permission type. Valid values are `read`, `write`, or +- ``: Enter the name of your Aiven for Apache Kafka service. +- `--username`: Enter the username or pattern to apply. Supports wildcards `*` and `?`. +- `--permission`: Enter the permission type. Valid values are `read`, `write`, or `readwrite`. -- `--topic`: Specify the topic name or pattern to apply. Supports wildcards `*` and `?`. . +- `--topic`: Enter the topic name or pattern to apply. Supports wildcards `*` and `?`. **Example:** @@ -219,7 +233,7 @@ avn service acl-add kafka-service \ -To add an Aiven ACL entry, use the following API request: +To add an Aiven ACL entry for Apache Kafka topics, use the following API request: ```bash curl --request POST \ @@ -228,7 +242,6 @@ curl --request POST \ --header 'Content-Type: application/json' \ --data '{ "username": "", - "resource_type": "", "resource": "", "permission": "" }' @@ -241,16 +254,29 @@ Parameters: - `service_name`: Enter the name of your Aiven for Apache Kafka service. - `username`: Enter the username or pattern to apply the ACL to. Use `*` and `?` as wildcards. -- `resource_type`: Specify `topic` for Kafka topics or `schema` for schemas in the - schema registry. - `resource`: Enter the name of the topic or schema. Use `*` to apply to all, or include patterns with wildcards. -- `permission`: Specify `read`, `write`, `readwrite`, or `admin`. +- `permission`: Enter the permission type, such as `read`, `write`, `readwrite`, or + `admin`. + +:::note +Schema-related ACLs control access to schemas in the schema registry. These are +configured separately from topic-based ACLs. + +To configure schema-related ACLs, use the schema registry-specific configuration endpoint: +`/service//schema-registry/acl`. + +For more information, see the +[Schema ACL definition](https://aiven.io/docs/products/kafka/karapace/concepts/acl-definition) +or the [Schema Registry ACL API documentation](https://api.aiven.io/doc/#tag/Service:_Kafka/operation/ServiceSchemaRegistryAclAdd). +::: + -To add an Aiven ACL entry using Terraform, define the following resource in your Terraform configuration: +To add an Aiven ACL entry using Terraform, define the following resource in your +Terraform configuration: ```terraform resource "aiven_kafka_acl" "example_acl" { @@ -262,15 +288,15 @@ resource "aiven_kafka_acl" "example_acl" { } ``` -Required attributes: + Parameters: - `project`: Enter the name of your Aiven project. - `service_name`: Enter the name of your Aiven for Apache Kafka service. -- `topic`: Specify the name of the topic or pattern to apply the ACL to. Supports +- `topic`: Enter the name of the topic or pattern to apply the ACL to. Supports wildcards `*` and `?`. -- `permission`: Specify the permission type. Valid values are `read`, `write`, or +- `permission`: Enter the permission type. Valid values are `read`, `write`, or `readwrite`. -- `username`: Specify the username or pattern to apply the ACL to. Supports wildcards `*` +- `username`: Enter the username or pattern to apply the ACL to. Supports wildcards `*` and `?`. :::tip @@ -290,7 +316,7 @@ an admin user with wildcard permissions. 1. Log in to the [Aiven Console](https://console.aiven.io/) and select your Aiven for Apache Kafka service. -1. Click +1. Click . 1. Click the **Kafka-native ACLs** tab to view Kafka-native ACL entries or the **Aiven ACLs** tab to view Aiven ACL entries. 1. Use filters to narrow the list by resource type, operation, or permission type. @@ -312,9 +338,7 @@ To view ACL entries using the Aiven CLI: avn service acl-list ``` -Parameters: - -- `service_name`: Enter the name of your Aiven for Apache Kafka service. +Replace `service_name` with the name of your Aiven for Apache Kafka service. @@ -365,6 +389,8 @@ To view ACL entries with Terraform: } ``` +- Run `terraform apply`, and use `terraform console` to view the ACL entries. + Parameters - `project`: Enter the name of your Aiven project. @@ -403,25 +429,14 @@ To delete an ACL entry, use one of the following commands based on the ACL type: - **Aiven ACLs**: ```bash - avn service acl-delete --service --id + avn service acl-delete ``` Parameters - ``: Enter the name of the Aiven for Apache Kafka service. -- ``: Enter the ID of the ACL entry to delete. To retrieve ACL ID: - - - For Kafka-native ACLs: - - ```bash - avn kafka acl list --service - ``` - - - For Aiven ACLs: - - ```bash - avn service acl-list --service - ``` +- ``: Enter the ID of the ACL entry to delete. You can get + the `acl_id` from the output when [viewing ACL entries](#view-acl-entries).