Mengonfigurasi Azure Private Link untuk akun Azure Cosmos DB

  • Artikel

BERLAKU UNTUK: Nosql MongoDB Cassandra Gremlin Meja

Dengan menggunakan Azure Private Link, Anda dapat tersambung ke akun Azure Cosmos DB melalui titik akhir privat. Titik akhir privat adalah sekumpulan alamat IP pribadi dalam subnet dalam jaringan virtual Anda. Anda kemudian dapat membatasi akses ke akun Azure Cosmos DB melalui alamat IP privat. Ketika Private Link dikombinasikan dengan kebijakan NSG yang ketat, ini membantu mengurangi risiko penyelundupan data. Untuk mempelajari selengkapnya tentang titik akhir privat, lihat Apa itu Azure Private Link?

Catatan

Private Link tidak mencegah titik akhir Azure Cosmos DB Anda diselesaikan oleh DNS publik. Pemfilteran permintaan masuk terjadi pada tingkat aplikasi, bukan tingkat transportasi atau jaringan.

Private Link memungkinkan pengguna untuk mengakses akun Azure Cosmos DB dari dalam jaringan virtual atau dari jaringan virtual yang di-peering. Sumber daya yang dipetakan ke Private Link juga dapat diakses di tempat melalui peering pribadi melalui VPN atau Azure ExpressRoute.

Anda dapat menyambungkan ke akun Azure Cosmos DB yang dikonfigurasi dengan Private Link dengan menggunakan metode persetujuan otomatis atau manual. Untuk mempelajari selengkapnya, lihat bagian alur kerja persetujuan dari dokumentasi Private Link.

Artikel ini menjelaskan cara menyiapkan endpoint pribadi untuk toko transaksional Azure Cosmos DB. Ini mengasumsikan bahwa Anda menggunakan metode persetujuan otomatis. Jika Anda menggunakan penyimpanan analitik, lihat Mengonfigurasi titik akhir privat untuk penyimpanan analitik.

Buat titik akhir pribadi menggunakan portal Azure

Ikuti langkah-langkah ini untuk membuat titik akhir privat untuk akun Azure Cosmos DB yang sudah ada dengan menggunakan portal Azure:

  1. Masuk ke portal Azure, lalu pilih akun Azure Cosmos DB.

  2. Pilih Jaringan dari daftar pengaturan, lalu pilih + Titik akhir privat di bawah tab Akses privat :

    Cuplikan layar pilihan untuk membuat titik akhir privat di portal Azure

  3. Di panel Buat titik akhir privat - Dasar, masukkan atau pilih detail berikut ini:

    Pengaturan Nilai
    Detail Proyek
    Langganan Pilih langganan Anda.
    Grup sumber daya Pilih grup sumber daya.
    Detail instans
    Nama Masukkan nama apa pun untuk endpoint pribadi Anda. Jika nama ini diambil, buat yang unik.
    Wilayah Pilih wilayah tempat Anda ingin menerapkan Tautan Pribadi. Buat titik akhir privat di lokasi yang sama di mana jaringan virtual Anda ada.

  4. Pilih Berikutnya: Sumber Daya.

  5. Di panel Buat titik akhir privat - Sumber Daya , masukkan atau pilih informasi ini:

    Pengaturan Nilai
    Metode koneksi Pilih Sambungkan ke sumber daya Azure di direktori saya.

    Anda kemudian dapat memilih salah satu sumber daya Anda untuk menyiapkan Link Pribadi. Atau Anda dapat menyambungkan ke sumber daya orang lain dengan menggunakan ID sumber daya atau alias yang telah mereka bagikan dengan Anda.
    Langganan Pilih langganan Anda.
    Jenis Sumber Daya Pilih Microsoft.AzureCosmosDB/databaseAccounts.
    Sumber daya Pilih akun Azure Cosmos DB Anda.
    Target subresource Pilih tipe Azure Cosmos DB API yang ingin Anda petakan. Ini default hanya untuk satu pilihan untuk API untuk SQL, MongoDB, dan Cassandra. Untuk API untuk Gremlin dan Table, Anda juga dapat memilih NoSQL karena API ini dapat dioperasikan dengan API untuk NoSQL. Jika Anda memiliki gateway khusus yang disediakan untuk API untuk akun NoSQL, Anda juga akan melihat opsi untuk SqlDedicated.

  6. Pilih Berikutnya: Virtual Network.

  7. Di panel Buat titik akhir privat - Virtual Network, masukkan atau pilih informasi ini:

    Pengaturan Nilai
    Jaringan virtual Pilih jaringan virtual Anda.
    Subnet Pilih subnet Anda.

  8. Pilih Berikutnya: DNS.

  9. Di panel Buat titik akhir privat - DNS , masukkan atau pilih informasi ini:

    Pengaturan Nilai
    Integrasikan dengan zona DNS privat Pilih Ya.

    Untuk menyambungkan secara pribadi dengan titik akhir pribadi, Anda memerlukan catatan DNS. Kami menyarankan Anda mengintegrasikan titik akhir privat Anda dengan zona DNS privat. Anda juga bisa menggunakan server DNS Anda sendiri atau membuat catatan DNS dengan menggunakan file host di mesin virtual Anda.

    Saat Anda memilih ya untuk opsi ini, grup zona DNS pribadi juga dibuat. Grup zona DNS adalah link antara zona DNS privat dan titik akhir privat. Tautan ini membantu Anda memperbarui zona DNS privat secara otomatis saat ada pembaruan ke titik akhir privat. Misalnya, saat Anda menambah atau menghapus wilayah, zona DNS privat diperbarui secara otomatis.
    Nama konfigurasi Pilih langganan dan grup sumber daya.

    Zona DNS privat ditentukan secara otomatis. Anda tidak dapat mengubahnya dengan menggunakan portal Azure.

  10. Pilih Berikutnya: Tinjauan>Tag + buat. Pada halaman Tinjau +buat, Azure memvalidasi konfigurasi Anda.

  11. Setelah muncul pesan Validasi berhasil, pilih Buat.

