Azure DocumentDB kümesi için dinlenme halindeki veri şifrelemesi için müşteri tarafından yönetilen anahtar (CMK) yapılandırma

Bu makalede, Azure DocumentDB'de bekleyen veri şifrelemesi için müşteri tarafından yönetilen anahtarı (CMK) yapılandırmayı öğreneceksiniz. Bu kılavuzdaki adımlar, yeni bir Azure DocumentDB kümesi, bir çoğaltma kümesi veya geri yüklenen bir küme yapılandırır. CMK kurulumu, Azure Key Vault'ta depolanan müşteri tarafından yönetilen anahtarı ve kullanıcı tarafından atanan yönetilen kimliği kullanır.

Önkoşullar

• Azure aboneliği

  • Azure aboneliğiniz yoksa ücretsiz bir hesap oluşturun

• Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz. Azure Cloud Shell'i kullanmaya başlama.

  

• CLI referans komutlarını yerel olarak çalıştırmayı tercih ediyorsanız, Azure CLI'yi yükleyin. Windows veya macOS üzerinde çalışıyorsanız, Azure CLI'yi bir Docker konteynerinde çalıştırmayı düşünün. Daha fazla bilgi için Azure CLI'nin bir Docker konteynerında nasıl çalıştırılacağını inceleyin.

  • Yerel bir kurulum kullanıyorsanız, az login komutunu kullanarak Azure CLI'ye giriş yapın. Kimlik doğrulama işlemini tamamlamak için, terminalinizde görüntülenen adımları takip edin. Diğer oturum açma seçenekleri için bkz. Azure CLI kullanarak Azure'da kimlik doğrulaması.

  • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma ve yönetme.

  • Yüklü olan sürümü ve bağımlı kütüphaneleri bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

Kullanıcı tarafından atanan yönetilen kimliği ve Azure Key Vault'ı hazırlama

MonogDB için Azure DocumentDB kümenizde müşteri tarafından yönetilen anahtar şifrelemesini yapılandırmak için, kullanıcı tarafından atanan yönetilen kimlik, Azure Key Vault örneği ve izinlerin düzgün yapılandırılması gerekir.

Önemli

CMK'yi yapılandırmak için kullanılan kullanıcı tarafından atanan yönetilen kimlik ve Azure Key Vault örneği, Azure DocumentDB kümesinin barındırıldığı aynı Azure bölgesinde olmalı ve hepsi aynı Microsoft kiracısına ait olmalıdır.

Azure portalını kullanma:

1. Henüz yoksa küme bölgesinde kullanıcı tarafından atanan bir yönetilen kimlik oluşturun.

2. Henüz bir anahtar deponuz oluşturulmadıysa küme bölgesinde bir Azure Key Vault oluşturun. Gereksinimleri karşıladığınızdan emin olun. Ayrıca, anahtar depoyu yapılandırmadan önce ve anahtarı oluşturup kullanıcı tarafından atanan yönetilen kimliğe gerekli izinleri atamadan önce önerileri izleyin.

3. Anahtar deponuzda bir anahtar oluşturun.

4. Gereksinimlerde açıklandığı gibi Azure Key Vault örneğine kullanıcı tarafından atanan yönetilen kimlik izinleri verin.

Küme sağlama sırasında müşteri tarafından yönetilen anahtarla veri şifrelemeyi yapılandırma

Portal

1. Yeni bir Azure DocumentDB kümesinin sağlanması sırasında, küme veri şifrelemesi için hizmet tarafından yönetilen veya müşteri tarafından yönetilen anahtarlar Şifreleme sekmesinde yapılandırılır. Veri şifrelemesi için Müşteri tarafından yönetilen anahtarı seçin.

   

2. Kullanıcı tarafından atanan yönetilen kimlik bölümünde Kimliği değiştir'i seçin.

   

3. Kullanıcı tarafından atanan yönetilen kimlikler listesinde, Azure Key Vault'ta depolanan veri şifreleme anahtarına erişmek için kümenizin kullanmasını istediğiniz kimlikleri seçin.

   

4. Add (Ekle) seçeneğini belirleyin.

   

5. Anahtar seçimi yöntemindeAnahtar seçin'i seçin.

6. Anahtar bölümünde Anahtarı değiştir'i seçin.

   

7. Anahtar seçin bölmesinde Anahtarkasasında Azure Key Vault'a ve Anahtar'daki şifreleme anahtarına tıklayın ve Seç'i seçerek seçimlerinizi onaylayın.

   

   Önemli

   Seçilen Azure Key Vault örneği, Azure DocumentDB kümesinin barındırılacağı Azure bölgesinde olmalıdır.

