Linux için sanal makine uzantısını Key Vault

Makale
08/26/2023

Key Vault VM uzantısı, Bir Azure anahtar kasasında depolanan sertifikaların otomatik olarak yenilenmesini sağlar. Özellikle uzantı, anahtar kasalarında depolanan gözlemlenen sertifikaların listesini izler. Uzantı, bir değişiklik algıladıktan sonra ilgili sertifikaları alır ve yükler. Key Vault VM uzantısı, şu anda Linux VM'lerde bulunan Microsoft tarafından yayımlanır ve desteklenir. Bu belgede, Linux için Key Vault VM uzantısı için desteklenen platformlar, yapılandırmalar ve dağıtım seçenekleri ayrıntılı olarak açıklanır.

İşletim sistemi

Key Vault VM uzantısı şu Linux dağıtımlarını destekler:

Ubuntu 20.04, 22.04
Azure Linux

Not

Key Vault VM Uzantısı, sertifikaları varsayılan konuma veya VM Uzantısı ayarlarında "certStoreLocation" özelliği tarafından sağlanan konuma indirir. Key Vault VM Uzantısı, klasör iznini 700 'e (drwx------) güncelleştirerek yalnızca klasörün sahibine okuma, yazma ve yürütme izni verir

Desteklenen sertifika içerik türleri

PKCS #12
PEM

Önkoşullar

Key Vault örneği sertifikayla. Bkz. Key Vault oluşturma
VM/VMSS atanmış yönetilen kimliğe sahip olmalıdır
Key Vault Erişim İlkesi, VM/VMSS yönetilen kimliğinin sertifikanın gizli dizi bölümünü alması için gizli get diziler ve list izinlerle ayarlanmalıdır. Bkz. Key Vault için Kimlik Doğrulama ve Key Vault erişim ilkesi atama.
VMSS aşağıdaki kimlik ayarına sahip olmalıdır: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
AKV uzantısı şu ayara sahip olmalıdır: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

VM uzantısı sürümünü Key Vault

Kullanıcılar, tam sertifika zinciri indirme özelliğini kullanmak için Key Vault vm uzantısı sürümlerini yükseltmeyi V2.0 seçebilir. Veren sertifikaları (ara ve kök) PEM dosyasındaki yaprak sertifikaya eklenir.
sürümüne v2.0yükseltmeyi tercih ederseniz, önce öğesini silmeniz v1.0 , ardından yüklemeniz gerekir v2.0.

  az vm extension delete --name KeyVaultForLinux --resource-group ${resourceGroup} --vm-name ${vmName}
  az vm extension set -n "KeyVaultForLinux" --publisher Microsoft.Azure.KeyVault --resource-group "${resourceGroup}" --vm-name "${vmName}" –settings .\akvvm.json –version 2.0

En son sürüm varsayılan olarak yükleneceği için --version 2.0 bayrağı isteğe bağlıdır.

VM'de v1.0 tarafından indirilen sertifikalar varsa, v1.0 AKVVM uzantısı silindiğinde indirilen sertifikalar SILINMEZ. v2.0 yüklendikten sonra mevcut sertifikalar DEĞIŞTIRILMEZ. VM'de tam zincire sahip PEM dosyasını almak için sertifika dosyalarını silmeniz veya sertifikayı aktarmanız gerekir.

Uzantı şeması

Aşağıdaki JSON, Key Vault VM uzantısının şemasını gösterir. Uzantı korumalı ayarlar gerektirmez; tüm ayarları güvenlik etkisi olmadan bilgi olarak kabul edilir. Uzantı, izlenen gizli dizilerin, yoklama sıklığının ve hedef sertifika deposunun bir listesini gerektirir. Özellikle:

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForLinux",
      "apiVersion": "2022-11-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <It is ignored on Linux>,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        },
        "authenticationSettings": {
          "msiEndpoint":  <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
          "msiClientId":  <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619".>
        }
       }
      }
    }

Not

Gözlemlenen sertifika URL'leriniz biçiminde https://myVaultName.vault.azure.net/secrets/myCertNameolmalıdır.

Bunun nedeni /secrets , yolun özel anahtar da dahil olmak üzere tam sertifikayı döndürmesi /certificates ve yol döndürmemesidir. Sertifikalar hakkında daha fazla bilgiyi burada bulabilirsiniz: Key Vault Sertifikaları

Önemli

