docs: improve M3, Grafana, connection pools (#1821)

docs/data-sources/connection_pool.md

@@ -3,20 +3,20 @@
 page_title: "aiven_connection_pool Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Connection Pool data source provides information about the existing Aiven Connection Pool.
+  Gets information about a connection pool in an Aiven for PostgreSQL® service.
 ---
 
 # aiven_connection_pool (Data Source)
 
-The Connection Pool data source provides information about the existing Aiven Connection Pool.
+Gets information about a connection pool in an Aiven for PostgreSQL® service.
 
 ## Example Usage
 
 ```terraform
-data "aiven_connection_pool" "mytestpool" {
-  project      = aiven_project.myproject.project
-  service_name = aiven_pg.mypg.service_name
-  pool_name    = "mypool"
+data "aiven_connection_pool" "main" {
+  project      = data.aiven_project.example_project.project
+  service_name = aiven_pg.example_postgres.service_name
+  pool_name    = "example-pool"
 }
 ```
 
@@ -25,15 +25,15 @@ data "aiven_connection_pool" "mytestpool" {
 
 ### Required
 
-- `pool_name` (String) The name of the created pool. Changing this property forces recreation of the resource.
+- `pool_name` (String) Name of the pool. 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.
 - `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.
 
 ### Read-Only
 
-- `connection_uri` (String, Sensitive) The URI for connecting to the pool
+- `connection_uri` (String, Sensitive) The URI for connecting to the pool.
 - `database_name` (String) The name of the database the pool connects to. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource.
 - `id` (String) The ID of this resource.
-- `pool_mode` (String) The mode the pool operates in. The possible values are `session`, `transaction` and `statement`. The default value is `transaction`.
-- `pool_size` (Number) The number of connections the pool may create towards the backend server. This does not affect the number of incoming connections, which is always a much larger number. The default value is `10`.
+- `pool_mode` (String) The [operational mode](https://aiven.io/docs/products/postgresql/concepts/pg-connection-pooling#pooling-modes). The possible values are `session`, `transaction` and `statement`. The default value is `transaction`.
+- `pool_size` (Number) The number of PostgreSQL server connections this pool can use at a time. This does not affect the number of incoming connections. Each pool can handle a minimum of 5000 client connections. The default value is `10`.
 - `username` (String) The name of the service user used to connect to the database. To set up proper dependencies please refer to this variable as a reference.

docs/data-sources/grafana.md

@@ -3,19 +3,19 @@
 page_title: "aiven_grafana Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Grafana data source provides information about the existing Aiven Grafana service.
+  Gets information about an Aiven for Grafana® service.
 ---
 
 # aiven_grafana (Data Source)
 
-The Grafana data source provides information about the existing Aiven Grafana service.
+Gets information about an Aiven for Grafana® service.
 
 ## Example Usage
 
 ```terraform
-data "aiven_grafana" "gr1" {
-  project      = data.aiven_project.ps1.project
-  service_name = "my-gr1"
+data "aiven_grafana" "example_grafana" {
+  project      = data.aiven_project.example_project.project
+  service_name = "example-grafana-service"
 }
 ```
 
@@ -37,7 +37,7 @@ data "aiven_grafana" "gr1" {
 - `disk_space_default` (String) The default disk space of the service, possible values depend on the service type, the cloud provider and the project. Its also the minimum value for `disk_space`
 - `disk_space_step` (String) The default disk space step of the service, possible values depend on the service type, the cloud provider and the project. `disk_space` needs to increment from `disk_space_default` by increments of this size.
 - `disk_space_used` (String) Disk space that service is currently using
-- `grafana` (List of Object, Sensitive) Grafana server provided values (see [below for nested schema](#nestedatt--grafana))
+- `grafana` (List of Object, Sensitive) Values provided by the Grafana server. (see [below for nested schema](#nestedatt--grafana))
 - `grafana_user_config` (List of Object) Grafana user configurable settings (see [below for nested schema](#nestedatt--grafana_user_config))
 - `id` (String) The ID of this resource.
 - `maintenance_window_dow` (String) Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.

docs/data-sources/m3db.md

@@ -3,19 +3,19 @@
 page_title: "aiven_m3db Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The M3 DB data source provides information about the existing Aiven M3 services.
+  Gets information about an Aiven for M3DB service.
 ---
 
 # aiven_m3db (Data Source)
 
-The M3 DB data source provides information about the existing Aiven M3 services.
+Gets information about an Aiven for M3DB service.
 
 ## Example Usage
 
 ```terraform
-data "aiven_m3db" "m3" {
-  project      = data.aiven_project.foo.project
-  service_name = "my-m3db"
+data "aiven_m3db" "example_m3db" {
+  project      = data.aiven_project.example_project.project
+  service_name = "example-m3db-service"
 }
 ```
 
@@ -38,7 +38,7 @@ data "aiven_m3db" "m3" {
 - `disk_space_step` (String) The default disk space step of the service, possible values depend on the service type, the cloud provider and the project. `disk_space` needs to increment from `disk_space_default` by increments of this size.
 - `disk_space_used` (String) Disk space that service is currently using
 - `id` (String) The ID of this resource.
-- `m3db` (List of Object, Sensitive) M3DB server provided values (see [below for nested schema](#nestedatt--m3db))
+- `m3db` (List of Object, Sensitive) Values provided by the M3DB server. (see [below for nested schema](#nestedatt--m3db))
 - `m3db_user_config` (List of Object) M3db user configurable settings (see [below for nested schema](#nestedatt--m3db_user_config))
 - `maintenance_window_dow` (String) Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.
 - `maintenance_window_time` (String) Time of day when maintenance operations should be performed. UTC time in HH:mm:ss format.

docs/data-sources/m3db_user.md

@@ -3,20 +3,20 @@
 page_title: "aiven_m3db_user Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The M3DB User data source provides information about the existing Aiven M3DB User.
+  Gets information about an Aiven for M3DB service user.
 ---
 
 # aiven_m3db_user (Data Source)
 
-The M3DB User data source provides information about the existing Aiven M3DB User.
+Gets information about an Aiven for M3DB service user.
 
 ## Example Usage
 
 ```terraform
-data "aiven_m3db_user" "user" {
-  service_name = "my-service"
-  project      = "my-project"
-  username     = "user1"
+data "aiven_m3db_user" "example_service_user" {
+  service_name = aiven_m3db.example_m3db.service_name
+  project      = data.aiven_project.example_project.project
+  username     = "example-m3db-user"
 }
 ```
 
@@ -27,10 +27,10 @@ data "aiven_m3db_user" "user" {
 
 - `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 M3DB 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 M3DB 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 M3DB User.
-- `type` (String) Type of the user account. Tells whether the user is the primary account or a regular account.
+- `password` (String, Sensitive) The M3DB service user's password.
+- `type` (String) User account type, such as primary or regular account.

docs/resources/connection_pool.md

@@ -3,24 +3,24 @@
 page_title: "aiven_connection_pool Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Connection Pool resource allows the creation and management of Aiven Connection Pools.
+  Creates and manages a connection pool https://aiven.io/docs/products/postgresql/concepts/pg-connection-pooling in an Aiven for PostgreSQL® service.
 ---
 
 # aiven_connection_pool (Resource)
 
-The Connection Pool resource allows the creation and management of Aiven Connection Pools.
+Creates and manages a [connection pool](https://aiven.io/docs/products/postgresql/concepts/pg-connection-pooling) in an Aiven for PostgreSQL® service.
 
 ## Example Usage
 
 ```terraform
-resource "aiven_connection_pool" "mytestpool" {
-  project       = aiven_project.myproject.project
-  service_name  = aiven_pg.mypg.service_name
-  database_name = aiven_pg_database.mypgdatabase.database_name
+resource "aiven_connection_pool" "main" {
+  project       = data.aiven_project.example_project.project
+  service_name  = aiven_pg.example_postgres.service_name
+  database_name = aiven_pg_database.main.database_name
   pool_mode     = "transaction"
-  pool_name     = "mypool"
+  pool_name     = "example-pool"
   pool_size     = 10
-  username      = aiven_pg_user.mypguser.username
+  username      = aiven_pg_user.example_user.username
 }
 ```
 
@@ -30,20 +30,20 @@ resource "aiven_connection_pool" "mytestpool" {
 ### Required
 
 - `database_name` (String) The name of the database the pool connects to. To set up proper dependencies please refer to this variable as a reference. Changing this property forces recreation of the resource.
-- `pool_name` (String) The name of the created pool. Changing this property forces recreation of the resource.
+- `pool_name` (String) Name of the pool. 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.
 - `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
 
-- `pool_mode` (String) The mode the pool operates in. The possible values are `session`, `transaction` and `statement`. The default value is `transaction`.
-- `pool_size` (Number) The number of connections the pool may create towards the backend server. This does not affect the number of incoming connections, which is always a much larger number. The default value is `10`.
+- `pool_mode` (String) The [operational mode](https://aiven.io/docs/products/postgresql/concepts/pg-connection-pooling#pooling-modes). The possible values are `session`, `transaction` and `statement`. The default value is `transaction`.
+- `pool_size` (Number) The number of PostgreSQL server connections this pool can use at a time. This does not affect the number of incoming connections. Each pool can handle a minimum of 5000 client connections. The default value is `10`.
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 - `username` (String) The name of the service user used to connect to the database. To set up proper dependencies please refer to this variable as a reference.
 
 ### Read-Only
 
-- `connection_uri` (String, Sensitive) The URI for connecting to the pool
+- `connection_uri` (String, Sensitive) The URI for connecting to the pool.
 - `id` (String) The ID of this resource.
 
 <a id="nestedblock--timeouts"></a>
@@ -62,5 +62,5 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_connection_pool.mytestpool PROJECT/SERVICE_NAME/POOL_NAME
+terraform import aiven_connection_pool.main PROJECT/SERVICE_NAME/POOL_NAME
 ```

docs/resources/grafana.md

@@ -3,21 +3,21 @@
 page_title: "aiven_grafana Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Grafana resource allows the creation and management of Aiven Grafana services.
+  Creates and manages an Aiven for Grafana® https://aiven.io/docs/products/grafana service.
 ---
 
 # aiven_grafana (Resource)
 
-The Grafana resource allows the creation and management of Aiven Grafana services.
+Creates and manages an [Aiven for Grafana®](https://aiven.io/docs/products/grafana) service.
 
 ## Example Usage
 
 ```terraform
-resource "aiven_grafana" "gr1" {
-  project                 = data.aiven_project.ps1.project
+resource "aiven_grafana" "example_grafana" {
+  project                 = data.aiven_project.example_project.project
   cloud_name              = "google-europe-west1"
   plan                    = "startup-1"
-  service_name            = "my-gr1"
+  service_name            = "example-grafana-service"
   maintenance_window_dow  = "monday"
   maintenance_window_time = "10:00:00"
 
@@ -45,7 +45,7 @@ resource "aiven_grafana" "gr1" {
 - `additional_disk_space` (String) Add [disk storage](https://aiven.io/docs/platform/howto/add-storage-space) in increments of 30  GiB to scale your service. The maximum value depends on the service type and cloud provider. Removing additional storage causes the service nodes to go through a rolling restart and there might be a short downtime for services with no HA capabilities.
 - `cloud_name` (String) Defines where the cloud provider and region where the service is hosted in. This can be changed freely after service is created. Changing the value will trigger a potentially lengthy migration process for the service. Format is cloud provider name (`aws`, `azure`, `do` `google`, `upcloud`, etc.), dash, and the cloud provider specific region name. These are documented on each Cloud provider's own support articles, like [here for Google](https://cloud.google.com/compute/docs/regions-zones/) and [here for AWS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html).
 - `disk_space` (String, Deprecated) Service disk space. Possible values depend on the service type, the cloud provider and the project. Therefore, reducing will result in the service rebalancing.
-- `grafana` (Block List, Max: 1) Grafana server provided values (see [below for nested schema](#nestedblock--grafana))
+- `grafana` (Block List, Max: 1) Values provided by the Grafana server. (see [below for nested schema](#nestedblock--grafana))
 - `grafana_user_config` (Block List, Max: 1) Grafana user configurable settings (see [below for nested schema](#nestedblock--grafana_user_config))
 - `maintenance_window_dow` (String) Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.
 - `maintenance_window_time` (String) Time of day when maintenance operations should be performed. UTC time in HH:mm:ss format.
@@ -354,5 +354,5 @@ Read-Only:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_grafana.gr1 project/service_name
+terraform import aiven_grafana.example_grafana PROJECT/SERVICE_NAME
 ```

docs/resources/m3db.md

@@ -3,29 +3,29 @@
 page_title: "aiven_m3db Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The M3 DB resource allows the creation and management of Aiven M3 services.
+  Creates and manages an Aiven for M3DB https://aiven.io/docs/products/m3db service.
 ---
 
 # aiven_m3db (Resource)
 
-The M3 DB resource allows the creation and management of Aiven M3 services.
+Creates and manages an [Aiven for M3DB](https://aiven.io/docs/products/m3db) service.
 
 ## Example Usage
 
 ```terraform
-resource "aiven_m3db" "m3" {
-  project                 = data.aiven_project.foo.project
+resource "aiven_m3db" "example_m3db" {
+  project                 = data.aiven_project.example_project.project
   cloud_name              = "google-europe-west1"
   plan                    = "business-8"
-  service_name            = "my-m3db"
+  service_name            = "example-m3db-service"
   maintenance_window_dow  = "monday"
   maintenance_window_time = "10:00:00"
 
   m3db_user_config {
     m3db_version = 1.1
 
     namespaces {
-      name = "my_ns1"
+      name = "example-namespace"
       type = "unaggregated"
     }
   }
@@ -46,7 +46,7 @@ resource "aiven_m3db" "m3" {
 - `additional_disk_space` (String) Add [disk storage](https://aiven.io/docs/platform/howto/add-storage-space) in increments of 30  GiB to scale your service. The maximum value depends on the service type and cloud provider. Removing additional storage causes the service nodes to go through a rolling restart and there might be a short downtime for services with no HA capabilities.
 - `cloud_name` (String) Defines where the cloud provider and region where the service is hosted in. This can be changed freely after service is created. Changing the value will trigger a potentially lengthy migration process for the service. Format is cloud provider name (`aws`, `azure`, `do` `google`, `upcloud`, etc.), dash, and the cloud provider specific region name. These are documented on each Cloud provider's own support articles, like [here for Google](https://cloud.google.com/compute/docs/regions-zones/) and [here for AWS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html).
 - `disk_space` (String, Deprecated) Service disk space. Possible values depend on the service type, the cloud provider and the project. Therefore, reducing will result in the service rebalancing.
-- `m3db` (Block List, Max: 1) M3DB server provided values (see [below for nested schema](#nestedblock--m3db))
+- `m3db` (Block List, Max: 1) Values provided by the M3DB server. (see [below for nested schema](#nestedblock--m3db))
 - `m3db_user_config` (Block List, Max: 1) M3db user configurable settings (see [below for nested schema](#nestedblock--m3db_user_config))
 - `maintenance_window_dow` (String) Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.
 - `maintenance_window_time` (String) Time of day when maintenance operations should be performed. UTC time in HH:mm:ss format.
@@ -316,5 +316,5 @@ Read-Only:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_m3db.m3 project/service_name
+terraform import aiven_m3db.example_m3db PROJECT/SERVICE_NAME
 ```