From dee70ecf9db3cd17310cc8e070b310c73c32ee6a Mon Sep 17 00:00:00 2001 From: Stacey Salamon <111294980+staceysalamon-aiven@users.noreply.github.com> Date: Thu, 21 Nov 2024 14:44:35 +0100 Subject: [PATCH] docs: improve valkey docs (#1914) --- docs/data-sources/valkey_user.md | 14 ++-- docs/resources/valkey.md | 4 +- docs/resources/valkey_user.md | 71 ++++++++++++++++--- .../resources/aiven_valkey_user/import.sh | 1 + .../resources/aiven_valkey_user/resource.tf | 42 +++++++++++ internal/sdkprovider/service/valkey/valkey.go | 2 +- .../sdkprovider/service/valkey/valkey_user.go | 16 ++--- 7 files changed, 123 insertions(+), 27 deletions(-) create mode 100644 examples/resources/aiven_valkey_user/import.sh create mode 100644 examples/resources/aiven_valkey_user/resource.tf diff --git a/docs/data-sources/valkey_user.md b/docs/data-sources/valkey_user.md index 85facc00f..e6a7f6e01 100644 --- a/docs/data-sources/valkey_user.md +++ b/docs/data-sources/valkey_user.md @@ -19,14 +19,14 @@ The Valkey User data source provides information about the existing Aiven for Va - `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. - `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. -- `username` (String) The actual name of the Valkey User. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource. +- `username` (String) Name of the Valkey service user. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource. ### Read-Only - `id` (String) The ID of this resource. -- `password` (String, Sensitive) The password of the Valkey User. -- `type` (String) Type of the user account. Tells whether the user is the primary account or a regular account. -- `valkey_acl_categories` (List of String) Defines command category rules. The field is required with`valkey_acl_commands` and `valkey_acl_keys`. Changing this property forces recreation of the resource. -- `valkey_acl_channels` (List of String) Defines the permitted pub/sub channel patterns. Changing this property forces recreation of the resource. -- `valkey_acl_commands` (List of String) Defines rules for individual commands. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. -- `valkey_acl_keys` (List of String) Defines key access rules. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. +- `password` (String, Sensitive) The Valkey service user's password. +- `type` (String) User account type, such as primary or regular account. +- `valkey_acl_categories` (List of String) Allow or disallow command categories. To allow a category use the prefix `+@` and to disallow use `-@`. See the [Valkey documentation](https://valkey.io/topics/acl/) for details on the ACL feature. The field is required with`valkey_acl_commands` and `valkey_acl_keys`. Changing this property forces recreation of the resource. +- `valkey_acl_channels` (List of String) Allows and disallows access to pub/sub channels. Entries are defined as standard glob patterns. Changing this property forces recreation of the resource. +- `valkey_acl_commands` (List of String) Defines rules for individual commands. To allow a command use the prefix `+` and to disallow use `-`. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. +- `valkey_acl_keys` (List of String) Key access rules. Entries are defined as standard glob patterns. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. diff --git a/docs/resources/valkey.md b/docs/resources/valkey.md index 3a9168433..3770f3b5f 100644 --- a/docs/resources/valkey.md +++ b/docs/resources/valkey.md @@ -3,12 +3,12 @@ page_title: "aiven_valkey Resource - terraform-provider-aiven" subcategory: "" description: |- - Creates and manages an Aiven for Valkey https://aiven.io/docs/products/valkey service. + Creates and manages an Aiven for Valkey™ https://aiven.io/docs/products/valkey service. --- # aiven_valkey (Resource) -Creates and manages an [Aiven for Valkey](https://aiven.io/docs/products/valkey) service. +Creates and manages an [Aiven for Valkey™](https://aiven.io/docs/products/valkey) service. ## Example Usage diff --git a/docs/resources/valkey_user.md b/docs/resources/valkey_user.md index 7d3665e8b..24123694e 100644 --- a/docs/resources/valkey_user.md +++ b/docs/resources/valkey_user.md @@ -3,14 +3,59 @@ page_title: "aiven_valkey_user Resource - terraform-provider-aiven" subcategory: "" description: |- - Creates and manages an Aiven for Valkey https://aiven.io/docs/products/valkey user. + Creates and manages an Aiven for Valkey™ https://aiven.io/docs/products/valkey service user. --- # aiven_valkey_user (Resource) -Creates and manages an [Aiven for Valkey](https://aiven.io/docs/products/valkey) user. +Creates and manages an [Aiven for Valkey™](https://aiven.io/docs/products/valkey) service user. +## Example Usage +```terraform +# Example user with read-only access for analytics +resource "aiven_valkey_user" "read_analytics" { + project = data.aiven_project.example_project.project + service_name = aiven_valkey.example_valkey.service_name + username = "example-analytics-reader" + password = var.valkey_user_pw + valkey_acl_categories = [ + "+@read" + ] + valkey_acl_commands = [ + "+get", + "+set", + "+mget", + "+hget", + "+zrange" + ] + valkey_acl_keys = [ + "analytics:*" + ] +} + +# Example user with restricted write access for session management +resource "aiven_valkey_user" "manage_sessions" { + project = data.aiven_project.example_project.project + service_name = aiven_valkey.example_valkey.service_name + username = "example-session-manager" + password = var.valkey_user_pw + valkey_acl_categories = [ + "+@write", + "+@keyspace", + ] + valkey_acl_commands = [ + "+set", + "+del", + "+expire", + "-flushall", + "-flushdb" + ] + valkey_acl_keys = [ + "session:*" + ] +} +``` ## Schema @@ -19,21 +64,21 @@ Creates and manages an [Aiven for Valkey](https://aiven.io/docs/products/valkey) - `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. - `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. -- `username` (String) The actual name of the Valkey User. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource. +- `username` (String) Name of the Valkey service user. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource. ### Optional -- `password` (String, Sensitive) The password of the Valkey User. +- `password` (String, Sensitive) The Valkey service user's password. - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts)) -- `valkey_acl_categories` (List of String) Defines command category rules. The field is required with`valkey_acl_commands` and `valkey_acl_keys`. Changing this property forces recreation of the resource. -- `valkey_acl_channels` (List of String) Defines the permitted pub/sub channel patterns. Changing this property forces recreation of the resource. -- `valkey_acl_commands` (List of String) Defines rules for individual commands. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. -- `valkey_acl_keys` (List of String) Defines key access rules. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. +- `valkey_acl_categories` (List of String) Allow or disallow command categories. To allow a category use the prefix `+@` and to disallow use `-@`. See the [Valkey documentation](https://valkey.io/topics/acl/) for details on the ACL feature. The field is required with`valkey_acl_commands` and `valkey_acl_keys`. Changing this property forces recreation of the resource. +- `valkey_acl_channels` (List of String) Allows and disallows access to pub/sub channels. Entries are defined as standard glob patterns. Changing this property forces recreation of the resource. +- `valkey_acl_commands` (List of String) Defines rules for individual commands. To allow a command use the prefix `+` and to disallow use `-`. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. +- `valkey_acl_keys` (List of String) Key access rules. Entries are defined as standard glob patterns. The field is required with`valkey_acl_categories` and `valkey_acl_keys`. Changing this property forces recreation of the resource. ### Read-Only - `id` (String) The ID of this resource. -- `type` (String) Type of the user account. Tells whether the user is the primary account or a regular account. +- `type` (String) User account type, such as primary or regular account. ### Nested Schema for `timeouts` @@ -45,3 +90,11 @@ Optional: - `delete` (String) - `read` (String) - `update` (String) + +## Import + +Import is supported using the following syntax: + +```shell +terraform import aiven_valkey.example_valkey PROJECT/SERVICE_NAME/USERNAME +``` diff --git a/examples/resources/aiven_valkey_user/import.sh b/examples/resources/aiven_valkey_user/import.sh new file mode 100644 index 000000000..6b93e8ab1 --- /dev/null +++ b/examples/resources/aiven_valkey_user/import.sh @@ -0,0 +1 @@ +terraform import aiven_valkey.example_valkey PROJECT/SERVICE_NAME/USERNAME diff --git a/examples/resources/aiven_valkey_user/resource.tf b/examples/resources/aiven_valkey_user/resource.tf new file mode 100644 index 000000000..8b6085b6d --- /dev/null +++ b/examples/resources/aiven_valkey_user/resource.tf @@ -0,0 +1,42 @@ +# Example user with read-only access for analytics +resource "aiven_valkey_user" "read_analytics" { + project = data.aiven_project.example_project.project + service_name = aiven_valkey.example_valkey.service_name + username = "example-analytics-reader" + password = var.valkey_user_pw + valkey_acl_categories = [ + "+@read" + ] + valkey_acl_commands = [ + "+get", + "+set", + "+mget", + "+hget", + "+zrange" + ] + valkey_acl_keys = [ + "analytics:*" + ] +} + +# Example user with restricted write access for session management +resource "aiven_valkey_user" "manage_sessions" { + project = data.aiven_project.example_project.project + service_name = aiven_valkey.example_valkey.service_name + username = "example-session-manager" + password = var.valkey_user_pw + valkey_acl_categories = [ + "+@write", + "+@keyspace", + ] + valkey_acl_commands = [ + "+set", + "+del", + "+expire", + "-flushall", + "-flushdb" + ] + valkey_acl_keys = [ + "session:*" + ] +} \ No newline at end of file diff --git a/internal/sdkprovider/service/valkey/valkey.go b/internal/sdkprovider/service/valkey/valkey.go index 7682eb952..03bb0cf58 100644 --- a/internal/sdkprovider/service/valkey/valkey.go +++ b/internal/sdkprovider/service/valkey/valkey.go @@ -59,7 +59,7 @@ func valkeySchema() map[string]*schema.Schema { func ResourceValkey() *schema.Resource { return &schema.Resource{ - Description: "Creates and manages an [Aiven for Valkey](https://aiven.io/docs/products/valkey) service.", + Description: "Creates and manages an [Aiven for Valkey™](https://aiven.io/docs/products/valkey) service.", CreateContext: schemautil.ResourceServiceCreateWrapper(schemautil.ServiceTypeValkey), ReadContext: schemautil.ResourceServiceRead, UpdateContext: schemautil.ResourceServiceUpdate, diff --git a/internal/sdkprovider/service/valkey/valkey_user.go b/internal/sdkprovider/service/valkey/valkey_user.go index a0049a3de..9e7f70a3f 100644 --- a/internal/sdkprovider/service/valkey/valkey_user.go +++ b/internal/sdkprovider/service/valkey/valkey_user.go @@ -21,7 +21,7 @@ var aivenValkeyUserSchema = map[string]*schema.Schema{ Required: true, ForceNew: true, ValidateFunc: schemautil.GetServiceUserValidateFunc(), - Description: userconfig.Desc("The actual name of the Valkey User.").ForceNew().Referenced().Build(), + Description: userconfig.Desc("Name of the Valkey service user.").ForceNew().Referenced().Build(), }, "password": { Type: schema.TypeString, @@ -29,14 +29,14 @@ var aivenValkeyUserSchema = map[string]*schema.Schema{ Sensitive: true, Computed: true, DiffSuppressFunc: schemautil.EmptyObjectDiffSuppressFunc, - Description: "The password of the Valkey User.", + Description: "The Valkey service user's password.", }, "valkey_acl_categories": { Type: schema.TypeList, Optional: true, ForceNew: true, RequiredWith: []string{"valkey_acl_commands", "valkey_acl_keys"}, - Description: userconfig.Desc("Defines command category rules.").RequiredWith("valkey_acl_commands", "valkey_acl_keys").ForceNew().Build(), + Description: userconfig.Desc("Allow or disallow command categories. To allow a category use the prefix `+@` and to disallow use `-@`. See the [Valkey documentation](https://valkey.io/topics/acl/) for details on the ACL feature.").RequiredWith("valkey_acl_commands", "valkey_acl_keys").ForceNew().Build(), Elem: &schema.Schema{ Type: schema.TypeString, }, @@ -46,7 +46,7 @@ var aivenValkeyUserSchema = map[string]*schema.Schema{ Optional: true, ForceNew: true, RequiredWith: []string{"valkey_acl_categories", "valkey_acl_keys"}, - Description: userconfig.Desc("Defines rules for individual commands.").RequiredWith("valkey_acl_categories", "valkey_acl_keys").ForceNew().Build(), + Description: userconfig.Desc("Defines rules for individual commands. To allow a command use the prefix `+` and to disallow use `-`.").RequiredWith("valkey_acl_categories", "valkey_acl_keys").ForceNew().Build(), Elem: &schema.Schema{ Type: schema.TypeString, }, @@ -56,7 +56,7 @@ var aivenValkeyUserSchema = map[string]*schema.Schema{ Optional: true, ForceNew: true, RequiredWith: []string{"valkey_acl_categories", "valkey_acl_commands"}, - Description: userconfig.Desc("Defines key access rules.").RequiredWith("valkey_acl_categories", "valkey_acl_keys").ForceNew().Build(), + Description: userconfig.Desc("Key access rules. Entries are defined as standard glob patterns.").RequiredWith("valkey_acl_categories", "valkey_acl_keys").ForceNew().Build(), Elem: &schema.Schema{ Type: schema.TypeString, }, @@ -65,7 +65,7 @@ var aivenValkeyUserSchema = map[string]*schema.Schema{ Type: schema.TypeList, Optional: true, ForceNew: true, - Description: userconfig.Desc("Defines the permitted pub/sub channel patterns.").ForceNew().Build(), + Description: userconfig.Desc("Allows and disallows access to pub/sub channels. Entries are defined as standard glob patterns.").ForceNew().Build(), Elem: &schema.Schema{ Type: schema.TypeString, }, @@ -75,13 +75,13 @@ var aivenValkeyUserSchema = map[string]*schema.Schema{ "type": { Type: schema.TypeString, Computed: true, - Description: "Type of the user account. Tells whether the user is the primary account or a regular account.", + Description: "User account type, such as primary or regular account.", }, } func ResourceValkeyUser() *schema.Resource { return &schema.Resource{ - Description: "Creates and manages an [Aiven for Valkey](https://aiven.io/docs/products/valkey) user.", + Description: "Creates and manages an [Aiven for Valkey™](https://aiven.io/docs/products/valkey) service user.", CreateContext: common.WithGenClient(resourceValkeyUserCreate), UpdateContext: common.WithGenClient(resourceValkeyUserUpdate), ReadContext: common.WithGenClient(resourceValkeyUserRead),