Kullanıcı tarafından atanan kimliklere sahip VM'ler için 'authenticationSettings' özelliği gereklidir. Sistem tarafından atanan bir kimlik kullanmak isteseniz bile bu yine de gereklidir, aksi takdirde VM uzantısı hangi kimliğin kullanılacağını bilmez. Bu bölüm olmadan, kullanıcı tarafından atanan kimliklere sahip bir VM, Key Vault uzantısının başarısız olmasına ve sertifikaları indirememesine neden olur. msiClientId değerini Key Vault kimlik doğrulaması yapacak kimliğe ayarlayın.

Azure Arc özellikli VM'ler için de gereklidir. msiEndpoint değerini olarak http://localhost:40342/metadata/identityayarlayın.

Özellik değerleri

Name	Değer / Örnek	Veri Türü
apiVersion	2022-07-01	date
yayımcı	Microsoft.Azure.KeyVault	string
tür	KeyVaultForLinux	string
typeHandlerVersion	2.0	int
pollingIntervalInS	3600	string
certificateStoreName	Linux'ta yoksayılır	string
linkOnRenewal	yanlış	boolean
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	string
requireInitialSync	true	boolean
observedCertificates	["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]	dize dizisi
msiEndpoint	http://169.254.169.254/metadata/identity	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

Şablon dağıtımı

Azure VM uzantıları Azure Resource Manager şablonlarıyla dağıtılabilir. Şablonlar, sertifikaların dağıtım sonrası yenilenmesini gerektiren bir veya daha fazla sanal makine dağıtırken idealdir. Uzantı tek tek VM'lere veya sanal makine ölçek kümelerine dağıtılabilir. Şema ve yapılandırma her iki şablon türü için de ortaktır.

Bir sanal makine uzantısı için JSON yapılandırması, şablonun sanal makine kaynak parçasının içine, özellikle "resources": [] de sanal makine şablonunun nesnesine ve nesnenin altındaki "virtualMachineProfile":"extensionProfile":{"extensions" :[] bir sanal makine ölçek kümesine iç içe yerleştirilmelidir.

Not

VM uzantısı, Key Vault'ta kimlik doğrulaması yapmak için sistem veya kullanıcı tarafından yönetilen kimliğin atanmalarını gerektirir. Bkz. Key Vault için kimlik doğrulaması ve Key Vault erişim ilkesi atama.

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KeyVaultForLinux",
      "apiVersion": "2022-11-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ingnored on linux>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        }      
      }
      }
    }

Uzantı Bağımlılığı Sıralama

Key Vault VM uzantısı, yapılandırılmışsa uzantı sıralamasını destekler. Uzantı varsayılan olarak yoklama başlar başlamaz başarıyla başlatıldığını bildirir. Ancak, başarılı bir başlangıç bildirmeden önce sertifika listesinin tamamını başarıyla indirene kadar bekleyecek şekilde yapılandırılabilir. Diğer uzantılar başlamadan önce tam sertifika kümesinin yüklenmesine bağlıysa, bu ayarın etkinleştirilmesi bu uzantıların Key Vault uzantısına bağımlılık bildirmesine olanak tanır. Bu, bağımlı oldukları tüm sertifikalar yüklenene kadar bu uzantıların başlatılmasını engeller. Uzantı, ilk indirme işlemini süresiz olarak yeniden dener ve durumunda Transitioning kalır.

Uzantı bağımlılığını açmak için aşağıdakileri ayarlayın:

"secretsManagementSettings": {
    "requireInitialSync": true,
    ...
}

[Not] Bu özelliğin kullanılması, sistem tarafından atanan bir kimlik oluşturan ve bir Key Vault erişim ilkesini bu kimlikle güncelleştiren arm şablonuyla uyumlu değildir. Bunun yapılması, kasa erişim ilkesi tüm uzantılar başlatılana kadar güncelleştirilemediğinden kilitlenmeye neden olur. Bunun yerine, dağıtmadan önce tek bir kullanıcı tarafından atanan MSI kimliği kullanmanız ve kasalarınızı bu kimlikle önceden ACL'ye geçirmeniz gerekir.

Azure PowerShell dağıtımı

Uyarı

PowerShell istemcileri genellikle settings.json dosyasına ekler \" ve bu da akvvm_service şu hatayla başarısız olmasını sağlar: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell, Key Vault VM uzantısını mevcut bir sanal makineye veya sanal makine ölçek kümesine dağıtmak için kullanılabilir.