Saat Anda memiliki Private Link yang disetujui untuk akun Azure Cosmos DB, di portal Azure, opsi Semua jaringan di panel Firewall dan jaringan virtual tidak tersedia.

Tipe API dan nama zona privat

Harap tinjau konfigurasi DNS Titik Akhir Privat Azure untuk penjelasan yang lebih rinci tentang zona privat dan konfigurasi DNS untuk titik akhir privat. Tabel berikut menunjukkan pemetaan antara berbagai jenis API akun Azure Cosmos DB, subresource yang didukung, dan nama zona privat yang sesuai. Anda juga dapat mengakses akun Gremlin dan API untuk Tabel melalui API untuk NoSQL, sehingga ada dua entri untuk API ini. Ada juga entri tambahan untuk API untuk NoSQL untuk akun yang menggunakan gateway khusus.

Jenis API akun Azure Cosmos DB Sub-sumber daya atau ID grup yang didukung ID Zona Privat
NoSQL Sql privatelink.documents.azure.com
NoSQL SqlDedicated privatelink.sqlx.cosmos.azure.com
Cassandra Cassandra privatelink.cassandra.cosmos.azure.com
Mongo MongoDB privatelink.mongo.cosmos.azure.com
Gremlin Gremlin privatelink.gremlin.cosmos.azure.com
Gremlin Sql privatelink.documents.azure.com
Tabel Tabel privatelink.table.cosmos.azure.com
Tabel Sql privatelink.documents.azure.com

Menggunakan alamat IP pribadi

Setelah titik akhir privat disediakan, Anda bisa meminta alamat IP. Untuk melihat alamat IP dari portal Azure:

  1. Cari titik akhir privat yang Anda buat sebelumnya. Dalam hal ini, itu cdbPrivateEndpoint3.
  2. Pilih tab Gambaran Umum untuk melihat pengaturan DNS dan alamat IP.

Cuplikan layar alamat IP privat di portal Azure

Beberapa alamat IP dibuat per titik akhir privat:

  • Satu untuk titik akhir agnostik wilayah global dari akun Azure Cosmos DB.
  • Satu untuk setiap wilayah tempat akun Azure Cosmos DB disebarkan.

Membuat titik akhir privat menggunakan Azure PowerShell

Jalankan skrip PowerShell berikut untuk membuat titik akhir privat bernama MyPrivateEndpoint untuk akun Azure Cosmos DB yang sudah ada. Ganti nilai variabel dengan detail untuk lingkungan Anda.

$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"

