Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: update Kafka ACL docs
Browse files Browse the repository at this point in the history
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.
staceysalamon-aiven committed Dec 10, 2024

Verified

This commit was signed with the committer’s verified signature.
staceysalamon-aiven Stacey Salamon
1 parent 6086287 commit 647ce11
Showing 6 changed files with 66 additions and 21 deletions.
10 changes: 6 additions & 4 deletions docs/resources/kafka_acl.md
Original file line number Diff line number Diff line change
@@ -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

43 changes: 35 additions & 8 deletions docs/resources/kafka_native_acl.md
Original file line number Diff line number Diff line change
@@ -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 `user:name` format that the permissions apply to. The `name` supports wildcards. 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
```
1 change: 1 addition & 0 deletions examples/resources/aiven_kafka_native_acl/import.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
terraform import aiven_kafka_native_acl.example_acl PROJECT/SERVICE_NAME/ID
11 changes: 11 additions & 0 deletions examples/resources/aiven_kafka_native_acl/resource.tf
Original file line number Diff line number Diff line change
@@ -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"
}
5 changes: 3 additions & 2 deletions internal/sdkprovider/service/kafka/kafka_acl.go
Original file line number Diff line number Diff line change
@@ -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,
17 changes: 10 additions & 7 deletions internal/sdkprovider/service/kafka/kafka_native_acl.go
Original file line number Diff line number Diff line change
@@ -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 `user:name` format that the permissions apply to. The `name` supports wildcards.").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),

0 comments on commit 647ce11

Please sign in to comment.