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/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..d37972e49 100644 --- a/internal/plugin/service/organization/organization_application_user.go +++ b/internal/plugin/service/organization/organization_application_user.go @@ -81,40 +81,42 @@ 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.", - Computed: true, + 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..610086c0a 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..0c02773de 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).", - Optional: 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", )) } }