# Resource for the Azure Cosmos DB account: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin, or Table
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private endpoint to create
$PrivateEndpointName = "MyPrivateEndpoint"
# Location where the private endpoint can be created. The private endpoint should be created in the same location where your subnet or the virtual network exists
$Location = "westcentralus"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"

$privateEndpointConnection = New-AzPrivateLinkServiceConnection -Name "myConnectionPS" -PrivateLinkServiceId $cosmosDbResourceId -GroupId $CosmosDbSubResourceType
 
$virtualNetwork = Get-AzVirtualNetwork -ResourceGroupName  $ResourceGroupName -Name $VNetName  
 
$subnet = $virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq $SubnetName}  
 
$privateEndpoint = New-AzPrivateEndpoint -ResourceGroupName $ResourceGroupName -Name $PrivateEndpointName -Location $Location -Subnet  $subnet -PrivateLinkServiceConnection $privateEndpointConnection

Mengintegrasikan titik akhir privat dengan zona DNS privat

Setelah Anda membuat titik akhir privat, Anda bisa mengintegrasikannya dengan zona DNS pribadi dengan menggunakan skrip PowerShell berikut ini:

Import-Module Az.PrivateDns

# Zone name differs based on the API type and group ID you are using. 
$zoneName = "privatelink.documents.azure.com"
$zone = New-AzPrivateDnsZone -ResourceGroupName $ResourceGroupName `
  -Name $zoneName

$link  = New-AzPrivateDnsVirtualNetworkLink -ResourceGroupName $ResourceGroupName `
  -ZoneName $zoneName `
  -Name "myzonelink" `
  -VirtualNetworkId $virtualNetwork.Id  
 
$pe = Get-AzPrivateEndpoint -Name $PrivateEndpointName `
  -ResourceGroupName $ResourceGroupName

$networkInterface = Get-AzResource -ResourceId $pe.NetworkInterfaces[0].Id `
  -ApiVersion "2019-04-01"

# Create DNS configuration

$PrivateDnsZoneId = $zone.ResourceId

$config = New-AzPrivateDnsZoneConfig -Name $zoneName `
 -PrivateDnsZoneId $PrivateDnsZoneId

## Create a DNS zone group
New-AzPrivateDnsZoneGroup -ResourceGroupName $ResourceGroupName `
 -PrivateEndpointName $PrivateEndpointName `
 -Name "MyPrivateZoneGroup" `
 -PrivateDnsZoneConfig $config

Menggunakan alamat IP pribadi

Setelah titik akhir privat disediakan, Anda bisa meminta alamat IP dan pemetaan FQDN dengan menggunakan skrip PowerShell berikut ini:

$pe = Get-AzPrivateEndpoint -Name MyPrivateEndpoint -ResourceGroupName myResourceGroup
$networkInterface = Get-AzNetworkInterface -ResourceId $pe.NetworkInterfaces[0].Id
foreach ($IPConfiguration in $networkInterface.IpConfigurations)
{
    Write-Host $IPConfiguration.PrivateIpAddress ":" $IPConfiguration.PrivateLinkConnectionProperties.Fqdns
}

Membuat titik akhir privat menggunakan portal Azure

Jalankan skrip Azure CLI berikut untuk membuat titik akhir privat bernama myPrivateEndpoint untuk akun Azure Cosmos DB yang sudah ada. Ganti nilai variabel dengan detail untuk lingkungan Anda.

# Resource group where the Azure Cosmos DB account and virtual network resources are located
ResourceGroupName="myResourceGroup"

# Subscription ID where the Azure Cosmos DB account and virtual network resources are located
SubscriptionId="<your Azure subscription ID>"

# Name of the existing Azure Cosmos DB account
CosmosDbAccountName="mycosmosaccount"

# API type of your Azure Cosmos DB account: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin, or Table
CosmosDbSubResourceType="Sql"

# Name of the virtual network to create
VNetName="myVnet"

# Name of the subnet to create
SubnetName="mySubnet"

# Name of the private endpoint to create
PrivateEndpointName="myPrivateEndpoint"

# Name of the private endpoint connection to create
PrivateConnectionName="myConnection"

az network vnet create \
 --name $VNetName \
 --resource-group $ResourceGroupName \
 --subnet-name $SubnetName

az network vnet subnet update \
 --name $SubnetName \
 --resource-group $ResourceGroupName \
 --vnet-name $VNetName \
 --disable-private-endpoint-network-policies true