8. Şifreleme sekmesinde seçili kullanıcı tarafından atanan yönetilen kimliği ve şifreleme anahtarını onaylayın ve küme oluşturmak için Gözden Geçir ve oluştur'u seçin.

   

REST API'leri

Kullanıcı tarafından atanan şifreleme anahtarıyla veri şifrelemeyi etkinleştirebilir ve bir komut aracılığıyla az rest yeni bir küme sağlayabilirsiniz.

1. Aşağıdaki içeriğe sahip bir JSON dosyası oluşturun. sign ile $ başlayan yer tutucuları gerçek değerlerle değiştirin ve dosyayı kaydedin.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "administrator": {
             "userName": "$adminName",
             "password": "$complexPassword"
           },
           "serverVersion": "8.0",
           "storage": {
             "sizeGb": 32
           },
           "compute": {
             "tier": "M40"
           },
           "sharding": {
             "shardCount": 1
           },
           "highAvailability": {
             "targetMode": "ZoneRedundantPreferred"
           },
         "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Uyarı

   keyEncryptionKeyUrl anahtar adını içermelidir ancak belirli bir anahtar sürümünü içermemelidir.

2. Azure DocumentDB kümesi oluşturmak üzere REST API çağrısı yapmak için aşağıdaki Azure CLI komutunu çalıştırın. Değişkenler bölümündeki yer tutucuları ve komut satırındaki parametresinin --bodyaz rest dosya adını gerçek değerlerle değiştirin.

   # Define your variables
   $randomIdentifier = (New-Guid).ToString().Substring(0,8)
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="DocumentDB"
   $mongoClustersName="msdocscr$randomIdentifier"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

CMK etkin kümede veri şifreleme ayarlarını güncelleştirme

Müşteri tarafından yönetilen bir anahtar kullanılarak veri şifrelemesi ile dağıtılan mevcut kümeler için çeşitli yapılandırma değişiklikleri yapabilirsiniz. Şifreleme anahtarının depolandığı anahtar kasasını ve müşteri tarafından yönetilen anahtar olarak kullanılan şifreleme anahtarını değiştirebilirsiniz. Anahtar deposunda tutulan şifreleme anahtarına erişmek için hizmet tarafından kullanılan kullanıcı tarafından atanan yönetilen kimliği de değiştirebilirsiniz.

Portal

1. Küme kenar çubuğundaki Ayarlar'ın altında Veri şifreleme'yi seçin.

2. Kullanıcı tarafından atanan yönetilen kimlik bölümünde Kimliği değiştir'i seçin.

   

3. Kullanıcı tarafından atanan yönetilen kimlikler listesinde, Azure Key Vault'ta depolanan veri şifreleme anahtarına erişmek için kümenizin kullanmasını istediğiniz kimlikleri seçin.

   

4. Add (Ekle) seçeneğini belirleyin.

5. Anahtar seçimi yöntemindeAnahtar seçin'i seçin.

6. Anahtar menüsündeAnahtarı değiştir seçeneğini seçin.

   

7. Anahtar seçin bölmesinde Anahtarkasasında Azure Key Vault'a ve Anahtar'daki şifreleme anahtarına tıklayın ve Seç'i seçerek seçimlerinizi onaylayın.

   

   Önemli

   Seçilen Azure Key Vault örneği, Azure DocumentDB kümesinin barındırıldığı Azure bölgesinde olmalıdır.

8. Veri şifreleme sayfasında seçili kullanıcı tarafından atanan yönetilen kimliği ve şifreleme anahtarını onaylayın ve seçimlerinizi onaylamak ve çoğaltma kümesi oluşturmak için Kaydet'i seçin.

   

REST API'leri

Rest API çağrısı aracılığıyla mevcut bir kümede veri şifrelemesi için kullanıcı tarafından atanan yönetilen kimliği ve şifreleme anahtarını değiştirebilirsiniz.

1. Aşağıdaki içeriğe sahip bir JSON dosyası oluşturun. sign ile $ başlayan yer tutucuları gerçek değerlerle değiştirin ve dosyayı kaydedin.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   Uyarı

   keyEncryptionKeyUrl anahtar adını içermelidir ancak belirli bir anahtar sürümünü içermemelidir.

