docs: improve networking resource documentation

docs/data-sources/aws_privatelink.md

@@ -3,19 +3,19 @@
 page_title: "aiven_aws_privatelink Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The AWS Privatelink resource allows the creation and management of Aiven AWS Privatelink for a services.
+  Gets information about an AWS PrivateLink connection for an Aiven service.
 ---
 
 # aiven_aws_privatelink (Data Source)
 
-The AWS Privatelink resource allows the creation and management of Aiven AWS Privatelink for a services.
+Gets information about an AWS PrivateLink connection for an Aiven service.
 
 ## Example Usage
 
 ```terraform
-data "aiven_aws_privatelink" "foo" {
-  project      = data.aiven_project.foo.project
-  service_name = aiven_kafka.bar.service_name
+data "aiven_aws_privatelink" "main" {
+  project      = aiven_project.example_project.project
+  service_name = aiven_kafka.example_kafka.service_name
 }
 ```
 
@@ -29,7 +29,7 @@ data "aiven_aws_privatelink" "foo" {
 
 ### Read-Only
 
-- `aws_service_id` (String) AWS service ID
-- `aws_service_name` (String) AWS service name
+- `aws_service_id` (String) AWS service ID.
+- `aws_service_name` (String) AWS service name.
 - `id` (String) The ID of this resource.
-- `principals` (Set of String) List of allowed principals
+- `principals` (Set of String) List of the ARNs of the AWS accounts or IAM users allowed to connect to the VPC endpoint.

docs/data-sources/aws_vpc_peering_connection.md

@@ -3,20 +3,27 @@
 page_title: "aiven_aws_vpc_peering_connection Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The AWS VPC Peering Connection data source provides information about the existing Aiven VPC Peering Connection.
+  Gets information about an AWS VPC peering connection.
 ---
 
 # aiven_aws_vpc_peering_connection (Data Source)
 
-The AWS VPC Peering Connection data source provides information about the existing Aiven VPC Peering Connection.
+Gets information about an AWS VPC peering connection.
 
 ## Example Usage
 
 ```terraform
-data "aiven_aws_vpc_peering_connection" "foo" {
-  vpc_id         = data.aiven_project_vpc.vpc.id
-  aws_account_id = "XXXXX"
-  aws_vpc_id     = "XXXXX"
+resource "aiven_project_vpc" "example_vpc" {
+  project      = aiven_project.example_project.project
+  cloud_name   = "google-europe-west1"
+  network_cidr = "192.168.1.0/24"
+}
+
+data "aiven_aws_vpc_peering_connection" "aws_to_aiven_peering" {
+  vpc_id         = aiven_project_vpc.example_vpc.id
+  aws_account_id = var.aws_id
+  aws_vpc_id     = "vpc-1a2b3c4d5e6f7g8h9"
+  aws_vpc_region = "aws-us-east-2"
 }
 ```
 
@@ -27,12 +34,12 @@ data "aiven_aws_vpc_peering_connection" "foo" {
 
 - `aws_account_id` (String) AWS account ID. Changing this property forces recreation of the resource.
 - `aws_vpc_id` (String) AWS VPC ID. Changing this property forces recreation of the resource.
-- `aws_vpc_region` (String) AWS region of the peered VPC (if not in the same region as Aiven VPC). Changing this property forces recreation of the resource.
-- `vpc_id` (String) The VPC the peering connection belongs to. Changing this property forces recreation of the resource.
+- `aws_vpc_region` (String) The AWS region of the peered VPC, if different from the Aiven VPC region. Changing this property forces recreation of the resource.
+- `vpc_id` (String) The ID of the Aiven VPC. Changing this property forces recreation of the resource.
 
 ### Read-Only
 
-- `aws_vpc_peering_connection_id` (String) AWS VPC peering connection ID
+- `aws_vpc_peering_connection_id` (String) The ID of the AWS VPC peering connection.
 - `id` (String) The ID of this resource.
-- `state` (String) State of the peering connection
-- `state_info` (Map of String) State-specific help or error information
+- `state` (String) The state of the peering connection.
+- `state_info` (Map of String) State-specific help or error information.

docs/data-sources/azure_privatelink.md

@@ -3,19 +3,19 @@
 page_title: "aiven_azure_privatelink Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Azure Privatelink resource allows the creation and management of Aiven Azure Privatelink for a services.
+  Gets information about an Azure Private Link connection for an Aiven service.
 ---
 
 # aiven_azure_privatelink (Data Source)
 
-The Azure Privatelink resource allows the creation and management of Aiven Azure Privatelink for a services.
+Gets information about an Azure Private Link connection for an Aiven service.
 
 ## Example Usage
 
 ```terraform
-data "aiven_azure_privatelink" "foo" {
-  project      = data.aiven_project.foo.project
-  service_name = aiven_kafka.bar.service_name
+data "aiven_azure_privatelink" "main" {
+  project      = aiven_project.example_project.project
+  service_name = aiven_kafka.example_kafka.service_name
 }
 ```
 
@@ -29,9 +29,9 @@ data "aiven_azure_privatelink" "foo" {
 
 ### Read-Only
 
-- `azure_service_alias` (String) Azure Privatelink service alias
-- `azure_service_id` (String) Azure Privatelink service ID
+- `azure_service_alias` (String) The Azure Private Link service alias.
+- `azure_service_id` (String) The Azure Private Link service ID.
 - `id` (String) The ID of this resource.
-- `message` (String) Printable result of the Azure Privatelink request
-- `state` (String) Privatelink resource state
-- `user_subscription_ids` (Set of String) A List of allowed Subscription IDs. Maximum length: `16`.
+- `message` (String) Printable result of the Azure Private Link request.
+- `state` (String) The state of the Private Link resource.
+- `user_subscription_ids` (Set of String) A list of allowed subscription IDs. Maximum length: `16`.

docs/data-sources/azure_vpc_peering_connection.md

@@ -3,30 +3,41 @@
 page_title: "aiven_azure_vpc_peering_connection Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Azure VPC Peering Connection data source provides information about the existing Aiven VPC Peering Connection.
+  Gets information about about an AWS VPC peering connection.
 ---
 
 # aiven_azure_vpc_peering_connection (Data Source)
 
-The Azure VPC Peering Connection data source provides information about the existing Aiven VPC Peering Connection.
+Gets information about about an AWS VPC peering connection.
 
+## Example Usage
 
+```terraform
+data "aiven_azure_vpc_peering_connection" "azure_to_aiven_peering" {
+  vpc_id                = aiven_project_vpc.example_vpc.id
+  azure_subscription_id = "00000000-0000-0000-0000-000000000000"
+  peer_resource_group   = "example-resource-group"
+  vnet_name             = "example-vnet"
+  peer_azure_app_id     = "00000000-0000-0000-0000-000000000000"
+  peer_azure_tenant_id  = "00000000-0000-0000-0000-000000000000"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `azure_subscription_id` (String) Azure Subscription ID. Changing this property forces recreation of the resource.
-- `peer_azure_app_id` (String) Azure app registration id in UUID4 form that is allowed to create a peering to the peer vnet. Changing this property forces recreation of the resource.
-- `peer_azure_tenant_id` (String) Azure tenant id in UUID4 form. Changing this property forces recreation of the resource.
-- `peer_resource_group` (String) Azure resource group name of the peered VPC. Changing this property forces recreation of the resource.
-- `vnet_name` (String) Azure Network name. Changing this property forces recreation of the resource.
-- `vpc_id` (String) The VPC the peering connection belongs to. Changing this property forces recreation of the resource.
+- `azure_subscription_id` (String) The ID of the Azure subscription in UUID4 format. Changing this property forces recreation of the resource.
+- `peer_azure_app_id` (String) The ID of the Azure app that is allowed to create a peering to the Azure Virtual Network (VNet) in UUID4 format. Changing this property forces recreation of the resource.
+- `peer_azure_tenant_id` (String) The Azure tenant ID in UUID4 format. Changing this property forces recreation of the resource.
+- `peer_resource_group` (String) The name of the Azure resource group associated with the VNet. Changing this property forces recreation of the resource.
+- `vnet_name` (String) The name of the Azure VNet. Changing this property forces recreation of the resource.
+- `vpc_id` (String) The ID of the Aiven VPC. Changing this property forces recreation of the resource.
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `peering_connection_id` (String) Cloud provider identifier for the peering connection if available
+- `peering_connection_id` (String) The ID of the cloud provider for the peering connection.
 - `state` (String) State of the peering connection
-- `state_info` (Map of String) State-specific help or error information
+- `state_info` (Map of String) State-specific help or error information.

docs/data-sources/gcp_privatelink.md

@@ -3,14 +3,21 @@
 page_title: "aiven_gcp_privatelink Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The GCP Privatelink resource allows the creation and management of Aiven GCP Privatelink for a services.
+  Gets information about a Google Private Service Connect connection for an Aiven service.
 ---
 
 # aiven_gcp_privatelink (Data Source)
 
-The GCP Privatelink resource allows the creation and management of Aiven GCP Privatelink for a services.
+Gets information about a Google Private Service Connect connection for an Aiven service.
 
+## Example Usage
 
+```terraform
+data "aiven_gcp_privatelink" "main" {
+  project      = aiven_project.example_project.project
+  service_name = aiven_kafka.example_kafka.service_name
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -22,7 +29,7 @@ The GCP Privatelink resource allows the creation and management of Aiven GCP Pri
 
 ### Read-Only
 
-- `google_service_attachment` (String) Privatelink resource Google Service Attachment
+- `google_service_attachment` (String) Google Private Service Connect service attachment.
 - `id` (String) The ID of this resource.
-- `message` (String) Printable result of the GCP Privatelink request
-- `state` (String) Privatelink resource state
+- `message` (String) Printable result of the Google Cloud Private Service Connect request.
+- `state` (String) The state of the Private Service Connect resource.

docs/data-sources/gcp_vpc_peering_connection.md

@@ -25,13 +25,13 @@ data "aiven_gcp_vpc_peering_connection" "foo" {
 
 ### Required
 
-- `gcp_project_id` (String) GCP project ID. Changing this property forces recreation of the resource.
-- `peer_vpc` (String) GCP VPC network name. Changing this property forces recreation of the resource.
+- `gcp_project_id` (String) Google Cloud project ID. Changing this property forces recreation of the resource.
+- `peer_vpc` (String) Google Cloud VPC network name. Changing this property forces recreation of the resource.
 - `vpc_id` (String) The VPC the peering connection belongs to. Changing this property forces recreation of the resource.
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `self_link` (String) Computed GCP network peering link
-- `state` (String) State of the peering connection
-- `state_info` (Map of String) State-specific help or error information
+- `self_link` (String) Computed Google Cloud network peering link.
+- `state` (String) State of the peering connection.
+- `state_info` (Map of String) State-specific help or error information.

docs/data-sources/project_vpc.md

@@ -3,38 +3,33 @@
 page_title: "aiven_project_vpc Data Source - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The Project VPC data source provides information about the existing Aiven Project VPC.
+  Gets information about the VPC for an Aiven project.
 ---
 
 # aiven_project_vpc (Data Source)
 
-The Project VPC data source provides information about the existing Aiven Project VPC.
+Gets information about the VPC for an Aiven project.
 
 ## Example Usage
 
 ```terraform
-data "aiven_project_vpc" "myvpc" {
-  project    = aiven_project.myproject.project
+data "aiven_project_vpc" "example_vpc" {
+  project    = aiven_project.example_project.project
   cloud_name = "google-europe-west1"
 }
-
-# Or
-data "aiven_project_vpc" "myvpc_id" {
-  vpc_id = aiven_project_vpc.vpc.id
-}
 ```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
-- `cloud_name` (String) Defines where the cloud provider and region where the service is hosted in. See the Service resource for additional information.
+- `cloud_name` (String) The cloud provider and region where the service is hosted in the format `CLOUD_PROVIDER-REGION_NAME`. For example, `google-europe-west1` or `aws-us-east-2`.
 - `project` (String) Identifies the project this resource belongs to.
-- `vpc_id` (String) ID of the VPC. This can be used to filter out the specific VPC if there are more than one datasource returned.
+- `vpc_id` (String) The ID of the VPC. This can be used to filter out the other VPCs if there are more than one for the project and cloud.
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `network_cidr` (String) Network address range used by the VPC like 192.168.0.0/24
+- `network_cidr` (String) Network address range used by the VPC. For example, `192.168.0.0/24`.
 - `state` (String) State of the VPC. The possible values are `APPROVED`, `ACTIVE`, `DELETING` and `DELETED`.

docs/resources/aws_privatelink.md

@@ -3,19 +3,19 @@
 page_title: "aiven_aws_privatelink Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The AWS Privatelink resource allows the creation and management of Aiven AWS Privatelink for a services.
+  Creates and manages an AWS PrivateLink for Aiven services https://aiven.io/docs/platform/howto/use-aws-privatelinks in a VPC.
 ---
 
 # aiven_aws_privatelink (Resource)
 
-The AWS Privatelink resource allows the creation and management of Aiven AWS Privatelink for a services.
+Creates and manages an [AWS PrivateLink for Aiven services](https://aiven.io/docs/platform/howto/use-aws-privatelinks) in a VPC.
 
 ## Example Usage
 
 ```terraform
-resource "aiven_aws_privatelink" "foo" {
-  project      = data.aiven_project.foo.project
-  service_name = aiven_kafka.bar.service_name
+resource "aiven_aws_privatelink" "main" {
+  project      = aiven_project.example_project.project
+  service_name = aiven_kafka.example_kafka.service_name
 
   principals = [
     "arn:aws:iam::012345678901:user/mwf"
@@ -28,7 +28,7 @@ resource "aiven_aws_privatelink" "foo" {
 
 ### Required
 
-- `principals` (Set of String) List of allowed principals
+- `principals` (Set of String) List of the ARNs of the AWS accounts or IAM users allowed to connect to the VPC endpoint.
 - `project` (String) Identifies 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) Specifies 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.
 
@@ -38,8 +38,8 @@ resource "aiven_aws_privatelink" "foo" {
 
 ### Read-Only
 
-- `aws_service_id` (String) AWS service ID
-- `aws_service_name` (String) AWS service name
+- `aws_service_id` (String) AWS service ID.
+- `aws_service_name` (String) AWS service name.
 - `id` (String) The ID of this resource.
 
 <a id="nestedblock--timeouts"></a>
@@ -58,5 +58,5 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_aws_privatelink.foo project/service_name
+terraform import aiven_aws_privatelink.main PROJECT/SERVICE_NAME
 ```

docs/resources/aws_vpc_peering_connection.md

@@ -3,20 +3,28 @@
 page_title: "aiven_aws_vpc_peering_connection Resource - terraform-provider-aiven"
 subcategory: ""
 description: |-
-  The AWS VPC Peering Connection resource allows the creation and management of Aiven AWS VPC Peering Connections.
+  Creates and manages an AWS VPC peering connection with an Aiven VPC.
 ---
 
 # aiven_aws_vpc_peering_connection (Resource)
 
-The AWS VPC Peering Connection resource allows the creation and management of Aiven AWS VPC Peering Connections.
+Creates and manages an AWS VPC peering connection with an Aiven VPC.
 
 ## Example Usage
 
 ```terraform
-resource "aiven_aws_vpc_peering_connection" "foo" {
-  vpc_id         = data.aiven_project_vpc.vpc.id
-  aws_account_id = "XXXXX"
-  aws_vpc_id     = "XXXXX"
+resource "aiven_project_vpc" "example_vpc" {
+  project      = aiven_project.example_project.project
+  cloud_name   = "google-europe-west1"
+  network_cidr = "192.168.1.0/24"
+}
+
+
+resource "aiven_aws_vpc_peering_connection" "aws_to_aiven_peering" {
+  vpc_id         = aiven_project_vpc.example_vpc.id
+  aws_account_id = var.aws_id
+  aws_vpc_id     = "vpc-1a2b3c4d5e6f7g8h9"
+  aws_vpc_region = "aws-us-east-2"
 }
 ```
 
@@ -27,19 +35,19 @@ resource "aiven_aws_vpc_peering_connection" "foo" {
 
 - `aws_account_id` (String) AWS account ID. Changing this property forces recreation of the resource.
 - `aws_vpc_id` (String) AWS VPC ID. Changing this property forces recreation of the resource.
-- `aws_vpc_region` (String) AWS region of the peered VPC (if not in the same region as Aiven VPC). Changing this property forces recreation of the resource.
-- `vpc_id` (String) The VPC the peering connection belongs to. Changing this property forces recreation of the resource.
+- `aws_vpc_region` (String) The AWS region of the peered VPC, if different from the Aiven VPC region. Changing this property forces recreation of the resource.
+- `vpc_id` (String) The ID of the Aiven VPC. Changing this property forces recreation of the resource.
 
 ### Optional
 
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 
 ### Read-Only
 
-- `aws_vpc_peering_connection_id` (String) AWS VPC peering connection ID
+- `aws_vpc_peering_connection_id` (String) The ID of the AWS VPC peering connection.
 - `id` (String) The ID of this resource.
-- `state` (String) State of the peering connection
-- `state_info` (Map of String) State-specific help or error information
+- `state` (String) The state of the peering connection.
+- `state_info` (Map of String) State-specific help or error information.
 
 <a id="nestedblock--timeouts"></a>
 ### Nested Schema for `timeouts`
@@ -57,5 +65,5 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-terraform import aiven_aws_vpc_peering_connection.foo project_name/vpc_id/aws_account_id/aws_vpc_id/aws_vpc_region
+terraform import aiven_aws_vpc_peering_connection.aws_to_aiven_peering PROJECT/VPC_ID/AWS_ACCOUNT_ID/AWS_VPC_ID/AWS_VPC_REGION
 ```