az network private-endpoint create \
    --name $PrivateEndpointName \
    --resource-group $ResourceGroupName \
    --vnet-name $VNetName  \
    --subnet $SubnetName \
    --private-connection-resource-id "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$CosmosDbAccountName" \
    --group-ids $CosmosDbSubResourceType \
    --connection-name $PrivateConnectionName

Mengintegrasikan titik akhir privat dengan zona DNS privat

Setelah Anda membuat titik akhir pribadi, Anda dapat mengintegrasikannya dengan zona DNS pribadi menggunakan skrip Azure CLI berikut:

#Zone name differs based on the API type and group ID you are using. 
zoneName="privatelink.documents.azure.com"

az network private-dns zone create --resource-group $ResourceGroupName \
   --name  $zoneName

az network private-dns link vnet create --resource-group $ResourceGroupName \
   --zone-name  $zoneName\
   --name myzonelink \
   --virtual-network $VNetName \
   --registration-enabled false 

#Create a DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group $ResourceGroupName \
   --endpoint-name $PrivateEndpointName \
   --name "MyPrivateZoneGroup" \
   --private-dns-zone $zoneName \
   --zone-name "myzone"

Membuat titik akhir privat dengan menggunakan templat Manajer Sumber Daya

Anda bisa menyetel Link Pribadi dengan membuat titik akhir privat di subnet jaringan virtual. Anda mencapai ini dengan menggunakan templat Azure Resource Manager.

Gunakan kode berikut untuk membuat templat Resource Manager bernama PrivateEndpoint_template.json. Templat ini membuat titik akhir privat untuk vAPI Azure Cosmos DB yang ada untuk akun NoSQL di jaringan virtual yang ada.

@description('Location for all resources.')
param location string = resourceGroup().location
param privateEndpointName string
param resourceId string
param groupId string
param subnetId string

resource privateEndpoint 'Microsoft.Network/privateEndpoints@2019-04-01' = {
  name: privateEndpointName
  location: location
  properties: {
    subnet: {
      id: subnetId
    }
    privateLinkServiceConnections: [
      {
        name: 'MyConnection'
        properties: {
          privateLinkServiceId: resourceId
          groupIds: [
            groupId
          ]
          requestMessage: ''
        }
      }
    ]
  }
}

output privateEndpointNetworkInterface string = privateEndpoint.properties.networkInterfaces[0].id

Tentukan file parameter untuk templat

Buat file parameter untuk templat, dan beri nama PrivateEndpoint_parameters.json. Tambahkan kode berikut ke file parameter:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateEndpointName": {
            "value": ""
        },
        "resourceId": {
            "value": ""
        },
        "groupId": {
            "value": ""
        },
        "subnetId": {
            "value": ""
        }
    }
}

Luncurkan templat menggunakan PowerShell

Buat skrip PowerShell dengan menggunakan kode berikut. Sebelum Anda menjalankan skrip, ganti ID langganan, nama grup sumber daya, dan nilai variabel lainnya dengan detail untuk lingkungan Anda.

### This script creates a private endpoint for an existing Azure Cosmos DB account in an existing virtual network

## Step 1: Fill in these details. Replace the variable values with the details for your environment.
$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos DB account. It can be one of the following: "Sql", "SqlDedicated", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private endpoint to create
$PrivateEndpointName = "myPrivateEndpoint"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"
$VNetResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Network/virtualNetworks/$($VNetName)"
$SubnetResourceId = "$($VNetResourceId)/subnets/$($SubnetName)"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_parameters.json"

## Step 2: Sign in to your Azure account and select the target subscription.
Login-AzAccount
Select-AzSubscription -SubscriptionId $subscriptionId

## Step 3: Make sure private endpoint network policies are disabled in the subnet.
$VirtualNetwork= Get-AzVirtualNetwork -Name "$VNetName" -ResourceGroupName "$ResourceGroupName"
($virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq "$SubnetName"} ).PrivateEndpointNetworkPolicies = "Disabled"
$virtualNetwork | Set-AzVirtualNetwork