2. Azure DocumentDB kümesi oluşturmak üzere REST API çağrısı yapmak için aşağıdaki Azure CLI komutunu çalıştırın. Değişkenler bölümündeki yer tutucuları ve komut satırındaki parametresinin --bodyaz rest dosya adını gerçek değerlerle değiştirin.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Anahtara erişmek için yalnızca kullanıcı tarafından atanan yönetilen kimliği değiştirmek veya yalnızca veri şifreleme için kullanılan anahtarı değiştirmek veya her ikisini aynı anda değiştirmek istiyorsanız, JSON dosyasında listelenen tüm parametreleri sağlamanız gerekir.

Belirtilen anahtar veya kullanıcı tarafından atanan yönetilen kimlik yoksa hatayı alırsınız.

Parametre olarak geçirilen kimlikler varsa ve geçerliyse, Azure DocumentDB kümenizle ilişkili kullanıcı tarafından atanan yönetilen kimlikler listesine otomatik olarak eklenir. Komut daha sonra başka bir hatayla başarısız olsa bile bu durum geçerlidir.

Mevcut kümelerde veri şifreleme modunu değiştirme

Veri şifrelemesi için hizmet tarafından yönetilen anahtar mı yoksa müşteri tarafından yönetilen anahtar mı (CMK) kullanmak istediğinize karar verebileceğiniz tek nokta, küme oluşturma zamanıdır. Bu kararı verdikten ve kümeyi oluşturduktan sonra iki seçenek arasında geçiş yapamazsınız. Farklı bir şifreleme seçeneğiyle Azure DocumentDB kümenizin bir kopyasını oluşturmak için bir çoğaltma kümesi oluşturabilir veya bir küme geri yükleme işlemi gerçekleştirebilir ve çoğaltma kümesi veya geri yüklenen küme oluşturma sırasında yeni şifreleme modunu seçebilirsiniz.

Çoğaltma kümesi oluşturma sırasında müşteri tarafından yönetilen anahtar (CMK) veri şifrelemesini etkinleştirme veya devre dışı bırakma

Bir çoğaltma kümesinde CMK'yi etkinleştirmek veya devre dışı bırakmak için CMK veya SMK veri şifrelemesi ile bir çoğaltma kümesi oluşturmak için bu adımları izleyin.

Portal

1. Küme kenar çubuğunda, Ayarlar'ın altında Genel dağıtım'ı seçin.

2. Yeni okuma replikası ekle'yi seçin.

   

3. Read replica adı alanına, bir replika küme adı girin.

4. Okuma çoğaltması bölgesinde bir bölge seçin. Replika kümesi, seçili Azure bölgesinde barındırılmaktadır.

   Uyarı

   Çoğaltma kümesi her zaman birincil (okuma-yazma) kümesiyle aynı Azure aboneliğinde ve kaynak grubunda oluşturulur.

   

5. Veri şifreleme bölümünde, çoğaltma kümesinde CMK'yi devre dışı bırakmak üzere CMK veya Hizmet tarafından yönetilen anahtarı etkinleştirmek için Müşteri tarafından yönetilen anahtarı seçin.

   

6. Kullanıcı tarafından atanan yönetilen kimlik bölümünde Kimliği değiştir'i seçin.

   

7. Kullanıcı tarafından atanan yönetilen kimlikler listesinde, Azure Key Vault'ta depolanan veri şifreleme anahtarına erişmek için kümenizin kullanmasını istediğiniz kimlikleri seçin.

   

8. Add (Ekle) seçeneğini belirleyin.

9. Anahtar seçimi yöntemindeAnahtar seçin'i seçin.

10. Anahtar menüsündeAnahtarı değiştir seçeneğini seçin.

    

11. Anahtar seçin bölmesinde Anahtarkasasında Azure Key Vault'a ve Anahtar'daki şifreleme anahtarına tıklayın ve Seç'i seçerek seçimlerinizi onaylayın.

    

12. Genel dağıtım sayfasında seçili kullanıcı tarafından atanan yönetilen kimliği ve şifreleme anahtarını onaylayın ve kaydet'i seçerek seçimlerinizi onaylayın ve çoğaltma kümesi oluşturun.

    

REST API'leri

Aynı bölgede CMK etkinleştirilmiş bir çoğaltma kümesi oluşturmak için aşağıdaki adımları izleyin.

