Aracılığıyla paylaş

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

  • Makale

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:

Not

Key Vault VM Uzantısı, sertifikaları varsayılan konuma veya VM Uzantısı ayarlarında (sürüm 1/2) veya tek tek sertifika ayarlarında (sürüm 3) "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

Sürüm 3.0+ güncelleştirmeleri

Linux için Key Vault VM uzantısının 3.0+ sürümü aşağıdaki özellikler için destek ekler:

  • Kullanıcılara ve gruplara okuma erişimi sağlamak için indirilen sertifikalar için ACL izinleri ekleme
  • Sertifika yükleme konumu yapılandırması
  • Özel sembolik ad desteği
  • Fluentd aracılığıyla VM uzantısı günlüğü tümleştirme desteği

Önkoşullar

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

  • Kullanıcılar mevcut Key Vault VM uzantısı sürümünü daha yeni bir sürüme yükseltmeyi seçebilir.

  • Daha yeni bir sürüme yükseltmeyi tercih ederseniz, önce önceki sürümü silmeniz, ardından daha yeni bir sürüm yüklemeniz gerekir.

  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 3.0

En son sürüm varsayılan olarak yüklendiğinden --version 3.0 bayrağı isteğe bağlıdır.

  • VM'de önceki sürüme göre indirilen sertifikalar varsa, VM uzantısı silindiğinde indirilen sertifikalar silinmez. Daha yeni bir sürüm 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": "3.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
      "loggingSettings": <Optional logging settings, e.g.:
        {
              "logger": <Logger engine name. e.g.: "fluentd">,
              "endpoint": <Logger listening endpoint "tcp://localhost:24224">,
              "format": <Logging format. e.g.: "forward">,
              "servicename": <Service name used in logs. e.g.: "akvvm_service">
          }>,
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "aclEnabled": <Enables ACLs for downloaded certificates, e.g.: true>,
          "observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location, ACL permission to certificate private key, and custom symbolic name. e.g.: 
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. e.g.: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreLocation": <disk path where certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "customSymbolicLinkName": <symbolic name for the certificate. e.g.: "app1Cert1">,
                    "acls": [
                        {
                            "user": "app1",
                            "group": "appGroup1"
                        },
                        {
                            "user": "service1"
                        }
                    ]
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <disk path where the certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "acls": [
                        {
                            "user": "app2",
                        }
                    ]
                }
             ]>
        },
        "authenticationSettings": <Optional msi settings, e.g.:
        {
          "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'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
publisher Microsoft.Azure.KeyVault Dize
type KeyVaultForLinux Dize
typeHandlerVersion 3.0 int
pollingIntervalInS 3600 Dize
certificateStoreName Linux'ta yoksayılır Dize
linkOnRenewal yanlış boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store Dize
observedCertificates [{...}, {...}] dize dizisi
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" Dize
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" Dize
observedCertificates/customSymbolicLinkName (isteğe bağlı) "app1Cert1" Dize
observedCertificates/acls (isteğe bağlı) "{...}, {...}" dize dizisi
authenticationSettings (isteğe bağlı) {...} nesne
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity Dize
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 Dize
loggingSettings (isteğe bağlı) {...} nesne
loggingSettings/logger "fluentd" Dize
loggingSettings/endpoint "tcp://localhost:24224" Dize
loggingSettings/format "ileri" Dize
loggingSettings/servicename "akvvm_service" 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": "3.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "requireInitialSync": <initial synchronization of certificates e..g: false>,
          "aclEnabled": <enables/disables acls on defined certificates e.g.: true>,
          "observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example:
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
                    "acls": <Optional. An array of preferred acls with read access to certificate private keys. Example: 
                    [
                        {
                            "user": "app1",
                            "group": "appGroup1"
                        },
                        {
                            "user": "service1"
                        }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreName": <ignored on linux>,
                    "certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
                    "acls": <Optional. An array of preferred acls with read access to certificate private keys. Example: 
                    [
                        {
                            "user": "app2"
                        }
                    ]>
                }
               
             ]>   
          },
          "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">
          }
        } 
      }
    }

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ı başarıyla indirene kadar 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:

Azure Key Vault VM uzantısı Azure PowerShell ile dağıtılabilir. Key Vault VM uzantısı ayarlarını bir JSON dosyasına (settings.json) kaydedin.

Aşağıdaki JSON kod parçacıkları, PowerShell ile Key Vault VM uzantısını dağıtmak için örnek ayarlar sağlar.

{
   "secretsManagementSettings": {
   "pollingIntervalInS": "3600",
   "linkOnRenewal": true,
   "aclEnabled": true,
   "observedCertificates":
   [
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
          "certificateStoreLocation":  "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app1",
                  "group": "appGroup1"
              },
              {
                  "user": "service1"
              }
          ]
      },
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
          "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app2"
              }
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
   }      
}
  • Uzantıyı bir sanal makineye dağıtmak için:
# Build settings
$settings = (get-content -raw ".\settings.json")
$extName =  "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"
 
# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "3.0" -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 = (get-content -raw ".\settings.json")
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"
      
    # Add extension to Virtual Machine Scale Sets
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "3.0" -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:

Azure Key Vault VM uzantısı, Azure CLI kullanılarak dağıtılabilir. Key Vault VM uzantısı ayarlarını bir JSON dosyasına (settings.json) kaydedin.

Aşağıdaki JSON kod parçacıkları, Azure CLI ile Key Vault VM uzantısını dağıtmak için örnek ayarlar sağlar.

{
   "secretsManagementSettings": {
   "pollingIntervalInS": "3600",
   "linkOnRenewal": true,
   "aclEnabled": true,
   "observedCertificates":
   [
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
          "certificateStoreLocation":  "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app1",
                  "group": "appGroup1"
              },
              {
                  "user": "service1"
              }
          ]
      },
      {
          "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
          "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
          "acls": 
          [
              {
                  "user": "app2"
              }
          ]
      }
   ]},
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity/oauth2/token",
      "msiClientId":  "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
   }      
}
  • Uzantıyı bir sanal makineye dağıtmak için

    # Start the deployment
      az vm extension set -n "KeyVaultForLinux" `
      --publisher Microsoft.Azure.KeyVault `
      -g "<resourcegroup>" `
      --vm-name "<vmName>" `
      --version 3.0 `
      --enable-auto-upgrade true `
      --settings "@settings.json"
  • 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 3.0 `
    --enable-auto-upgrade true `
    --settings "@settings.json"

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
    • Key Vault Gizli Dizileri Kullanıcı rolü, VM kimliği için Key Vault'a atanmalıdır

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 VM'de yerel olarak bulunur ve sorun giderme konusunda en bilgilendiricidir. günlük sağlayıcısıyla tümleştirmek için isteğe bağlı günlük bölümünü kullanarak fluentd

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.

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.