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

@@ -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
 

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 generated by tfplugindocs -->
 ## 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
+```

examples/resources/aiven_kafka_native_acl/import.sh

@@ -0,0 +1 @@
+terraform import aiven_kafka_native_acl.example_acl PROJECT/SERVICE_NAME/ID

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"
+}

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,

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),