Uzantıyı bir VM'ye dağıtmak için:

    # Build settings
    $settings = '{"secretsManagementSettings": 
    { "pollingIntervalInS": "' + <pollingInterval> + 
    '", "certificateStoreName": "' + <certStoreName> + 
    '", "certificateStoreLocation": "' + <certStoreLoc> + 
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName =  "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"


    # Start the deployment
    Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Uzantıyı bir sanal makine ölçek kümesine dağıtmak için:


    # Build settings
    $settings = '{"secretsManagementSettings": 
    { "pollingIntervalInS": "' + <pollingInterval> + 
    '", "certificateStoreName": "' + <certStoreName> + 
    '", "certificateStoreLocation": "' + <certStoreLoc> + 
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"

    # Add Extension to VMSS
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -Setting $settings

    # Start the deployment
    Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Azure CLI dağıtımı

Azure CLI, Key Vault VM uzantısını mevcut bir sanal makineye veya sanal makine ölçek kümesine dağıtmak için kullanılabilir.

Uzantıyı bir VM'ye dağıtmak için:

   # Start the deployment
     az vm extension set -n "KeyVaultForLinux" `
     --publisher Microsoft.Azure.KeyVault `
     -g "<resourcegroup>" `
     --vm-name "<vmName>" `
     --version 2.0 `
     --enable-auto-upgrade true `
     --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

Uzantıyı bir sanal makine ölçek kümesine dağıtmak için:

      # Start the deployment
      az vmss extension set -n "KeyVaultForLinux" `
      --publisher Microsoft.Azure.KeyVault `
      -g "<resourcegroup>" `
      --vmss-name "<vmssName>" `
      --version 2.0 `
      --enable-auto-upgrade true `
      --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

Lütfen aşağıdaki kısıtlamalara/gereksinimlere dikkat edin:

Key Vault kısıtlamaları:
- Dağıtım sırasında mevcut olmalıdır
- Yönetilen Kimlik kullanılarak VM/VMSS Kimliği için Key Vault Erişim İlkesi ayarlanmalıdır. Bkz. Key Vault için Kimlik Doğrulama ve Key Vault erişim ilkesi atama.

Sorun Giderme ve Destek

Uzantı dağıtımlarının durumuyla ilgili veriler Azure portal ve Azure PowerShell kullanılarak alınabilir. Belirli bir VM'nin uzantılarının dağıtım durumunu görmek için Azure PowerShell kullanarak aşağıdaki komutu çalıştırın.

Azure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

Azure CLI

 az vm get-instance-view --resource-group <resource group name> --name  <vmName> --query "instanceView.extensions"

Azure CLI çeşitli kabuk ortamlarında çalıştırılabilir ancak biçim çeşitlemeleri hafiftir. Azure CLI komutlarıyla ilgili beklenmeyen sonuçlar alırsanız bkz. Azure CLI'yi başarıyla kullanma.

Günlükler ve yapılandırma

Key Vault VM uzantısı günlükleri yalnızca VM'de yerel olarak bulunur ve sorun giderme konusunda en bilgilendiricidir.

Konum	Description
/var/log/waagent.log	Uzantıya yönelik bir güncelleştirmenin ne zaman gerçekleştiğini gösterir.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	akvvm_service hizmetinin ve sertifika indirmesinin durumunu belirlemek için Key Vault VM Uzantısı hizmet günlüklerini inceleyin. PEM dosyalarının indirme konumu bu dosyalarda sertifika dosya adı adlı bir girişle de bulunur. certificateStoreLocation belirtilmezse, varsayılan olarak /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ olarak ayarlanır
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-en< son sürüm>/config/*	Key Vault VM Uzantısı hizmeti için yapılandırma ve ikili dosyalar.

Symlink kullanma

Sembolik bağlantılar veya Symlink'ler gelişmiş kısayollardır. Klasörün izlenmesini önlemek ve en son sertifikayı otomatik olarak almak için, Linux'ta sertifikanın en son sürümünü almak için bu symlink'i ([VaultName].[CertificateName]) kullanabilirsiniz.

Sık Sorulan Sorular

Ayarlayabileceğiniz gözlemlenenCertificate sayısı için bir sınır var mı? Hayır, Key Vault VM Uzantısının gözlemlenenCertificate sayısı sınırı yoktur.

Destek

Bu makalenin herhangi bir noktasında daha fazla yardıma ihtiyacınız varsa MSDN Azure ve Stack Overflow forumlarında Azure uzmanlarına başvurabilirsiniz. Alternatif olarak, bir Azure desteği olayı da kaydedebilirsiniz. Azure desteği sitesine gidin ve Destek al'ı seçin. Azure Desteği'ni kullanma hakkında bilgi için Microsoft Azure desteği SSS bölümünü okuyun.