feat: Adds port_mapping_enabled attribute to privatelink_endpoint and privatelink_endpoint_service

.changelog/4017.txt

@@ -0,0 +1,15 @@
+```release-note:enhancement
+resource/mongodbatlas_privatelink_endpoint_service: Adds `port_mapping_enabled` attribute
+```
+
+```release-note:enhancement
+resource/mongodbatlas_privatelink_endpoint: Adds `port_mapping_enabled` attribute
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_privatelink_endpoint_service: Adds `port_mapping_enabled` attribute
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_privatelink_endpoint: Adds `port_mapping_enabled` attribute
+```

docs/data-sources/privatelink_endpoint.md

@@ -55,8 +55,9 @@ In addition to all arguments above, the following attributes are exported:
 * `private_endpoints` - All private endpoints that you have added to this Azure Private Link Service.
 * `private_link_service_name` - Name of the Azure Private Link Service that Atlas manages.
 * `private_link_service_resource_id` - Resource ID of the Azure Private Link Service that Atlas manages.
-* `endpoint_group_names` - GCP network endpoint groups corresponding to the Private Service Connect endpoint service.
+* `endpoint_group_names` - For GCP legacy architecture (when `port_mapping_enabled` is not set or `false` on the endpoint resource): A list of the endpoint group names associated with the private endpoint service. For GCP port-based architecture (when `port_mapping_enabled = true` on the endpoint resource): A list of private endpoint names associated with the private endpoint service.
 * `region_name` - GCP region for the Private Service Connect endpoint service.