1. Aşağıdaki içeriğe sahip bir JSON dosyası oluşturun. sign ile $ başlayan yer tutucuları gerçek değerlerle değiştirin ve dosyayı kaydedin.

   {
           "identity": {
               "type": "UserAssigned",
               "userAssignedIdentities": {
                 "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
               }
             },
         "location": "$targetRegionName",
             "properties": {
             	"createMode": "GeoReplica",
                   "replicaParameters": {
                     "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$sourceClusterName",
                     "sourceLocation": "sourceRegionName"
                   },
                   "encryption": {
                     "customerManagedKeyEncryption": {
                       "keyEncryptionKeyIdentity": {
                         "identityType": "UserAssignedIdentity",
                         "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                       },
                       "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                     }
                   }
             }
       }
   

   Uyarı

   keyEncryptionKeyUrl anahtar adını içermelidir ancak belirli bir anahtar sürümünü içermemelidir.

2. Azure DocumentDB kümesi oluşturmak üzere REST API çağrısı yapmak için aşağıdaki Azure CLI komutunu çalıştırın. Değişkenler bölümündeki yer tutucuları ve komut satırındaki parametresinin --bodyaz rest dosya adını gerçek değerlerle değiştirin.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Küme geri yükleme sırasında müşteri tarafından yönetilen anahtar (CMK) veri şifrelemesini etkinleştirme veya devre dışı bırakma

Geri yükleme işlemi aynı Azure bölgesinde, aboneliğinde ve kaynak grubunda özgün kümeyle aynı yapılandırmaya sahip yeni bir küme oluşturur. CMK veya SMK etkin olarak geri yüklenen bir küme oluşturmak için bu adımları izleyin.

Portal

1. Mevcut bir Azure DocumentDB kümesini seçin.

2. Küme kenar çubuğundaki Ayarlar'ın altında Belirli Bir Noktaya Geri Yükleme'yi seçin.

3. Bir tarih seçin ve tarih ve saat alanlarında bir saat (UTC saat diliminde) sağlayın.

   

4. Hedef küme adını Restore target cluster name alanına girin.

   

5. Yönetici kullanıcı adı alanına geri yüklenen küme için bir küme yöneticisi adı girin.

6. Parola ve Parolayı onayla alanlarına yönetici rolü için bir parola girin.

   

7. Veri şifreleme bölümünde, CMK'yi etkinleştirmek için Müşteri tarafından yönetilen anahtarı seçin. Geri yüklenen kümede CMK'nin devre dışı bırakılması gerekiyorsa Hizmet tarafından yönetilen anahtar'ı seçin.

   

8. Kullanıcı tarafından atanan yönetilen kimlik bölümünde Kimliği değiştir'i seçin.

   

9. Kullanıcı tarafından atanan yönetilen kimlikler listesinde, Azure Key Vault'ta depolanan veri şifreleme anahtarına erişmek için kümenizin kullanmasını istediğiniz kimlikleri seçin.

   

10. Add (Ekle) seçeneğini belirleyin.

11. Anahtar seçimi yöntemindeAnahtar seçin'i seçin.

12. Anahtar menüsündeAnahtarı değiştir seçeneğini seçin.

    

13. Anahtar seçin bölmesinde Anahtarkasasında Azure Key Vault'a ve Anahtar'daki şifreleme anahtarına tıklayın ve Seç'i seçerek seçimlerinizi onaylayın.

    

14. Küme geri yüklemesini başlatmak için Gönder'i seçin.

REST API'leri

CMK etkin bir kümeyi geri yüklemek için aşağıdaki adımları izleyin.

1. Aşağıdaki içeriğe sahip bir JSON dosyası oluşturun. sign ile $ başlayan yer tutucuları gerçek değerlerle değiştirin ve dosyayı kaydedin.

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
               "administrator": {
                 "userName": "$adminName"
               },
         	"createMode": "PointInTimeRestore",
               "restoreParameters": {
                 "pointInTimeUTC": "yyyy-mm-ddThh:mm:ssZ",
                 "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$restoredClusterName"
               },
               "encryption": {
                 "customerManagedKeyEncryption": {
                   "keyEncryptionKeyIdentity": {
                     "identityType": "UserAssignedIdentity",
                     "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                   },
                   "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                 }
               }
         }
   }
   

   Uyarı

   keyEncryptionKeyUrl anahtar adını içermelidir ancak belirli bir anahtar sürümünü içermemelidir.

2. Azure DocumentDB kümesi oluşturmak üzere REST API çağrısı yapmak için aşağıdaki Azure CLI komutunu çalıştırın. Değişkenler bölümündeki yer tutucuları ve komut satırındaki parametresinin --bodyaz rest dosya adını gerçek değerlerle değiştirin.

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

Geri yüklenen küme oluşturulduktan sonra geri yükleme sonrası görevlerin listesini gözden geçirin.

İlgili içerik

• Azure DocumentDB'de dinamik olmayan veri şifrelemesi hakkında bilgi edinin
• CMK kurulumu sorunlarını giderme
• CMK sınırlamalarına göz atın
• Verileri Azure DocumentDB'ye geçirme