docs: add docs for private endpoint connections (#197)

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.1] - 2024-04-04
+
+## Added
+
+- Added `private_endpoint_connection` examples for AWS, Azure, GCP.
+
 ### Fixed
 
 - Added any missing examples for data sources, resources and imports.

docs/resources/private_endpoint_connection.md

@@ -3,19 +3,82 @@
 page_title: "cockroach_private_endpoint_connection Resource - terraform-provider-cockroach"
 subcategory: ""
 description: |-
-  Private Endpoint Connection.
+  Private endpoint connections allow customer applications to connect to a CockroachDB Cloud cluster without traversing the public internet. All application-database traffic remains within the cloud-provider network.
 ---
 
 # cockroach_private_endpoint_connection (Resource)
 
-Private Endpoint Connection.
+Private endpoint connections allow customer applications to connect to a CockroachDB Cloud cluster without traversing the public internet. All application-database traffic remains within the cloud-provider network.
 
 ## Example Usage
 
 ```terraform
-resource "cockroach_private_endpoint_connection" "serverless" {
-  cluster_id  = cockroach_cluster.serverless.id
-  endpoint_id = "endpoint-id"
+## Example with AWS PrivateLink
+
+# Enable the PrivateLink service on the CockroachDB Cloud cluster.
+resource "cockroach_private_endpoint_services" "services" {
+  cluster_id = cockroach_cluster.my_cluster.id
+}
+
+# Create a PrivateLink endpoint and associate it with the PrivateLink Service. 
+resource "aws_vpc_endpoint" "my_endpoint" {
+  vpc_id             = "vpc-7fc0a543"
+  service_name       = cockroach_private_endpoint_services.services.name
+  vpc_endpoint_type  = "Interface"
+  subnet_ids         = ["subnet-de0406d2"]
+  security_group_ids = ["sg-3f238186"]
+}
+
+# Establish the connection between the endpoint and the service.
+resource "cockroach_private_endpoint_connection" "connection" {
+  cluster_id  = cockroach_cluster.my_cluster.id
+  endpoint_id = aws_vpc_endpoint.my_endpoint.id
+}
+
+## Example with Azure Private Link
+
+# Enable the Private Link service on the CockroachDB Cloud cluster.
+resource "cockroach_private_endpoint_services" "services" {
+  cluster_id = cockroach_cluster.my_cluster.id
+}
+
+# Create a private link endpoint and associate it with the Private Link Service. 
+resource "azurerm_private_endpoint" "my_endpoint" {
+  name                = "my_endpoint"
+  location            = var.location
+  resource_group_name = var.resource_group_name
+  subnet_id           = azurerm_subnet.my_subnet.id
+  private_service_connection {
+    name                           = cockroach_private_endpoint_connection.services[0].name
+    private_connection_resource_id = cockroach_private_endpoint_connection.services[0].endpoint_service_id
+    is_manual_connection           = true
+    request_message                = "Azure Private Link test"
+  }
+}
+
+# Establish a connection between the endpoint and the service.
+resource "cockroach_private_endpoint_connection" "connection" {
+  cluster_id  = cockroach_cluster.my_cluster.id
+  endpoint_id = azurerm_private_endpoint.my_endpoint.id
+}
+
+## Example with GCP Private Service Connect
+
+# Enable the Private Service Connect services on the CockroachDB Cloud cluster.
+resource "cockroach_private_endpoint_services" "services" {
+  cluster_id = cockroach_cluster.my_cluster.id
+}
+
+# Create the GCP Private Service Connect endpoint using the GCP API or the GCP
+# Console. You will need the service id to create the endpoint. You can get the
+# service information by running `terraform show` and noting
+# `cockroach_private_endpoint_connection.services[*].name`,
+# `cockroach_private_endpoint_connection.services[*].endpoint_service_id`
+
+# Establish a connection between the endpoint and the service.
+resource "cockroach_private_endpoint_connection" "connection" {
+  cluster_id  = cockroach_cluster.my_cluster.id
+  endpoint_id = "6133183410995353"
 }
 ```
 

examples/resources/cockroach_private_endpoint_connection/resource.tf

@@ -1,4 +1,67 @@
-resource "cockroach_private_endpoint_connection" "serverless" {
-  cluster_id  = cockroach_cluster.serverless.id
-  endpoint_id = "endpoint-id"
+## Example with AWS PrivateLink
+
+# Enable the PrivateLink service on the CockroachDB Cloud cluster.
+resource "cockroach_private_endpoint_services" "services" {
+  cluster_id = cockroach_cluster.my_cluster.id
+}
+
+# Create a PrivateLink endpoint and associate it with the PrivateLink Service. 
+resource "aws_vpc_endpoint" "my_endpoint" {
+  vpc_id             = "vpc-7fc0a543"
+  service_name       = cockroach_private_endpoint_services.services.name
+  vpc_endpoint_type  = "Interface"
+  subnet_ids         = ["subnet-de0406d2"]
+  security_group_ids = ["sg-3f238186"]
+}
+
+# Establish the connection between the endpoint and the service.
+resource "cockroach_private_endpoint_connection" "connection" {
+  cluster_id  = cockroach_cluster.my_cluster.id
+  endpoint_id = aws_vpc_endpoint.my_endpoint.id
+}
+
+## Example with Azure Private Link
+
+# Enable the Private Link service on the CockroachDB Cloud cluster.
+resource "cockroach_private_endpoint_services" "services" {
+  cluster_id = cockroach_cluster.my_cluster.id
+}
+
+# Create a private link endpoint and associate it with the Private Link Service. 
+resource "azurerm_private_endpoint" "my_endpoint" {
+  name                = "my_endpoint"
+  location            = var.location
+  resource_group_name = var.resource_group_name
+  subnet_id           = azurerm_subnet.my_subnet.id
+  private_service_connection {
+    name                           = cockroach_private_endpoint_connection.services[0].name
+    private_connection_resource_id = cockroach_private_endpoint_connection.services[0].endpoint_service_id
+    is_manual_connection           = true
+    request_message                = "Azure Private Link test"
+  }
+}
+
+# Establish a connection between the endpoint and the service.
+resource "cockroach_private_endpoint_connection" "connection" {
+  cluster_id  = cockroach_cluster.my_cluster.id
+  endpoint_id = azurerm_private_endpoint.my_endpoint.id
+}
+
+## Example with GCP Private Service Connect
+
+# Enable the Private Service Connect services on the CockroachDB Cloud cluster.
+resource "cockroach_private_endpoint_services" "services" {
+  cluster_id = cockroach_cluster.my_cluster.id
+}
+
+# Create the GCP Private Service Connect endpoint using the GCP API or the GCP
+# Console. You will need the service id to create the endpoint. You can get the
+# service information by running `terraform show` and noting
+# `cockroach_private_endpoint_connection.services[*].name`,
+# `cockroach_private_endpoint_connection.services[*].endpoint_service_id`
+
+# Establish a connection between the endpoint and the service.
+resource "cockroach_private_endpoint_connection" "connection" {
+  cluster_id  = cockroach_cluster.my_cluster.id
+  endpoint_id = "6133183410995353"
 }

internal/provider/private_endpoint_connection_resource.go

@@ -48,7 +48,7 @@ func (r *privateEndpointConnectionResource) Schema(
 	_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse,
 ) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "Private Endpoint Connection.",
+		MarkdownDescription: "Private endpoint connections allow customer applications to connect to a CockroachDB Cloud cluster without traversing the public internet. All application-database traffic remains within the cloud-provider network.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Computed:            true,