-* `service_attachment_names` - Unique alphanumeric and special character strings that identify the service attachments associated with the GCP Private Service Connect endpoint service.
+* `service_attachment_names` - For GCP legacy architecture (when `port_mapping_enabled` is not set or `false` on the endpoint resource): A list of service attachments connected to the private endpoint service (one per Atlas node). For GCP port-based architecture (when `port_mapping_enabled = true` on the endpoint resource): A list of one service attachment connected to the private endpoint service.
+* `port_mapping_enabled` - Flag that indicates whether this endpoint service uses GCP port-mapping. When `true`, the endpoint service uses the new port-based architecture (requires 1 endpoint). When `false`, it uses the legacy architecture. Only applicable for GCP provider.
 
 See [MongoDB Atlas API](https://docs.atlas.mongodb.com/reference/api/private-endpoints-service-get-one/) Documentation for more information.

docs/data-sources/privatelink_endpoint_service.md

@@ -33,9 +33,10 @@ resource "mongodbatlas_privatelink_endpoint_service" "test" {
 }
 
 data "mongodbatlas_privatelink_endpoint_service" "test" {
-  project_id            = mongodbatlas_privatelink_endpoint_service.test.project_id
-  private_link_id       = mongodbatlas_privatelink_endpoint_service.test.private_link_id
-  interface_endpoint_id = mongodbatlas_privatelink_endpoint_service.test.interface_endpoint_id
+  project_id          = mongodbatlas_privatelink_endpoint_service.test.project_id
+  private_link_id     = mongodbatlas_privatelink_endpoint_service.test.private_link_id
+  endpoint_service_id = mongodbatlas_privatelink_endpoint_service.test.endpoint_service_id
+  provider_name       = "AWS"
 }
 ```
 
@@ -71,9 +72,36 @@ resource "mongodbatlas_privatelink_endpoint_service" "test" {
 }
 
 data "mongodbatlas_privatelink_endpoint_service" "test" {
-  project_id            = mongodbatlas_privatelink_endpoint_service.test.project_id
-  private_link_id       = mongodbatlas_privatelink_endpoint_service.test.private_link_id
-  interface_endpoint_id = mongodbatlas_privatelink_endpoint_service.test.interface_endpoint_id
+  project_id          = mongodbatlas_privatelink_endpoint_service.test.project_id
+  private_link_id     = mongodbatlas_privatelink_endpoint_service.test.private_link_id
+  endpoint_service_id = mongodbatlas_privatelink_endpoint_service.test.endpoint_service_id
+  provider_name       = "AZURE"
+}
+```
+
+## Example with GCP (Legacy Architecture)
+
+```terraform
+data "mongodbatlas_privatelink_endpoint_service" "test" {
+  project_id          = mongodbatlas_privatelink_endpoint_service.test.project_id
+  private_link_id     = mongodbatlas_privatelink_endpoint_service.test.private_link_id
+  endpoint_service_id = mongodbatlas_privatelink_endpoint_service.test.endpoint_service_id
+  provider_name       = "GCP"
+}
+```
+
+## Example with GCP (Port-Based Architecture)
+
+The new port-based architecture uses port mapping to reduce resource provisioning. Unlike the legacy architecture that requires dedicated resources for each Atlas node, the new design uses a single set of resources to support up to 1000 nodes through a port mapping network endpoint group (NEG), enabling direct targeting of specific nodes using only one customer IP address. Enable it by setting `port_mapping_enabled = true` on the endpoint resource.
+
+**Important:** For the new port-based architecture, use `endpoint_service_id` (the forwarding rule name) and `private_endpoint_ip_address` (the IP address). The `endpoints` list is no longer used for the new architecture.
+
+```terraform
+data "mongodbatlas_privatelink_endpoint_service" "test" {
+  project_id          = mongodbatlas_privatelink_endpoint_service.test.project_id
+  private_link_id     = mongodbatlas_privatelink_endpoint_service.test.private_link_id
+  endpoint_service_id = mongodbatlas_privatelink_endpoint_service.test.endpoint_service_id
+  provider_name       = "GCP"
 }
 ```
 
@@ -84,8 +112,8 @@ data "mongodbatlas_privatelink_endpoint_service" "test" {
 
 * `project_id` - (Required) Unique identifier for the project.
 * `private_link_id` - (Required) Unique identifier of the private endpoint service for which you want to retrieve a private endpoint.
-* `endpoint_service_id` - (Required) Unique identifier of the `AWS` or `AZURE` or `GCP` resource.
-* `provider_name` - (Required) Cloud provider for which you want to create a private endpoint. Atlas accepts `AWS` or `AZURE` or `GCP`.
+* `endpoint_service_id` - (Required) Unique identifier of the interface endpoint you created in your VPC with the `AWS`, `AZURE`, or `GCP` resource. For GCP legacy architecture, this can be any identifier string. For GCP port-based architecture (when `port_mapping_enabled = true` on the endpoint resource), this is the forwarding rule name.
+* `provider_name` - (Required) Cloud provider for which you want to retrieve a private endpoint. Atlas accepts `AWS`, `AZURE` or `GCP`.
 
 ## Attributes Reference
 
@@ -94,7 +122,7 @@ In addition to all arguments above, the following attributes are exported:
 * `id` - The Terraform's unique identifier used internally for state management.
 * `interface_endpoint_id` - Unique identifier of the interface endpoint.
 * `private_endpoint_connection_name` - Name of the connection for this private endpoint that Atlas generates.
-* `private_endpoint_ip_address` - Private IP address of the private endpoint network interface.
+* `private_endpoint_ip_address` - Private IP address of the private endpoint network interface. For GCP port-based architecture (when `port_mapping_enabled = true` on the endpoint resource), this is the IP address of the forwarding rule. For GCP legacy architecture, this is not used.
 * `private_endpoint_resource_id` - Unique identifier of the private endpoint.
 * `delete_requested` - Indicates if Atlas received a request to remove the interface endpoint from the private endpoint connection.
 * `error_message` - Error message pertaining to the interface endpoint. Returns null if there are no errors.
@@ -118,9 +146,11 @@ In addition to all arguments above, the following attributes are exported:
   * `AVAILABLE` - Atlas approved the connection to your private endpoint.
   * `FAILED` - Atlas failed to accept the connection your private endpoint.
   * `DELETING` - Atlas is removing the connection to your private endpoint from the Private Link service.
-* `endpoints` - Collection of individual private endpoints that comprise your network endpoint group.
+* `gcp_endpoint_status` - Status of the individual GCP endpoint. Only populated for port-based architecture (when `port_mapping_enabled = true`on the endpoint resource).  Returns one of the following values: `INITIATING`, `AVAILABLE`, `FAILED`, `DELETING`.
+* `endpoints` - Collection of individual private endpoints that comprise your network endpoint group. Only populated for legacy GCP architecture.
   * `endpoint_name` - Forwarding rule that corresponds to the endpoint you created in GCP.
   * `ip_address` - Private IP address of the network endpoint group you created in GCP.
   * `status` - Status of the endpoint. Atlas returns one of the [values shown above](https://docs.atlas.mongodb.com/reference/api/private-endpoints-endpoint-create-one/#std-label-ref-status-field).
+* `port_mapping_enabled` - Flag that indicates whether this endpoint service uses GCP port-mapping. This is a read-only attribute that reflects the architecture type. When `true`, the endpoint service uses the new port-based architecture (requires 1 endpoint). When `false`, it uses the legacy architecture. Only applicable for GCP provider.
 
 See [MongoDB Atlas API](https://docs.atlas.mongodb.com/reference/api/private-endpoints-endpoint-get-one/) Documentation for more information.

docs/resources/privatelink_endpoint.md

@@ -19,6 +19,8 @@ ensure that you review the [Multi-Region Private Endpoints](https://www.mongodb.
 
 -> **NOTE:** A network container is created for a private endpoint to reside in if one does not yet exist in the project.  
 
+~> **IMPORTANT:** For GCP Private Service Connect, MongoDB encourages customers to use the port-based architecture by setting `port_mapping_enabled = true`. The port-based architecture simplifies setup by requiring only 1 endpoint instead of multiple endpoints required by the legacy architecture, and uses a single set of resources to support up to 1000 nodes. For migration guidance, see the [GCP Private Link Port Mapping Migration Guide](../guides/gcp-privatelink-port-mapping-migration.md).
+
 ## Example Usage
 
 ```terraform
@@ -37,7 +39,8 @@ resource "mongodbatlas_privatelink_endpoint" "test" {
 ### Further Examples
 - [AWS PrivateLink Endpoint](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.2.0/examples/mongodbatlas_privatelink_endpoint/aws)
 - [Azure PrivateLink Endpoint](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.2.0/examples/mongodbatlas_privatelink_endpoint/azure)
-- [GCP Private Service Connect Endpoint](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.2.0/examples/mongodbatlas_privatelink_endpoint/gcp)
+- [GCP Private Service Connect Endpoint (Legacy Architecture)](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.2.0/examples/mongodbatlas_privatelink_endpoint/gcp)
+- [GCP Private Service Connect Endpoint (Port-Based Architecture)](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.2.0/examples/mongodbatlas_privatelink_endpoint/gcp-port-based)
 
 ## Argument Reference
 
@@ -47,6 +50,7 @@ resource "mongodbatlas_privatelink_endpoint" "test" {
 Accepted values are: [AWS regions](https://docs.atlas.mongodb.com/reference/amazon-aws/#amazon-aws), [AZURE regions](https://docs.atlas.mongodb.com/reference/microsoft-azure/#microsoft-azure) and [GCP regions](https://docs.atlas.mongodb.com/reference/google-gcp/#std-label-google-gcp)
 * `timeouts`- (Optional) The duration of time to wait for Private Endpoint to be created or deleted. The timeout value is defined by a signed sequence of decimal numbers with a time unit suffix such as: `1h45m`, `300s`, `10m`, etc. The valid time units are:  `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. The default timeout for Private Endpoint create & delete is `1h`. Learn more about timeouts [here](https://www.terraform.io/plugin/sdkv2/resources/retries-and-customizable-timeouts).
 * `delete_on_create_timeout`- (Optional) Indicates whether to delete the resource being created if a timeout is reached when waiting for completion. When set to `true` and timeout occurs, it triggers the deletion and returns immediately without waiting for deletion to complete. When set to `false`, the timeout will not trigger resource deletion. If you suspect a transient error when the value is `true`, wait before retrying to allow resource deletion to finish. Default is `true`.
+* `port_mapping_enabled` - (Optional) Flag that indicates whether this endpoint service uses GCP port-mapping. When set to `true`, enables the new port-based architecture, which requires only 1 endpoint. Defaults to `false`. Only applicable for GCP provider.
 
 ## Attributes Reference
 
@@ -62,10 +66,10 @@ AZURE:
   * `private_endpoints` - All private endpoints that you have added to this Azure Private Link Service.
   * `private_link_service_name` - Name of the Azure Private Link Service that Atlas manages.
 GCP: 
-  * `endpoint_group_names` - GCP network endpoint groups corresponding to the Private Service Connect endpoint service.
+  * `endpoint_group_names` - For GCP legacy architecture (when `port_mapping_enabled` is not set or `false` on the endpoint resource): A list of the endpoint group names associated with the private endpoint service. For GCP port-based architecture (when `port_mapping_enabled = true` on the endpoint resource): A list of private endpoint names associated with the private endpoint service.
   * `region_name` - GCP region for the Private Service Connect endpoint service.
-  * `service_attachment_names` - Unique alphanumeric and special character strings that identify the service attachments associated with the GCP Private Service Connect endpoint service. Returns an empty list while Atlas creates the service attachments.
-* `status` - Status of the AWS PrivateLink connection or Status of the Azure Private Link Service. Atlas returns one of the following values:
+  * `service_attachment_names` - For GCP legacy architecture (when `port_mapping_enabled` is not set or `false` on the endpoint resource): A list of service attachments connected to the private endpoint service (one per Atlas node). For GCP port-based architecture (when `port_mapping_enabled = true` on the endpoint resource): A list of one service attachment connected to the private endpoint service. Returns an empty list while Atlas creates the service attachments.
+* `status` - Status of the AWS PrivateLink connection or Status of the Azure/GCP Private Link Service. Atlas returns one of the following values:
   AWS:
     * `AVAILABLE` 	Atlas is creating the network load balancer and VPC endpoint service.
     * `WAITING_FOR_USER` The Atlas network load balancer and VPC endpoint service are created and ready to receive connection requests. When you receive this status, create an interface endpoint to continue configuring the AWS PrivateLink connection.