doc: The commit adds Azure Streams PrivateLink documentation and examples (#3299)

Author: jwongmongodb

docs/data-sources/stream_privatelink_endpoint.md

@@ -213,23 +213,21 @@ output "privatelink_endpoint_id" {
 ### Required
 
 - `id` (String) The ID of the Private Link connection.
-- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.
-
-**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
+- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.<br>**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
 
 ### Read-Only
 
-- `arn` (String) Amazon Resource Name (ARN).
-- `dns_domain` (String) Domain name of Privatelink connected cluster.
-- `dns_sub_domain` (List of String) Sub-Domain name of Confluent cluster. These are typically your availability zones.
+- `arn` (String) Amazon Resource Name (ARN). Required for AWS Provider and MSK vendor.
+- `dns_domain` (String) The domain hostname. Required for the following provider and vendor combinations:<br>- AWS provider with CONFLUENT vendor.<br>- AZURE provider with EVENTHUB or CONFLUENT vendor.
+- `dns_sub_domain` (List of String) Sub-Domain name of Confluent cluster. These are typically your availability zones. Required for AWS Provider and CONFLUENT vendor. If your AWS CONFLUENT cluster doesn't use subdomains, you must set this to the empty array [].
 - `error_message` (String) Error message if the connection is in a failed state.
 - `interface_endpoint_id` (String) Interface endpoint ID that is created from the specified service endpoint ID.
 - `interface_endpoint_name` (String) Name of interface endpoint that is created from the specified service endpoint ID.
 - `provider_account_id` (String) Account ID from the cloud provider.
-- `provider_name` (String) Provider where the Kafka cluster is deployed.
-- `region` (String) When the vendor is `CONFLUENT`, this is the domain name of Confluent cluster. When the vendor is `MSK`, this is computed by the API from the provided `arn`.
-- `service_endpoint_id` (String) Service Endpoint ID.
+- `provider_name` (String) Provider where the Kafka cluster is deployed. Valid values are AWS and AZURE.
+- `region` (String) The region of the Provider’s cluster. See [AZURE](https://www.mongodb.com/docs/atlas/reference/microsoft-azure/#stream-processing-instances) and [AWS](https://www.mongodb.com/docs/atlas/reference/amazon-aws/#stream-processing-instances) supported regions. When the vendor is `CONFLUENT`, this is the domain name of Confluent cluster. When the vendor is `MSK`, this is computed by the API from the provided `arn`.
+- `service_endpoint_id` (String) For AZURE EVENTHUB, this is the [namespace endpoint ID](https://learn.microsoft.com/en-us/rest/api/eventhub/namespaces/get). For AWS CONFLUENT cluster, this is the [VPC Endpoint service name](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html).
 - `state` (String) Status of the connection.
-- `vendor` (String) Vendor who manages the Kafka cluster.
+- `vendor` (String) Vendor that manages the Kafka cluster. The following are the vendor values per provider:<br>- MSK and CONFLUENT for the AWS provider.<br>- EVENTHUB and CONFLUENT for the AZURE provider.
 
 For more information see: [MongoDB Atlas API - Streams Privatelink](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Streams/operation/createPrivateLinkConnection) Documentation.

docs/data-sources/stream_privatelink_endpoints.md

@@ -212,9 +212,7 @@ output "privatelink_endpoint_id" {
 
 ### Required
 
-- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.
-
-**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
+- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.<br>**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
 
 ### Read-Only
 
@@ -225,21 +223,19 @@ output "privatelink_endpoint_id" {
 
 Read-Only:
 
-- `arn` (String) Amazon Resource Name (ARN).
-- `dns_domain` (String) Domain name of Privatelink connected cluster.
-- `dns_sub_domain` (List of String) Sub-Domain name of Confluent cluster. These are typically your availability zones.
+- `arn` (String) Amazon Resource Name (ARN). Required for AWS Provider and MSK vendor.
+- `dns_domain` (String) The domain hostname. Required for the following provider and vendor combinations:<br>- AWS provider with CONFLUENT vendor.<br>- AZURE provider with EVENTHUB or CONFLUENT vendor.
+- `dns_sub_domain` (List of String) Sub-Domain name of Confluent cluster. These are typically your availability zones. Required for AWS Provider and CONFLUENT vendor. If your AWS CONFLUENT cluster doesn't use subdomains, you must set this to the empty array [].
 - `error_message` (String) Error message if the connection is in a failed state.
 - `id` (String) The ID of the Private Link connection.
 - `interface_endpoint_id` (String) Interface endpoint ID that is created from the specified service endpoint ID.
 - `interface_endpoint_name` (String) Name of interface endpoint that is created from the specified service endpoint ID.
-- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.
-
-**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
+- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.<br>**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
 - `provider_account_id` (String) Account ID from the cloud provider.
-- `provider_name` (String) Provider where the Kafka cluster is deployed.
-- `region` (String) When the vendor is `CONFLUENT`, this is the domain name of Confluent cluster. When the vendor is `MSK`, this is computed by the API from the provided `arn`.
-- `service_endpoint_id` (String) Service Endpoint ID.
+- `provider_name` (String) Provider where the Kafka cluster is deployed. Valid values are AWS and AZURE.
+- `region` (String) The region of the Provider’s cluster. See [AZURE](https://www.mongodb.com/docs/atlas/reference/microsoft-azure/#stream-processing-instances) and [AWS](https://www.mongodb.com/docs/atlas/reference/amazon-aws/#stream-processing-instances) supported regions. When the vendor is `CONFLUENT`, this is the domain name of Confluent cluster. When the vendor is `MSK`, this is computed by the API from the provided `arn`.
+- `service_endpoint_id` (String) For AZURE EVENTHUB, this is the [namespace endpoint ID](https://learn.microsoft.com/en-us/rest/api/eventhub/namespaces/get). For AWS CONFLUENT cluster, this is the [VPC Endpoint service name](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html).
 - `state` (String) Status of the connection.
-- `vendor` (String) Vendor who manages the Kafka cluster.
+- `vendor` (String) Vendor that manages the Kafka cluster. The following are the vendor values per provider:<br>- MSK and CONFLUENT for the AWS provider.<br>- EVENTHUB and CONFLUENT for the AZURE provider.
 
 For more information see: [MongoDB Atlas API - Streams Privatelink](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Streams/operation/createPrivateLinkConnection) Documentation.

docs/resources/stream_privatelink_endpoint.md

@@ -212,19 +212,17 @@ output "privatelink_endpoint_id" {
 
 ### Required
 
-- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.
-
-**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
-- `provider_name` (String) Provider where the Kafka cluster is deployed.
-- `vendor` (String) Vendor who manages the Kafka cluster.
+- `project_id` (String) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access.<br>**NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group or project id remains the same. The resource and corresponding endpoints use the term groups.
+- `provider_name` (String) Provider where the Kafka cluster is deployed. Valid values are AWS and AZURE.
+- `vendor` (String) Vendor that manages the Kafka cluster. The following are the vendor values per provider:<br>- MSK and CONFLUENT for the AWS provider.<br>- EVENTHUB and CONFLUENT for the AZURE provider.
 
 ### Optional
 
-- `arn` (String) Amazon Resource Name (ARN).
-- `dns_domain` (String) Domain name of Privatelink connected cluster.
-- `dns_sub_domain` (List of String) Sub-Domain name of Confluent cluster. These are typically your availability zones.
-- `region` (String) When the vendor is `CONFLUENT`, this is the domain name of Confluent cluster. When the vendor is `MSK`, this is computed by the API from the provided `arn`.
-- `service_endpoint_id` (String) Service Endpoint ID.
+- `arn` (String) Amazon Resource Name (ARN). Required for AWS Provider and MSK vendor.
+- `dns_domain` (String) The domain hostname. Required for the following provider and vendor combinations:<br>- AWS provider with CONFLUENT vendor.<br>- AZURE provider with EVENTHUB or CONFLUENT vendor.
+- `dns_sub_domain` (List of String) Sub-Domain name of Confluent cluster. These are typically your availability zones. Required for AWS Provider and CONFLUENT vendor. If your AWS CONFLUENT cluster doesn't use subdomains, you must set this to the empty array [].
+- `region` (String) The region of the Provider’s cluster. See [AZURE](https://www.mongodb.com/docs/atlas/reference/microsoft-azure/#stream-processing-instances) and [AWS](https://www.mongodb.com/docs/atlas/reference/amazon-aws/#stream-processing-instances) supported regions. When the vendor is `CONFLUENT`, this is the domain name of Confluent cluster. When the vendor is `MSK`, this is computed by the API from the provided `arn`.
+- `service_endpoint_id` (String) For AZURE EVENTHUB, this is the [namespace endpoint ID](https://learn.microsoft.com/en-us/rest/api/eventhub/namespaces/get). For AWS CONFLUENT cluster, this is the [VPC Endpoint service name](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html).
 
 ### Read-Only
 

examples/mongodbatlas_stream_privatelink_endpoint/azure/README.md

@@ -0,0 +1,70 @@
+# Example - Microsoft Azure and MongoDB Atlas Streams Private Endpoint
+
+This example shows how to use Azure PrivateLink Endpoints with EventHub for Atlas Streams PrivateLink.
+
+You must set the following variables for Atlas in main.tf:
+
+- `public_key`: Public API key to authenticate to Atlas
+- `private_key`: Private API key to authenticate to Atlas
+- `project_id`: Unique 24-hexadecimal digit string that identifies your atlas project
+- `atlas_region`: Atlas region where you want to create the Streams PrivateLink resources. To learn more, see `Atlas Region` column in https://www.mongodb.com/docs/atlas/reference/microsoft-azure/#stream-processing-instances. 
+
+- Additional required fields in main.tf:
+- `dns_domain`: Hostname of the Event Hub Namespace in Azure, which is the dns_domain.
+- `service_endpoint_id`: Service Endpoint ID for the EventHub Namespace. You can find this in the Azure portal under the EventHub Namespace properties. It typically looks like `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}`.
+
+The following setup is for Azure PrivateLink with EventHub example in azure.tf. To learn more, see documentation https://learn.microsoft.com/en-us/azure/event-hubs/private-link-service#add-a-private-endpoint-using-azure-portal
+
+- `azure_region`: The Azure region where you want to create the Azure PrivateLink resources. `Azure Region` column in https://www.mongodb.com/docs/atlas/reference/microsoft-azure/#stream-processing-instances.
+- `azure_resource_group`: The name of the Azure Resource Group where you want to create the PrivateLink resources. 
+- `vnet_name`: The name of the Azure Virtual Network (VNet) where you want to create the PrivateLink resources.
+- `subnet_name`: The name of the subnet within the VNet where you want to create the PrivateLink resources. 
+- `eventhub_namespace_name`: The name of the Azure EventHub Namespace that you want to use for the PrivateLink connection. Must be globally unique. 
+- `eventhub_name`: The name of the Azure EventHub that you want to use for the PrivateLink connection. 
+- `vnet_address_space`: The address space for the Azure Virtual Network. 
+- `subnet_address_prefix`: The address prefix for the Azure Subnet.
+
+## Usage
+
+**1\. Ensure that your Azure credentials are set up.**
+
+1. Install the Azure CLI by following the steps from the [official Azure documentation](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).
+2. Run the command `az login` and authenticate using the default browser.
+3. Once authenticated, Azure returns the following user details:
+
+**2\. Set up your MongoDB Atlas API keys.**
+1. Log in to your MongoDB Atlas account.
+2. Navigate to the "Project Access" section of your project.
+3. Create a new API key with the necessary permissions (Project Owner or similar).
+4. Copy the Public and Private keys to use with the Terraform configuration.
+
+**3\. Create a terraform.tfvars file.**
+1. Create a file named `terraform.tfvars` in the same directory as your `main.tf`.
+2. Defining the required variables in the `terraform.tfvars` file.
+
+**4\. Optional: Create the Azure resources with EventHub.**
+1. If you don't have an existing Azure EventHub Namespace and EventHub, you can create them using the provided `azure.tf` file.
+
+**5\. Initialize Terraform.**
+1. Run the following command to initialize Terraform and download the required providers:
+   ```bash
+   terraform init
+   ```
+**6\. Plan the Terraform deployment.**
+1. Run the following command to see the execution plan and verify the resources that will be created:
+   ```bash
+   terraform plan
+   ```
+   
+**7\. Apply the Terraform configuration.**
+1. If the plan looks good, run the following command to create the resources:
+   ```bash
+   terraform apply
+   ```
+
+**8\. Destroy the Terraform resources.**
+1. When you no longer need the resources, you can destroy them by running the following command:
+   ```bash
+   terraform destroy
+   ```
+

examples/mongodbatlas_stream_privatelink_endpoint/azure/azure.tf

@@ -0,0 +1,69 @@
+resource "azurerm_resource_group" "rg" {
+  name     = var.azure_resource_group
+  location = var.azure_region
+}
+
+resource "azurerm_virtual_network" "vnet" {
+  name                = var.vnet_name
+  address_space       = var.vnet_address_space
+  location            = azurerm_resource_group.rg.location
+  resource_group_name = azurerm_resource_group.rg.name
+}
+
+resource "azurerm_subnet" "subnet" {
+  name                 = var.subnet_name
+  resource_group_name  = azurerm_resource_group.rg.name
+  virtual_network_name = azurerm_virtual_network.vnet.name
+  address_prefixes     = var.subnet_address_prefix
+}
+
+resource "azurerm_eventhub_namespace" "eventhub_ns" {
+  name                = var.eventhub_namespace_name
+  location            = azurerm_resource_group.rg.location
+  resource_group_name = azurerm_resource_group.rg.name
+  sku                 = "Standard" # Minimum SKU for Private Link
+  capacity            = 1
+}
+
+resource "azurerm_eventhub" "eventhub" {
+  name                = var.eventhub_name
+  namespace_name      = azurerm_eventhub_namespace.eventhub_ns.name
+  resource_group_name = azurerm_resource_group.rg.name
+  partition_count     = 1
+  message_retention   = 1
+}
+
+resource "azurerm_private_dns_zone" "dns_zone" {
+  name                = "privatelink.servicebus.windows.net" # should always be "privatelink.servicebus.windows.net"
+  resource_group_name = azurerm_resource_group.rg.name
+}
+
+resource "azurerm_private_dns_zone_virtual_network_link" "dns_zone_link" {
+  name                  = "${var.vnet_name}-dns-link"
+  resource_group_name   = azurerm_resource_group.rg.name
+  private_dns_zone_name = azurerm_private_dns_zone.dns_zone.name
+  virtual_network_id    = azurerm_virtual_network.vnet.id
+}
+
+resource "azurerm_private_endpoint" "eventhub_endpoint" {
+  name                = "pe-${var.eventhub_namespace_name}"
+  location            = azurerm_resource_group.rg.location
+  resource_group_name = azurerm_resource_group.rg.name
+  subnet_id           = azurerm_subnet.subnet.id
+
+  private_service_connection {
+    name                           = "psc-${var.eventhub_namespace_name}"
+    is_manual_connection           = false
+    private_connection_resource_id = azurerm_eventhub_namespace.eventhub_ns.id
+    subresource_names              = ["namespace"]
+  }
+
+  private_dns_zone_group {
+    name                 = "default-dns-group"
+    private_dns_zone_ids = [azurerm_private_dns_zone.dns_zone.id]
+  }
+
+  depends_on = [azurerm_private_dns_zone_virtual_network_link.dns_zone_link]
+}
+
+data "azurerm_client_config" "current" {}

examples/mongodbatlas_stream_privatelink_endpoint/azure/main.tf

@@ -0,0 +1,11 @@
+resource "mongodbatlas_stream_privatelink_endpoint" "test_stream_privatelink" {
+  project_id = var.project_id
+  # dns_domain comes from the hostname of the Event Hub Namespace in Azure.
+  dns_domain    = "${var.eventhub_namespace_name}.servicebus.windows.net"
+  provider_name = "AZURE"
+  region        = var.atlas_region
+  vendor        = "EVENTHUB"
+  # The service endpoint ID is generated as follows: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventHub/namespaces/{namespaceName}
+  service_endpoint_id = "/subscriptions/${data.azurerm_client_config.current.subscription_id}/resourceGroups/${var.azure_resource_group}/providers/Microsoft.EventHub/namespaces/${var.eventhub_namespace_name}"
+  depends_on          = [azurerm_private_endpoint.eventhub_endpoint]
+}

examples/mongodbatlas_stream_privatelink_endpoint/azure/providers.tf

@@ -0,0 +1,9 @@
+provider "azurerm" {
+  features {}
+  # assumes Azure CLI login ('az login') or other standard auth
+}
+
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}