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

Makale
02/20/2024

Key Vault VM uzantısı, 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. 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 (drwx------) olarak 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

Sertifika ile Key Vault örneği. Bkz. Key Vault oluşturma
VM/VMSS'de atanan yönetilen kimlik
VM'ler ve Azure Sanal Makine Ölçek Kümeleri yönetilen kimliği için Key Vault kapsam düzeyindeki Key Vault Gizli Dizileri Kullanıcı rolü. Bu rol, sertifikanın gizli dizi bölümünü alır. Daha fazla bilgi için aşağıdaki makaleleri inceleyin:
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]" }

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

Kullanıcılar, tam sertifika zinciri indirme özelliğini kullanmak için Key Vault vm uzantısı sürümünü yükseltmeyi V2.0 seçebilir. Veren sertifikaları (ara ve kök) PEM dosyasında yaprak sertifikaya dahil edilir.
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üklendiğinden --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ı dağıtmanı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 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's 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 'authentication Ayarlar' ö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'ta 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

Veri Akışı Adı	Değer / Örnek	Veri Türü
apiVersion	2022-07-01	tarih
Yayımcı	Microsoft.Azure.KeyVault	Dize
Tür	KeyVaultForLinux	Dize
typeHandlerVersion	2.0	int
pollingIntervalInS	3600	Dize
certificateStoreName	Linux'ta yoksayılır	Dize
linkOnRenewal	yanlış	boolean
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	Dize
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	Dize
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	Dize

Ş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ılı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ının JSON yapılandırması, şablonun sanal makine kaynak parçasının içine, özellikle "resources": [] sanal makine şablonuna ve nesnenin altındaki bir sanal makine ölçek kümesine ait nesnenin içine "virtualMachineProfile":"extensionProfile":{"extensions" :[] 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'ta kimlik doğrulaması yapma 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ıldıysa uzantı sıralamasını destekler. Varsayılan olarak uzantı, yoklama başlar başlamaz başarılı başlangıcı bildirir. Ancak, başarılı bir başlangıç bildirmeden önce sertifika listesinin tamamının başarıyla indirilmesini bekleyecek şekilde yapılandırabilirsiniz. Diğer uzantılar başlamadan önce yüklü sertifikalara bağımlı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 bir Transitioning durumda 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 Key Vault erişim ilkesini bu kimlikle güncelleştiren arm şablonuyla uyumlu değildir. Kasa erişim ilkesi tüm uzantılar başlatılana kadar güncelleştirilemediğinden bu işlem 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 sahip olmanız gerekir.

Azure PowerShell dağıtımı

Uyarı

PowerShell istemcileri genellikle settings.json ekler \" ve bu da akvvm_service hatayla başarısız olur: [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'ta Kimlik Doğrulaması Yapma ve Key Vault erişim ilkesi atama.

Sorun Giderme ve Destek

Uzantı dağıtımlarının durumuyla ilgili veriler Azure portalından 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'i 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ışabilir, ancak hafif biçim çeşitlemeleriyle. Azure CLI komutlarıyla ilgili beklenmeyen sonuçlara sahipseniz 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	Açıklama
/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 indirmenin durumunu belirlemek için Key Vault VM Uzantısı hizmet günlüklerini inceleyin. PEM dosyalarının indirme konumunu, sertifika dosya adı adlı bir girişe sahip dosyalarda bulabilirsiniz. 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 ([VaultName].[CertificateName]) sertifikanın en son sürümünü almak için bu bağlantıyı kullanabilirsiniz.

Sık Sorulan Sorular

Yapılandırabileceğiniz observedCertificates sayısıyla ilgili bir sınır var mı? Hayır, Key Vault VM Uzantısının gözlemlenenCertificates 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 oluşturabilirsiniz. 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.