From e4d4c9acde843806e3f1351254333e8f5da8877d Mon Sep 17 00:00:00 2001 From: Stacey Salamon Date: Thu, 7 Mar 2024 12:26:19 +0100 Subject: [PATCH] docs: add LA note and update app users --- .../organization_application_user.md | 24 +++++++--- .../organization_application_user.md | 37 ++++++++++----- .../organization_application_user_token.md | 46 ++++++++++++++----- docs/resources/organization_group_project.md | 1 + .../organization_user_group_member.md | 1 + .../data-source.tf | 4 ++ .../import.sh | 1 + .../resource.tf | 4 ++ .../import.sh | 1 + .../resource.tf | 10 ++++ .../organization_application_user.go | 14 +++--- ...ganization_application_user_data_source.go | 17 +++++-- .../organization_application_user_token.go | 28 +++++------ internal/schemautil/userconfig/desc.go | 3 +- 14 files changed, 136 insertions(+), 55 deletions(-) create mode 100644 examples/data-sources/aiven_organization_application_user/data-source.tf create mode 100644 examples/resources/aiven_organization_application_user/import.sh create mode 100644 examples/resources/aiven_organization_application_user/resource.tf create mode 100644 examples/resources/aiven_organization_application_user_token/import.sh create mode 100644 examples/resources/aiven_organization_application_user_token/resource.tf diff --git a/docs/data-sources/organization_application_user.md b/docs/data-sources/organization_application_user.md index 017705b49..3a6de00b9 100644 --- a/docs/data-sources/organization_application_user.md +++ b/docs/data-sources/organization_application_user.md @@ -3,24 +3,36 @@ page_title: "aiven_organization_application_user Data Source - terraform-provider-aiven" subcategory: "" description: |- - Retrieves information about an organization application user from Aiven. + Gets information about an application user. + This data source is in the limited availability stage and may change without notice. To enable this feature, contact the sales team mailto:sales@aiven.io. After it's enabled, set + the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the data source. --- # aiven_organization_application_user (Data Source) -Retrieves information about an organization application user from Aiven. +Gets information about an application user. +**This data source is in the limited availability stage and may change without notice.** To enable this feature, contact the [sales team](mailto:sales@aiven.io). After it's enabled, set +the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the data source. +## Example Usage + +```terraform +data "aiven_organization_application_user" "tf_user" { + organization_id = aiven_organization.main.id + user_id = "u123a456b7890c" +} +``` ## Schema ### Required -- `organization_id` (String) Identifier of the organization the application user belongs to. -- `user_id` (String) Identifier of the organization application user. +- `organization_id` (String) The ID of the organization the application user belongs to. +- `user_id` (String) The ID of the application user. ### Read-Only -- `email` (String) Email of the organization application user. -- `name` (String) Name of the organization application user. +- `email` (String) The auto-generated email address of the application user. +- `name` (String) Name of the application user. diff --git a/docs/resources/organization_application_user.md b/docs/resources/organization_application_user.md index 676c7f344..d348e0480 100644 --- a/docs/resources/organization_application_user.md +++ b/docs/resources/organization_application_user.md @@ -3,28 +3,34 @@ page_title: "aiven_organization_application_user Resource - terraform-provider-aiven" subcategory: "" description: |- - Creates and manages an organization application user. Application users can be used for programmatic access to the platform. - This resource is in the limited availability stage and may change without notice. - To enable this feature, contact the sales team mailto:sales@aiven.io. After it's enabled, set + Creates and manages an organization application user. Application users https://aiven.io/docs/platform/howto/manage-application-users can be used for programmatic access to the platform. + This resource is in the limited availability stage and may change without notice. To enable this feature, contact the sales team mailto:sales@aiven.io. After it's enabled, set the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource. --- # aiven_organization_application_user (Resource) -Creates and manages an organization application user. Application users can be used for programmatic access to the platform. -**This resource is in the limited availability stage and may change without notice.** -To enable this feature, contact the [sales team](mailto:sales@aiven.io). After it's enabled, set +Creates and manages an organization application user. [Application users](https://aiven.io/docs/platform/howto/manage-application-users) can be used for programmatic access to the platform. + +**This resource is in the limited availability stage and may change without notice.** To enable this feature, contact the [sales team](mailto:sales@aiven.io). After it's enabled, set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource. +## Example Usage +```terraform +resource "aiven_organization_application_user" "tf_user" { + organization_id = aiven_organization.main.id + name = "app-terraform" +} +``` ## Schema ### Required -- `name` (String) Name of the organization application user. -- `organization_id` (String) Identifier of the organization the application user belongs to. +- `name` (String) Name of the application user. +- `organization_id` (String) The ID of the organization the application user belongs to. ### Optional @@ -32,9 +38,10 @@ the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource. ### Read-Only -- `email` (String) Email of the organization application user. -- `id` (String) Compound identifier of the organization application user. -- `user_id` (String) Identifier of the organization application user. +- `email` (String) An email address automatically generated by Aiven to help identify the application user. + No notifications are sent to this email. +- `id` (String) A compound identifier of the resource in the format `organization_id/user_id`. +- `user_id` (String) The ID of the application user. ### Nested Schema for `timeouts` @@ -45,3 +52,11 @@ Optional: - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs. - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled. - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). + +## Import + +Import is supported using the following syntax: + +```shell +terraform import aiven_organization_application_user.example ORGANIZATION_ID/USER_ID +``` diff --git a/docs/resources/organization_application_user_token.md b/docs/resources/organization_application_user_token.md index f3d83dbb2..97e082ea1 100644 --- a/docs/resources/organization_application_user_token.md +++ b/docs/resources/organization_application_user_token.md @@ -3,45 +3,59 @@ page_title: "aiven_organization_application_user_token Resource - terraform-provider-aiven" subcategory: "" description: |- - Creates and manages an organization application user token in Aiven. + Creates and manages an application user token. Review the best practices https://aiven.io/docs/platform/concepts/application-users#security-best-practices for securing application users and their tokens. This resource is in the beta stage and may change without notice. Set the PROVIDER_AIVEN_ENABLE_BETA environment variable to use the resource. --- # aiven_organization_application_user_token (Resource) -Creates and manages an organization application user token in Aiven. +Creates and manages an application user token. Review the [best practices](https://aiven.io/docs/platform/concepts/application-users#security-best-practices) for securing application users and their tokens. + **This resource is in the beta stage and may change without notice.** Set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource. +## Example Usage + +```terraform +resource "aiven_organization_application_user" "tf_user" { + organization_id = aiven_organization.main.id + name = "app-terraform" +} +resource "aiven_organization_application_user_token" "example" { + organization_id = aiven_organization.main.id + user_id = aiven_organization_application_user.tf_user.user_id + description = "Token for TF access to Aiven." +} +``` ## Schema ### Required -- `organization_id` (String) Identifier of the organization the application user token belongs to. -- `user_id` (String) Identifier of the application user the token belongs to. +- `organization_id` (String) The ID of the organization the application user belongs to. +- `user_id` (String) The ID of the application user the token is created for. ### Optional - `description` (String) Description of the token. -- `extend_when_used` (Boolean) True to extend token expiration time when token is used. Only applicable if max_age_seconds is specified. -- `max_age_seconds` (Number) Time the token remains valid since creation (or since last use if extend_when_used is true). -- `scopes` (Set of String) Scopes this token is restricted to if specified. +- `extend_when_used` (Boolean) Extends the token session duration when the token is used. Only applicable if a value is set for `max_age_seconds`. +- `max_age_seconds` (Number) The number of hours after which a token expires. Default session duration is 10 hours. +- `scopes` (Set of String) Restricts the scopes for this token. - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts)) ### Read-Only - `create_time` (String) Time when the token was created. -- `created_manually` (Boolean) True for tokens explicitly created via the access_tokens API, false for tokens created via login. -- `currently_active` (Boolean) True if API request was made with this access token. -- `expiry_time` (String) Timestamp when the access token will expire unless extended, if ever. +- `created_manually` (Boolean) True for tokens explicitly created using the `access_tokens` API. False for tokens created when a user logs in. +- `currently_active` (Boolean) True if the API request was made with this token. +- `expiry_time` (String) Timestamp when the access token will expire unless extended. - `full_token` (String, Sensitive) Full token. -- `id` (String) Compound identifier of the organization application user token. +- `id` (String) Compound identifier of the application user token. - `last_ip` (String) IP address of the last request made with this token. -- `last_used_time` (String) Timestamp when the access token was last used, if ever. +- `last_used_time` (String) Timestamp when the access token was last used. - `last_user_agent` (String) User agent of the last request made with this token. - `last_user_agent_human_readable` (String) User agent of the last request made with this token in human-readable format. - `token_prefix` (String) Prefix of the token. @@ -55,3 +69,11 @@ Optional: - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs. - `read` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Read operations occur during any refresh or planning operation when refresh is enabled. - `update` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). + +## Import + +Import is supported using the following syntax: + +```shell +terraform import aiven_organization_application_user_token.example ORGANIZATION_ID/USER_ID/TOKEN_PREFIX +``` diff --git a/docs/resources/organization_group_project.md b/docs/resources/organization_group_project.md index 6010141eb..6a4bbfda9 100644 --- a/docs/resources/organization_group_project.md +++ b/docs/resources/organization_group_project.md @@ -11,6 +11,7 @@ description: |- # aiven_organization_group_project (Resource) Adds and manages a [group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups) of users as [members of a project](https://aiven.io/docs/platform/reference/project-member-privileges). + **This resource is in the beta stage and may change without notice.** Set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource. diff --git a/docs/resources/organization_user_group_member.md b/docs/resources/organization_user_group_member.md index 308a945df..a4f41243e 100644 --- a/docs/resources/organization_user_group_member.md +++ b/docs/resources/organization_user_group_member.md @@ -11,6 +11,7 @@ description: |- # aiven_organization_user_group_member (Resource) Adds and manages users in a [user group](https://aiven.io/docs/platform/concepts/projects_accounts_access#groups). + **This resource is in the beta stage and may change without notice.** Set the `PROVIDER_AIVEN_ENABLE_BETA` environment variable to use the resource. diff --git a/examples/data-sources/aiven_organization_application_user/data-source.tf b/examples/data-sources/aiven_organization_application_user/data-source.tf new file mode 100644 index 000000000..b5c09a6ce --- /dev/null +++ b/examples/data-sources/aiven_organization_application_user/data-source.tf @@ -0,0 +1,4 @@ +data "aiven_organization_application_user" "tf_user" { + organization_id = aiven_organization.main.id + user_id = "u123a456b7890c" +} diff --git a/examples/resources/aiven_organization_application_user/import.sh b/examples/resources/aiven_organization_application_user/import.sh new file mode 100644 index 000000000..28c55caf7 --- /dev/null +++ b/examples/resources/aiven_organization_application_user/import.sh @@ -0,0 +1 @@ +terraform import aiven_organization_application_user.example ORGANIZATION_ID/USER_ID diff --git a/examples/resources/aiven_organization_application_user/resource.tf b/examples/resources/aiven_organization_application_user/resource.tf new file mode 100644 index 000000000..da187cd51 --- /dev/null +++ b/examples/resources/aiven_organization_application_user/resource.tf @@ -0,0 +1,4 @@ +resource "aiven_organization_application_user" "tf_user" { + organization_id = aiven_organization.main.id + name = "app-terraform" +} \ No newline at end of file diff --git a/examples/resources/aiven_organization_application_user_token/import.sh b/examples/resources/aiven_organization_application_user_token/import.sh new file mode 100644 index 000000000..d4e0adca7 --- /dev/null +++ b/examples/resources/aiven_organization_application_user_token/import.sh @@ -0,0 +1 @@ +terraform import aiven_organization_application_user_token.example ORGANIZATION_ID/USER_ID/TOKEN_PREFIX diff --git a/examples/resources/aiven_organization_application_user_token/resource.tf b/examples/resources/aiven_organization_application_user_token/resource.tf new file mode 100644 index 000000000..1e677d740 --- /dev/null +++ b/examples/resources/aiven_organization_application_user_token/resource.tf @@ -0,0 +1,10 @@ +resource "aiven_organization_application_user" "tf_user" { + organization_id = aiven_organization.main.id + name = "app-terraform" +} + +resource "aiven_organization_application_user_token" "example" { + organization_id = aiven_organization.main.id + user_id = aiven_organization_application_user.tf_user.user_id + description = "Token for TF access to Aiven." +} \ No newline at end of file diff --git a/internal/plugin/service/organization/organization_application_user.go b/internal/plugin/service/organization/organization_application_user.go index 4f44ffb64..3939f5d70 100644 --- a/internal/plugin/service/organization/organization_application_user.go +++ b/internal/plugin/service/organization/organization_application_user.go @@ -81,39 +81,41 @@ func (r *organizationApplicationUser) Schema( resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{ Description: userconfig. Desc( - "Creates and manages an organization application user. Application users can be used for " + + "Creates and manages an organization application user. [Application users](https://aiven.io/docs/platform/howto/manage-application-users) can be used for " + "programmatic access to the platform.", ). AvailabilityType(userconfig.Limited). Build(), Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ - Description: "Compound identifier of the organization application user.", + Description: "A compound identifier of the resource in the format `organization_id/user_id`.", Computed: true, PlanModifiers: []planmodifier.String{ stringplanmodifier.UseStateForUnknown(), }, }, "organization_id": schema.StringAttribute{ - Description: "Identifier of the organization the application user belongs to.", + Description: "The ID of the organization the application user belongs to.", Required: true, PlanModifiers: []planmodifier.String{ stringplanmodifier.RequiresReplace(), }, }, "user_id": schema.StringAttribute{ - Description: "Identifier of the organization application user.", + Description: "The ID of the application user.", Computed: true, PlanModifiers: []planmodifier.String{ stringplanmodifier.UseStateForUnknown(), }, }, "name": schema.StringAttribute{ - Description: "Name of the organization application user.", + Description: "Name of the application user.", Required: true, }, "email": schema.StringAttribute{ - Description: "Email of the organization application user.", + Description: `An email address automatically generated by Aiven to help identify the application user. + No notifications are sent to this email. + `, Computed: true, }, }, diff --git a/internal/plugin/service/organization/organization_application_user_data_source.go b/internal/plugin/service/organization/organization_application_user_data_source.go index 111ffd36b..c6e67d790 100644 --- a/internal/plugin/service/organization/organization_application_user_data_source.go +++ b/internal/plugin/service/organization/organization_application_user_data_source.go @@ -9,6 +9,7 @@ import ( "github.com/hashicorp/terraform-plugin-framework/types" "github.com/aiven/terraform-provider-aiven/internal/plugin/util" + "github.com/aiven/terraform-provider-aiven/internal/schemautil/userconfig" ) var ( @@ -67,22 +68,28 @@ func (r *organizationApplicationUserDataSource) Schema( resp *datasource.SchemaResponse, ) { resp.Schema = schema.Schema{ - Description: "Retrieves information about an organization application user from Aiven.", + Description: userconfig. + Desc( + "Gets information about an application user.", + ). + MarkAsDataSource(). + AvailabilityType(userconfig.Limited). + Build(), Attributes: map[string]schema.Attribute{ "organization_id": schema.StringAttribute{ - Description: "Identifier of the organization the application user belongs to.", + Description: "The ID of the organization the application user belongs to.", Required: true, }, "user_id": schema.StringAttribute{ - Description: "Identifier of the organization application user.", + Description: "The ID of the application user.", Required: true, }, "name": schema.StringAttribute{ - Description: "Name of the organization application user.", + Description: "Name of the application user.", Computed: true, }, "email": schema.StringAttribute{ - Description: "Email of the organization application user.", + Description: "The auto-generated email address of the application user.", Computed: true, }, }, diff --git a/internal/plugin/service/organization/organization_application_user_token.go b/internal/plugin/service/organization/organization_application_user_token.go index eea6d0e36..1f1bc76e0 100644 --- a/internal/plugin/service/organization/organization_application_user_token.go +++ b/internal/plugin/service/organization/organization_application_user_token.go @@ -109,26 +109,27 @@ func (r *organizationApplicationUserToken) Schema( resp *resource.SchemaResponse, ) { resp.Schema = util.GeneralizeSchema(ctx, schema.Schema{ - Description: userconfig.Desc("Creates and manages an organization application user token in Aiven."). + Description: userconfig.Desc("Creates and manages an application user token. Review the" + + " [best practices](https://aiven.io/docs/platform/concepts/application-users#security-best-practices) for securing application users and their tokens."). AvailabilityType(userconfig.Beta). Build(), Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ - Description: "Compound identifier of the organization application user token.", + Description: "Compound identifier of the application user token.", Computed: true, PlanModifiers: []planmodifier.String{ stringplanmodifier.UseStateForUnknown(), }, }, "organization_id": schema.StringAttribute{ - Description: "Identifier of the organization the application user token belongs to.", + Description: "The ID of the organization the application user belongs to.", Required: true, PlanModifiers: []planmodifier.String{ stringplanmodifier.RequiresReplace(), }, }, "user_id": schema.StringAttribute{ - Description: "Identifier of the application user the token belongs to.", + Description: "The ID of the application user the token is created for.", Required: true, PlanModifiers: []planmodifier.String{ stringplanmodifier.RequiresReplace(), @@ -154,23 +155,22 @@ func (r *organizationApplicationUserToken) Schema( }, }, "max_age_seconds": schema.NumberAttribute{ - Description: "Time the token remains valid since creation (or since last use if " + - "extend_when_used is true).", + Description: "The number of hours after which a token expires. Default session duration is 10 hours.", Optional: true, PlanModifiers: []planmodifier.Number{ numberplanmodifier.RequiresReplace(), }, }, "extend_when_used": schema.BoolAttribute{ - Description: "True to extend token expiration time when token is used. Only applicable if " + - "max_age_seconds is specified.", + Description: "Extends the token session duration when the token is used. Only applicable if " + + "a value is set for `max_age_seconds`.", Optional: true, PlanModifiers: []planmodifier.Bool{ boolplanmodifier.RequiresReplace(), }, }, "scopes": schema.SetAttribute{ - Description: "Scopes this token is restricted to if specified.", + Description: "Restricts the scopes for this token.", Optional: true, ElementType: types.StringType, PlanModifiers: []planmodifier.Set{ @@ -178,7 +178,7 @@ func (r *organizationApplicationUserToken) Schema( }, }, "currently_active": schema.BoolAttribute{ - Description: "True if API request was made with this access token.", + Description: "True if the API request was made with this token.", Computed: true, }, "create_time": schema.StringAttribute{ @@ -186,12 +186,12 @@ func (r *organizationApplicationUserToken) Schema( Computed: true, }, "created_manually": schema.BoolAttribute{ - Description: "True for tokens explicitly created via the access_tokens API, false for tokens created " + - "via login.", + Description: "True for tokens explicitly created using the `access_tokens` API. False for tokens created " + + "when a user logs in.", Computed: true, }, "expiry_time": schema.StringAttribute{ - Description: "Timestamp when the access token will expire unless extended, if ever.", + Description: "Timestamp when the access token will expire unless extended.", Computed: true, }, "last_ip": schema.StringAttribute{ @@ -199,7 +199,7 @@ func (r *organizationApplicationUserToken) Schema( Computed: true, }, "last_used_time": schema.StringAttribute{ - Description: "Timestamp when the access token was last used, if ever.", + Description: "Timestamp when the access token was last used.", Computed: true, }, "last_user_agent": schema.StringAttribute{ diff --git a/internal/schemautil/userconfig/desc.go b/internal/schemautil/userconfig/desc.go index 324a597d9..fa126c5c2 100644 --- a/internal/schemautil/userconfig/desc.go +++ b/internal/schemautil/userconfig/desc.go @@ -139,6 +139,7 @@ func (db *DescriptionBuilder) Build() string { builder.WriteRune(' ') const availabilityCommonPart = ` + **This %[1]s is in the %[2]s stage and may change without notice.** %[3]s the ` + "`PROVIDER_AIVEN_ENABLE_BETA`" + ` environment variable to use the %[1]s.` @@ -155,7 +156,7 @@ the ` + "`PROVIDER_AIVEN_ENABLE_BETA`" + ` environment variable to use the %[1]s availabilityCommonPart, db.entityType.String(), "limited availability", - "\nTo enable this feature, contact the [sales team](mailto:sales@aiven.io). After it's enabled, set", + " To enable this feature, contact the [sales team](mailto:sales@aiven.io). After it's enabled, set", )) } }