## Step 4: Create the private endpoint.
Write-Output "Deploying private endpoint on $($resourceGroupName)"
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile $PrivateEndpointTemplateFilePath `
    -TemplateParameterFile $PrivateEndpointParametersFilePath `
    -SubnetId $SubnetResourceId `
    -ResourceId $CosmosDbResourceId `
    -GroupId $CosmosDbSubResourceType `
    -PrivateEndpointName $PrivateEndpointName

$deploymentOutput

Dalam skrip PowerShell, GroupId variabel hanya dapat berisi satu nilai. Nilai itu adalah tipe API akun. Nilai yang diizinkan adalah: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin, dan Table. Beberapa jenis akun Azure Cosmos DB dapat diakses melalui beberapa API. Contohnya:

  • API untuk akun NoSQL memiliki opsi tambahan untuk akun yang dikonfigurasi untuk menggunakan gateway khusus.
  • API untuk akun Gremlin dapat diakses dari Gremlin dan API untuk akun NoSQL.
  • API untuk akun Table dapat diakses dari Tabel dan API untuk akun NoSQL.

Untuk akun tersebut, Anda harus membuat satu titik akhir privat untuk setiap jenis API. Jika Anda membuat titik akhir privat untuk SqlDedicated, Anda hanya perlu menambahkan titik Sql akhir kedua jika Anda ingin juga menyambungkan ke akun Anda menggunakan gateway standar. Jenis API yang sesuai ditentukan dalam GroupId array.

Setelah templat berhasil diterapkan, Anda dapat melihat output yang mirip dengan apa yang ditunjukkan gambar berikut. Nilai provisioningState adalah Succeeded jika titik akhir privat disiapkan dengan benar.

Cuplikan layar output penyebaran untuk templat Resource Manager.

Setelah templat disebarkan, alamat IP pribadi dicadangkan dalam subnet. Aturan firewall akun Azure Cosmos DB dikonfigurasi untuk menerima koneksi dari titik akhir privat saja.

Mengintegrasikan titik akhir privat dengan zona DNS privat

Gunakan kode berikut untuk membuat templat Resource Manager bernama PrivateZone_template.json. Templat ini membuat zona DNS privat untuk API Azure Cosmos DB yang ada untuk akun NoSQL di jaringan virtual yang ada.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "type": "string"
        },
        "VNetId": {
            "type": "string"
        }        
    },
    "resources": [
        {
            "name": "[parameters('privateZoneName')]",
            "type": "Microsoft.Network/privateDnsZones",
            "apiVersion": "2018-09-01",
            "location": "global",
            "properties": {                
            }
        },
        {
            "type": "Microsoft.Network/privateDnsZones/virtualNetworkLinks",
            "apiVersion": "2018-09-01",
            "name": "[concat(parameters('privateZoneName'), '/myvnetlink')]",
            "location": "global",
            "dependsOn": [
                "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]"
            ],
            "properties": {
                "registrationEnabled": false,
                "virtualNetwork": {
                    "id": "[parameters('VNetId')]"
                }
            }
        }        
    ]
}

Tentukan file parameter untuk templat

Buat dua file parameter berikut untuk templat. Buat PrivateZone_parameters.json dengan kode berikut:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "value": ""
        },
        "VNetId": {
            "value": ""
        }
    }
}

Gunakan kode berikut untuk membuat templat Resource Manager bernama PrivateZoneGroup_template.json. Templat ini membuat grup zona DNS privat untuk API Azure Cosmos DB yang ada untuk akun NoSQL di jaringan virtual yang ada.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "type": "string"
        },
        "PrivateEndpointDnsGroupName": {
            "value": "string"
        },
        "privateEndpointName":{
            "value": "string"
        }        
    },
    "resources": [
        {
            "type": "Microsoft.Network/privateEndpoints/privateDnsZoneGroups",
            "apiVersion": "2020-06-01",
            "name": "[parameters('PrivateEndpointDnsGroupName')]",
            "location": "global",
            "dependsOn": [
                "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]",
                "[variables('privateEndpointName')]"
            ],
          "properties": {
            "privateDnsZoneConfigs": [
              {
                "name": "config1",
                "properties": {
                  "privateDnsZoneId": "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]"
                }
              }
            ]
          }
        }
    ]
}

Tentukan file parameter untuk templat

Buat dua file parameter berikut untuk templat. Buat PrivateZoneGroup_parameters.json. dengan kode berikut:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "value": ""
        },
        "PrivateEndpointDnsGroupName": {
            "value": ""
        },
        "privateEndpointName":{
            "value": ""
        }
    }
}

Luncurkan templat menggunakan PowerShell

Buat skrip PowerShell dengan menggunakan kode berikut. Sebelum Anda menjalankan skrip, ganti ID langganan, nama grup sumber daya, dan nilai variabel lainnya dengan detail untuk lingkungan Anda.

### This script:
### - creates a private zone
### - creates a private endpoint for an existing Azure Cosmos DB account in an existing VNet
### - maps the private endpoint to the private zone

## Step 1: Fill in these details. Replace the variable values with the details for your environment.
$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos DB account. It can be one of the following: "Sql", "SqlDedicated", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private zone to create
$PrivateZoneName = "myPrivateZone.documents.azure.com"
# Name of the private endpoint to create
$PrivateEndpointName = "myPrivateEndpoint"

# Name of the DNS zone group to create
$PrivateEndpointDnsGroupName = "myPrivateDNSZoneGroup"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"
$VNetResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Network/virtualNetworks/$($VNetName)"
$SubnetResourceId = "$($VNetResourceId)/subnets/$($SubnetName)"
$PrivateZoneTemplateFilePath = "PrivateZone_template.json"
$PrivateZoneParametersFilePath = "PrivateZone_parameters.json"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_parameters.json"
$PrivateZoneGroupTemplateFilePath = "PrivateZoneGroup_template.json"
$PrivateZoneGroupParametersFilePath = "PrivateZoneGroup_parameters.json"

## Step 2: Login your Azure account and select the target subscription
Login-AzAccount 
Select-AzSubscription -SubscriptionId $subscriptionId

## Step 3: Make sure private endpoint network policies are disabled in the subnet
$VirtualNetwork= Get-AzVirtualNetwork -Name "$VNetName" -ResourceGroupName "$ResourceGroupName"
($virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq "$SubnetName"} ).PrivateEndpointNetworkPolicies = "Disabled"
$virtualNetwork | Set-AzVirtualNetwork

## Step 4: Create the private zone
New-AzResourceGroupDeployment -Name "PrivateZoneDeployment" `
    -ResourceGroupName $ResourceGroupName `
    -TemplateFile $PrivateZoneTemplateFilePath `
    -TemplateParameterFile $PrivateZoneParametersFilePath `
    -PrivateZoneName $PrivateZoneName `
    -VNetId $VNetResourceId

