From fd84f0604ba0eac5bc420cf4da2bed00be2dfe4f Mon Sep 17 00:00:00 2001 From: Stacey Salamon Date: Fri, 6 Dec 2024 13:12:42 +0100 Subject: [PATCH] docs: update Kafka ACL docs Updates descriptions for Aiven ACLs and Kafka-native ACLs to provide clarification on when to use each. Adds example usage for Kafka-native ACLs. Updates field descriptions for native ACLs. --- docs/resources/kafka_acl.md | 10 +++-- docs/resources/kafka_native_acl.md | 43 +++++++++++++++---- .../aiven_kafka_native_acl/import.sh | 1 + .../aiven_kafka_native_acl/resource.tf | 11 +++++ .../sdkprovider/service/kafka/kafka_acl.go | 5 ++- .../service/kafka/kafka_native_acl.go | 17 +++++--- 6 files changed, 66 insertions(+), 21 deletions(-) create mode 100644 examples/resources/aiven_kafka_native_acl/import.sh create mode 100644 examples/resources/aiven_kafka_native_acl/resource.tf diff --git a/docs/resources/kafka_acl.md b/docs/resources/kafka_acl.md index 0cfb47ce8..29db625bb 100644 --- a/docs/resources/kafka_acl.md +++ b/docs/resources/kafka_acl.md @@ -3,15 +3,17 @@ page_title: "aiven_kafka_acl Resource - terraform-provider-aiven" subcategory: "" description: |- - Creates and manages an access control list https://aiven.io/docs/products/kafka/concepts/acl (ACL) entry for an Aiven for Apache Kafka® service. - ACL entries grant users rights to produce, consume, and manage Kafka topics. + Creates and manages Aiven access control lists https://aiven.io/docs/products/kafka/concepts/acl (ACLs) for an Aiven for Apache Kafka® service. ACLs control access to Kafka topics, consumer groups, + clusters, and Schema Registry. + Aiven ACLs provide simplified topic-level control with basic permissions and wildcard support. For more advanced access control, you can use Kafka-native ACLs https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/kafka_native_acl. --- # aiven_kafka_acl (Resource) -Creates and manages an [access control list](https://aiven.io/docs/products/kafka/concepts/acl) (ACL) entry for an Aiven for Apache Kafka® service. +Creates and manages Aiven [access control lists](https://aiven.io/docs/products/kafka/concepts/acl) (ACLs) for an Aiven for Apache Kafka® service. ACLs control access to Kafka topics, consumer groups, +clusters, and Schema Registry. -ACL entries grant users rights to produce, consume, and manage Kafka topics. +Aiven ACLs provide simplified topic-level control with basic permissions and wildcard support. For more advanced access control, you can use [Kafka-native ACLs](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/kafka_native_acl). ## Example Usage diff --git a/docs/resources/kafka_native_acl.md b/docs/resources/kafka_native_acl.md index 64de3e56e..9b5b05513 100644 --- a/docs/resources/kafka_native_acl.md +++ b/docs/resources/kafka_native_acl.md @@ -3,32 +3,51 @@ page_title: "aiven_kafka_native_acl Resource - terraform-provider-aiven" subcategory: "" description: |- - Manages native acls in kafka service https://aiven.io/docs/products/kafka/concepts/acl. + Creates and manages Kafka-native access control lists https://aiven.io/docs/products/kafka/concepts/acl (ACLs) for an Aiven for Apache Kafka® service. ACLs control access to Kafka topics, consumer groups, + clusters, and Schema Registry. + Kafka-native ACLs provide advanced resource-level access control with fine-grained permissions, including ALLOW and DENY rules. For simplified topic-level control you can use Aiven ACLs https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/kafka_acl. --- # aiven_kafka_native_acl (Resource) -Manages native acls in [kafka service](https://aiven.io/docs/products/kafka/concepts/acl). +Creates and manages Kafka-native [access control lists](https://aiven.io/docs/products/kafka/concepts/acl) (ACLs) for an Aiven for Apache Kafka® service. ACLs control access to Kafka topics, consumer groups, +clusters, and Schema Registry. +Kafka-native ACLs provide advanced resource-level access control with fine-grained permissions, including `ALLOW` and `DENY` rules. For simplified topic-level control you can use [Aiven ACLs](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/kafka_acl). +## Example Usage + +```terraform +resource "aiven_kafka_native_acl" "example_acl" { + project = data.aiven_project.example_project.project + service_name = aiven_kafka.example_kafka.service_name + resource_type = "Topic" + resource_name = "example-topic" + principal = "User:example-user" + operation = "Read" + pattern_type = "LITERAL" + permission_type = "ALLOW" + host = "198.51.100.0" +} +``` ## Schema ### Required -- `operation` (String) The operation. The possible values are `All`, `Alter`, `AlterConfigs`, `ClusterAction`, `Create`, `CreateTokens`, `Delete`, `Describe`, `DescribeConfigs`, `DescribeTokens`, `IdempotentWrite`, `Read` and `Write`. Changing this property forces recreation of the resource. +- `operation` (String) The action that a principal is allowed or denied on the Kafka resource. The possible values are `All`, `Alter`, `AlterConfigs`, `ClusterAction`, `Create`, `CreateTokens`, `Delete`, `Describe`, `DescribeConfigs`, `DescribeTokens`, `IdempotentWrite`, `Read` and `Write`. Changing this property forces recreation of the resource. - `pattern_type` (String) Resource pattern used to match specified resources. The possible values are `LITERAL` and `PREFIXED`. Changing this property forces recreation of the resource. -- `permission_type` (String) The permission type. The possible values are `ALLOW` and `DENY`. Changing this property forces recreation of the resource. -- `principal` (String) Principal is in type:name' format. Maximum length: `256`. Changing this property forces recreation of the resource. +- `permission_type` (String) Specifies whether the action is explicitly allowed or denied for the principal on the specified resource. The possible values are `ALLOW` and `DENY`. Changing this property forces recreation of the resource. +- `principal` (String) Identities in `type:name` format that the permissions apply to. Maximum length: `256`. Changing this property forces recreation of the resource. - `project` (String) The name of the project this resource belongs to. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource. -- `resource_name` (String) The kafka resource name. Maximum length: `256`. Changing this property forces recreation of the resource. -- `resource_type` (String) The kafka resource type. The possible values are `Topic`, `Group`, `Cluster`, `TransactionalId`, `DelegationToken` and `User`. Changing this property forces recreation of the resource. +- `resource_name` (String) The name of the Kafka resource the permission applies to, such as the topic name or group ID. Maximum length: `256`. Changing this property forces recreation of the resource. +- `resource_type` (String) The type of Kafka resource. The possible values are `Topic`, `Group`, `Cluster`, `TransactionalId`, `DelegationToken` and `User`. Changing this property forces recreation of the resource. - `service_name` (String) The name of the service that this resource belongs to. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource. ### Optional -- `host` (String) The host or `*` for all hosts. Maximum length: `256`. Changing this property forces recreation of the resource. +- `host` (String) The IP address from which a principal is allowed or denied access to the resource. Use `*` for all hosts. Maximum length: `256`. Changing this property forces recreation of the resource. - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts)) ### Read-Only @@ -45,3 +64,11 @@ Optional: - `delete` (String) - `read` (String) - `update` (String) + +## Import + +Import is supported using the following syntax: + +```shell +terraform import aiven_kafka_native_acl.example_acl PROJECT/SERVICE_NAME/ID +``` diff --git a/examples/resources/aiven_kafka_native_acl/import.sh b/examples/resources/aiven_kafka_native_acl/import.sh new file mode 100644 index 000000000..cbf110a1f --- /dev/null +++ b/examples/resources/aiven_kafka_native_acl/import.sh @@ -0,0 +1 @@ +terraform import aiven_kafka_native_acl.example_acl PROJECT/SERVICE_NAME/ID diff --git a/examples/resources/aiven_kafka_native_acl/resource.tf b/examples/resources/aiven_kafka_native_acl/resource.tf new file mode 100644 index 000000000..81a405f12 --- /dev/null +++ b/examples/resources/aiven_kafka_native_acl/resource.tf @@ -0,0 +1,11 @@ +resource "aiven_kafka_native_acl" "example_acl" { + project = data.aiven_project.example_project.project + service_name = aiven_kafka.example_kafka.service_name + resource_type = "Topic" + resource_name = "example-topic" + principal = "User:example-user" + operation = "Read" + pattern_type = "LITERAL" + permission_type = "ALLOW" + host = "198.51.100.0" +} diff --git a/internal/sdkprovider/service/kafka/kafka_acl.go b/internal/sdkprovider/service/kafka/kafka_acl.go index 7851678bd..e1bf71bf7 100644 --- a/internal/sdkprovider/service/kafka/kafka_acl.go +++ b/internal/sdkprovider/service/kafka/kafka_acl.go @@ -49,9 +49,10 @@ var aivenKafkaACLSchema = map[string]*schema.Schema{ func ResourceKafkaACL() *schema.Resource { return &schema.Resource{ Description: ` -Creates and manages an [access control list](https://aiven.io/docs/products/kafka/concepts/acl) (ACL) entry for an Aiven for Apache Kafka® service. +Creates and manages Aiven [access control lists](https://aiven.io/docs/products/kafka/concepts/acl) (ACLs) for an Aiven for Apache Kafka® service. ACLs control access to Kafka topics, consumer groups, +clusters, and Schema Registry. -ACL entries grant users rights to produce, consume, and manage Kafka topics. +Aiven ACLs provide simplified topic-level control with basic permissions and wildcard support. For more advanced access control, you can use [Kafka-native ACLs](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/kafka_native_acl). `, CreateContext: resourceKafkaACLCreate, ReadContext: resourceKafkaACLRead, diff --git a/internal/sdkprovider/service/kafka/kafka_native_acl.go b/internal/sdkprovider/service/kafka/kafka_native_acl.go index da8beab09..e827b327c 100644 --- a/internal/sdkprovider/service/kafka/kafka_native_acl.go +++ b/internal/sdkprovider/service/kafka/kafka_native_acl.go @@ -21,14 +21,14 @@ var aivenKafkaNativeACLSchema = map[string]*schema.Schema{ Required: true, ForceNew: true, ValidateFunc: validation.StringLenBetween(1, 256), - Description: userconfig.Desc("The kafka resource name").ForceNew().MaxLen(256).Build(), + Description: userconfig.Desc("The name of the Kafka resource the permission applies to, such as the topic name or group ID.").ForceNew().MaxLen(256).Build(), }, "resource_type": { Type: schema.TypeString, Required: true, ForceNew: true, ValidateFunc: validation.StringInSlice(kafka.ResourceTypeChoices(), false), - Description: userconfig.Desc("The kafka resource type").ForceNew().PossibleValuesString(kafka.ResourceTypeChoices()...).Build(), + Description: userconfig.Desc("The type of Kafka resource.").ForceNew().PossibleValuesString(kafka.ResourceTypeChoices()...).Build(), }, "pattern_type": { Type: schema.TypeString, @@ -42,34 +42,37 @@ var aivenKafkaNativeACLSchema = map[string]*schema.Schema{ Required: true, ForceNew: true, ValidateFunc: validation.StringLenBetween(1, 256), - Description: userconfig.Desc("Principal is in type:name' format").ForceNew().MaxLen(256).Build(), + Description: userconfig.Desc("Identities in `type:name` format that the permissions apply to.").ForceNew().MaxLen(256).Build(), }, "host": { Type: schema.TypeString, Optional: true, ForceNew: true, ValidateFunc: validation.StringLenBetween(1, 256), - Description: userconfig.Desc("The host or `*` for all hosts").ForceNew().MaxLen(256).Build(), + Description: userconfig.Desc("The IP address from which a principal is allowed or denied access to the resource. Use `*` for all hosts.").ForceNew().MaxLen(256).Build(), }, "operation": { Type: schema.TypeString, Required: true, ForceNew: true, ValidateFunc: validation.StringInSlice(kafka.OperationTypeChoices(), false), - Description: userconfig.Desc("The operation").ForceNew().PossibleValuesString(kafka.OperationTypeChoices()...).Build(), + Description: userconfig.Desc("The action that a principal is allowed or denied on the Kafka resource.").ForceNew().PossibleValuesString(kafka.OperationTypeChoices()...).Build(), }, "permission_type": { Type: schema.TypeString, Required: true, ForceNew: true, ValidateFunc: validation.StringInSlice(kafka.KafkaAclPermissionTypeChoices(), false), - Description: userconfig.Desc("The permission type").ForceNew().PossibleValuesString(kafka.KafkaAclPermissionTypeChoices()...).Build(), + Description: userconfig.Desc("Specifies whether the action is explicitly allowed or denied for the principal on the specified resource.").ForceNew().PossibleValuesString(kafka.KafkaAclPermissionTypeChoices()...).Build(), }, } func ResourceKafkaNativeACL() *schema.Resource { return &schema.Resource{ - Description: userconfig.Desc(`Manages native acls in [kafka service](https://aiven.io/docs/products/kafka/concepts/acl)`).Build(), + Description: userconfig.Desc(`Creates and manages Kafka-native [access control lists](https://aiven.io/docs/products/kafka/concepts/acl) (ACLs) for an Aiven for Apache Kafka® service. ACLs control access to Kafka topics, consumer groups, +clusters, and Schema Registry. + +Kafka-native ACLs provide advanced resource-level access control with fine-grained permissions, including ` + "`ALLOW`" + ` and ` + "`DENY`" + ` rules. For simplified topic-level control you can use [Aiven ACLs](https://registry.terraform.io/providers/aiven/aiven/latest/docs/resources/kafka_acl).`).Build(), CreateContext: common.WithGenClient(resourceKafkaNativeACLCreate), ReadContext: common.WithGenClient(resourceKafkaNativeACLRead), DeleteContext: common.WithGenClient(resourceKafkaNativeACLDelete),