## Step 5: Create the private endpoint
Write-Output "Deploying private endpoint on $($resourceGroupName)"
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile $PrivateEndpointTemplateFilePath `
    -TemplateParameterFile $PrivateEndpointParametersFilePath `
    -SubnetId $SubnetResourceId `
    -ResourceId $CosmosDbResourceId `
    -GroupId $CosmosDbSubResourceType `
    -PrivateEndpointName $PrivateEndpointName
$deploymentOutput

## Step 6: Create the private zone
New-AzResourceGroupDeployment -Name "PrivateZoneGroupDeployment" `
    -ResourceGroupName $ResourceGroupName `
    -TemplateFile $PrivateZoneGroupTemplateFilePath `
    -TemplateParameterFile $PrivateZoneGroupParametersFilePath `
    -PrivateZoneName $PrivateZoneName `
    -PrivateEndpointName $PrivateEndpointName`
    -PrivateEndpointDnsGroupName $PrivateEndpointDnsGroupName

Mengonfigurasi DNS kustom

Anda harus menggunakan zona DNS pribadi dalam subnet tempat Anda membuat titik akhir privat. Konfigurasikan titik akhir sehingga setiap alamat IP pribadi dipetakan ke entri DNS.Konfigurasikan titik akhir sehingga setiap alamat IP privat dipetakan ke entri DNS. Lihat properti fqdns dalam respons yang ditunjukkan sebelumnya.

Saat Anda membuat titik akhir privat, Anda bisa mengintegrasikannya dengan zona DNS pribadi di Azure. Jika Anda memilih untuk menggunakan zona DNS kustom, Anda harus mengonfigurasinya untuk menambahkan catatan DNS untuk semua alamat IP pribadi yang disediakan untuk titik akhir privat.

Penting

Ini adalah resolusi DNS permintaan Anda yang menentukan apakah permintaan ini melewati titik akhir privat Anda, atau mengambil rute publik standar. Pastikan DNS lokal Anda mereferensikan IP pribadi yang diatasi dengan benar yang dipetakan oleh titik akhir pribadi Anda.

Situasi dan hasil berikut dimungkinkan saat Anda menggunakan Private Link dalam kombinasi dengan aturan firewall:

  • Jika Anda tidak mengonfigurasi aturan firewall apa pun, maka secara default, semua lalu lintas dapat mengakses akun Azure Cosmos DB.

  • Jika Anda mengonfigurasi lalu lintas publik atau titik akhir layanan dan Anda membuat titik akhir pribadi, maka berbagai jenis lalu lintas masuk diizinkan oleh jenis aturan firewall yang sesuai. Jika titik akhir privat dikonfigurasi dalam subnet tempat titik akhir layanan juga dikonfigurasi:

    • lalu lintas ke akun database yang dipetakan oleh titik akhir pribadi dirutekan melalui titik akhir pribadi,
    • lalu lintas ke akun database lain dari subnet dirutekan melalui titik akhir layanan.

  • Jika Anda tidak mengonfigurasi lalu lintas publik atau titik akhir layanan apa pun dan Anda membuat titik akhir privat, akun Azure Cosmos DB hanya dapat diakses melalui titik akhir privat. Jika Anda tidak mengonfigurasi lalu lintas publik atau titik akhir layanan, setelah semua titik akhir privat yang disetujui ditolak atau dihapus, akun terbuka untuk seluruh jaringan kecuali PublicNetworkAccess diatur ke Dinonaktifkan.

Memblokir akses jaringan publik selama pembuatan akun

Seperti yang dijelaskan di bagian sebelumnya, dan kecuali aturan firewall tertentu telah ditetapkan, menambahkan titik akhir privat membuat akun Azure Cosmos DB Anda hanya dapat diakses melalui titik akhir privat. Ini berarti bahwa akun Azure Cosmos DB dapat dicapai dari lalu lintas publik setelah dibuat dan sebelum titik akhir privat ditambahkan. Untuk memastikan bahwa akses jaringan publik dinonaktifkan bahkan sebelum pembuatan titik akhir privat, Anda dapat mengatur publicNetworkAccess bendera ke Dinonaktifkan selama pembuatan akun. Perhatikan bahwa bendera ini lebih diutamakan daripada IP atau aturan jaringan virtual apa pun. Semua lalu lintas jaringan publik dan virtual diblokir ketika bendera diatur ke Dinonaktifkan, meskipun IP sumber atau jaringan virtual diizinkan dalam konfigurasi firewall.

Untuk contoh yang memperlihatkan cara menggunakan bendera ini, lihat templat Azure Resource Manager ini.

Menambahkan titik akhir privat ke akun Azure Cosmos DB yang sudah ada tanpa waktu henti

Secara default, menambahkan titik akhir privat ke akun yang ada menghasilkan waktu henti singkat sekitar lima menit. Ikuti petunjuk berikut untuk menghindari waktu henti ini:

  1. Tambahkan ip atau aturan jaringan virtual ke konfigurasi firewall Anda untuk secara eksplisit memperbolehkan koneksi klien Anda.
  2. Tunggu selama 10 menit untuk memastikan bahwa pembaruan konfigurasi diterapkan.
  3. Konfigurasikan endpoint pribadi baru Anda.
  4. Hapus aturan firewall yang ditetapkan di langkah 1.

Catatan

Jika Anda telah menjalankan aplikasi menggunakan SDK Azure Cosmos DB, mungkin ada batas waktu sementara selama pembaruan konfigurasi. Pastikan aplikasi Anda dirancang agar tahan terhadap kegagalan konektivitas sementara dan memiliki logika coba lagi jika diperlukan.

Rentang port ketika menggunakan mode langsung

Saat Anda menggunakan Private Link dengan akun Azure Cosmos DB melalui koneksi mode langsung, Anda perlu memastikan bahwa berbagai port TCP (0 - 65535) terbuka.

Memperbarui titik akhir privat saat Anda menambahkan atau menghapus kawasan

Ada tiga wilayah untuk penyebaran akun Azure Cosmos DB: US Barat, AS Tengah, dan Eropa Barat. Saat Anda membuat titik akhir pribadi untuk akun Anda, empat IP pribadi dicadangkan di subnet. Ada satu IP untuk masing-masing dari tiga wilayah, dan ada satu IP untuk titik akhir agnostik wilayah global. Nantinya, Anda dapat menambahkan wilayah baru ke akun Azure Cosmos DB. Zona DNS privat diperbarui sebagai berikut:

  • Jika grup zona DNS privat digunakan:

    Jika Anda menggunakan grup zona DNS privat, zona DNS privat akan diperbarui secara otomatis saat titik akhir privat diperbarui. Dalam contoh sebelumnya, setelah menambahkan wilayah baru, zona DNS pribadi diperbarui secara otomatis.

  • Jika grup zona DNS privat tidak digunakan:

    Jika Anda tidak menggunakan grup zona DNS privat, menambahkan atau menghapus wilayah ke akun Azure Cosmos DB mengharuskan Anda menambahkan atau menghapus entri DNS untuk akun tersebut. Setelah wilayah ditambahkan atau dihapus, Anda bisa memperbarui zona DNS pribadi subjaringan untuk mencerminkan entri DNS yang ditambahkan atau dihapus dan alamat IP pribadi terkait.

    Dalam contoh sebelumnya, setelah menambahkan wilayah baru, Anda perlu menambahkan catatan DNS terkait ke zona DNS pribadi atau DNS kustom Anda. Anda bisa menggunakan langkah yang sama saat menghapus kawasan. Setelah menghapus kawasan, Anda perlu menghapus catatan DNS terkait dari zona DNS pribadi atau DNS kustom Anda.

Batasan saat ini

Batasan berikut berlaku saat Anda menggunakan Private Link dengan akun Azure Cosmos DB:

  • Anda tidak dapat memiliki lebih dari 200 titik akhir privat pada satu akun Azure Cosmos DB.

  • Saat Anda menggunakan Private Link dengan akun Azure Cosmos DB melalui koneksi mode langsung, Anda hanya dapat menggunakan protokol TCP. Protokol HTTP saat ini tidak didukung.

  • Saat Anda menggunakan API Azure Cosmos DB untuk akun MongoDB, titik akhir privat didukung untuk akun di server versi 3.6 atau yang lebih tinggi (yaitu, akun yang menggunakan titik akhir dalam format *.mongo.cosmos.azure.com). Private Link tidak didukung untuk akun di server versi 3.2 (yaitu, akun yang menggunakan titik akhir dalam format *.documents.azure.com). Untuk menggunakan Private Link, Anda harus memigrasikan akun lama ke versi baru.

  • Saat Anda menggunakan API Azure Cosmos DB untuk akun MongoDB yang memiliki Private Link, alat dan pustaka harus mendukung Identifikasi Nama Layanan (SNI) atau meneruskan appName parameter dari string koneksi untuk terhubung dengan benar. Beberapa alat dan pustaka yang lebih lama mungkin tidak kompatibel dengan fitur Private Link.

  • Administrator jaringan harus diberikan setidaknya Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action izin di cakupan akun Azure Cosmos DB untuk membuat titik akhir privat yang disetujui secara otomatis.

  • Saat ini, Anda tidak dapat menyetujui koneksi titik akhir privat yang ditolak. Sebagai gantinya, buat ulang titik akhir privat untuk melanjutkan konektivitas privat. Layanan tautan privat Azure Cosmos DB secara otomatis menyetujui titik akhir privat yang dibuat ulang.

Batasan integrasi zona DNS privat

Kecuali Anda menggunakan grup zona DNS privat, rekaman DNS di zona DNS privat tidak dihapus secara otomatis saat Anda menghapus titik akhir privat atau Anda menghapus wilayah dari akun Azure Cosmos DB. Anda harus menghapus catatan DNS secara manual sebelumnya:

  • Menambahkan titik akhir privat baru yang ditautkan ke zona DNS privat ini.
  • Menambahkan wilayah baru ke akun database apa pun yang memiliki titik akhir privat yang ditautkan ke zona DNS privat ini.

Jika Anda tidak membersihkan catatan DNS, masalah pesawat data yang tidak terduga mungkin terjadi. Masalah ini termasuk pemadaman data ke wilayah yang ditambahkan setelah penghapusan titik akhir pribadi atau penghapusan kawasan.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang fitur keamanan Azure Cosmos DB, lihat artikel berikut ini: