Key Vault rozszerzenie maszyny wirtualnej dla systemu LinuxKey Vault virtual machine extension for Linux

Rozszerzenie maszyny wirtualnej Key Vault umożliwia automatyczne odświeżanie certyfikatów przechowywanych w magazynie kluczy platformy Azure.The Key Vault VM extension provides automatic refresh of certificates stored in an Azure key vault. Rozszerzenie monitoruje listę obserwowanych certyfikatów przechowywanych w magazynach kluczy.Specifically, the extension monitors a list of observed certificates stored in key vaults. Po wykryciu zmiany rozszerzenie pobiera i instaluje odpowiednie certyfikaty.Upon detecting a change, the extension retrieves, and installs the corresponding certificates. Rozszerzenie maszyny wirtualnej Key Vault jest publikowane i obsługiwane przez firmę Microsoft, obecnie na maszynach wirtualnych z systemem Linux.The Key Vault VM extension is published and supported by Microsoft, currently on Linux VMs. Ten dokument zawiera szczegółowe informacje o obsługiwanych platformach, konfiguracjach i opcjach wdrażania dla rozszerzenia maszyny wirtualnej Key Vault dla systemu Linux.This document details the supported platforms, configurations, and deployment options for the Key Vault VM extension for Linux.

System operacyjnyOperating system

Rozszerzenie maszyny wirtualnej Key Vault obsługuje te dystrybucje systemu Linux:The Key Vault VM extension supports these Linux distributions:

  • Ubuntu-1804Ubuntu-1804
  • SUSE-15Suse-15

Uwaga

Aby uzyskać rozszerzone funkcje zabezpieczeń, przygotuj się do uaktualnienia systemów Ubuntu-1604 i Debian-9, ponieważ te wersje zbliżają się do końca wydłużonego okresu wsparcia.To get extended security features, prepare to upgrade Ubuntu-1604 and Debian-9 systems as these versions are reaching their end of designated support period.

Obsługiwane typy zawartości certyfikatówSupported certificate content types

  • #12 PKCSPKCS #12
  • PEMPEM

Wymagania wstępnePrerequisities

  • Key Vault wystąpienie z certyfikatem.Key Vault instance with certificate. Zobacz tworzenie Key VaultSee Create a Key Vault

  • Maszyna wirtualna/VMSS musi mieć przypisaną tożsamość zarządzanąVM/VMSS must have assigned managed identity

  • Zasady dostępu Key Vault muszą być ustawione przy użyciu wpisów tajnych get i list uprawnień dla tożsamości ZARZĄDZANEJ maszyny wirtualnej/VMSS w celu pobrania części certyfikatu klucza tajnego.The Key Vault Access Policy must be set with secrets get and list permission for VM/VMSS managed identity to retrieve a secret's portion of certificate. Zobacz Jak przeprowadzić uwierzytelnianie, aby Key Vault i przypisać zasady dostępu Key Vault.See How to Authenticate to Key Vault and Assign a Key Vault access policy.

  • VMSS powinny mieć następujące ustawienie tożsamości: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }VMSS should have the following identity setting: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

  • Rozszerzenie AKV powinno mieć to ustawienie: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }AKV extension should have this setting: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Wersja rozszerzenia maszyny wirtualnej Key VaultKey Vault VM extension version

  • Ubuntu-18,04 i SUSE-15 użytkownicy mogą wybrać uaktualnienie wersji rozszerzenia maszyny wirtualnej magazynu kluczy, aby V2.0 uzyskać pełną funkcję pobierania łańcucha certyfikatów.Ubuntu-18.04 and SUSE-15 users can chose to upgrade their key vault vm extension version to V2.0 to avail full certificate chain download feature. Certyfikaty wystawcy (pośrednie i główne) będą dołączane do certyfikatu liścia w pliku PEM.Issuer certificates (intermediate and root) will be appended to the leaf certificate in the PEM file.

  • Jeśli wolisz uaktualnić do programu v2.0 , musisz v1.0 najpierw usunąć program, a następnie zainstalować v2.0 .If you prefer to upgrade to v2.0, you would need to delete v1.0 first, then install 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

Flaga--w wersji 2,0 jest opcjonalna, ponieważ Najnowsza wersja zostanie zainstalowana domyślnie.The flag --version 2.0 is optional because the latest version will be installed by default.

  • Jeśli maszyna wirtualna ma certyfikaty pobrane przez program v 1.0, usunięcie rozszerzenia AKVVM v 1.0 nie spowoduje usunięcia pobranych certyfikatów.If the VM has certificates downloaded by v1.0, deleting the v1.0 AKVVM extension will NOT delete the downloaded certificates. Po zainstalowaniu programu v 2.0 istniejące certyfikaty nie zostaną zmodyfikowane.After installing v2.0, the existing certificates will NOT be modified. Należy usunąć pliki certyfikatu lub przekroczyć certyfikat, aby pobrać plik PEM z pełnym łańcuchem na maszynie wirtualnej.You would need to delete the certificate files or roll-over the certificate to get the PEM file with full-chain on the VM.

Schemat rozszerzeniaExtension schema

Poniższy kod JSON przedstawia schemat rozszerzenia maszyny wirtualnej Key Vault.The following JSON shows the schema for the Key Vault VM extension. Rozszerzenie nie wymaga ustawień chronionych — wszystkie jego ustawienia są traktowane jako informacje bez wpływu na bezpieczeństwo.The extension does not require protected settings - all its settings are considered information without security impact. Rozszerzenie wymaga listy monitorowanych wpisów tajnych, częstotliwości sondowania i docelowego magazynu certyfikatów.The extension requires a list of monitored secrets, polling frequency, and the destination certificate store. W szczególności:Specifically:

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForLinux",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": 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":  <Optional MSI endpoint e.g.: "http://169.254.169.254/metadata/identity">,
                "msiClientId":  <Optional MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
        }
       }
      }
    }

Uwaga

Adresy URL obserwowanych certyfikatów powinny mieć postać https://myVaultName.vault.azure.net/secrets/myCertName .Your observed certificates URLs should be of the form https://myVaultName.vault.azure.net/secrets/myCertName.

Wynika to z faktu, że /secrets ścieżka zwraca pełny certyfikat, w tym klucz prywatny, podczas gdy /certificates ścieżka nie jest.This is because the /secrets path returns the full certificate, including the private key, while the /certificates path does not. Więcej informacji o certyfikatach można znaleźć tutaj: Key Vault CertificatesMore information about certificates can be found here: Key Vault Certificates

Ważne

Właściwość "authenticationSettings" jest wymagana tylko w przypadku maszyn wirtualnych z tożsamościami przypisanymi przez użytkownika.The 'authenticationSettings' property is required only for VMs with user assigned identities. Określa tożsamość do użycia podczas uwierzytelniania do Key Vault.It specifies identity to use for authentication to Key Vault.

Wartości właściwościProperty values

NazwaName Wartość/przykładValue / Example Typ danychData Type
apiVersionapiVersion 2019-07-012019-07-01 datadate
publisherpublisher Microsoft.Azure.KeyVaultMicrosoft.Azure.KeyVault ciągstring
typtype KeyVaultForLinuxKeyVaultForLinux ciągstring
typeHandlerVersiontypeHandlerVersion 2.02.0 intint
pollingIntervalInSpollingIntervalInS 36003600 ciągstring
certificateStoreNamecertificateStoreName Jest on ignorowany w systemie LinuxIt is ignored on Linux ciągstring
linkOnRenewallinkOnRenewal fałszfalse booleanboolean
certificateStoreLocationcertificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault/var/lib/waagent/Microsoft.Azure.KeyVault ciągstring
requireInitialSyncrequireInitialSync truetrue booleanboolean
observedCertificatesobservedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] Tablica ciągówstring array
msiEndpointmsiEndpoint http://169.254.169.254/metadata/identity ciągstring
msiClientIdmsiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619c7373ae5-91c2-4165-8ab6-7381d6e75619 ciągstring

Wdrażanie na podstawie szablonuTemplate deployment

Rozszerzenia maszyny wirtualnej platformy Azure można wdrażać za pomocą szablonów Azure Resource Manager.Azure VM extensions can be deployed with Azure Resource Manager templates. Szablony są idealne do wdrożenia co najmniej jednej maszyny wirtualnej, która wymaga odświeżenia certyfikatów po wdrożeniu.Templates are ideal when deploying one or more virtual machines that require post deployment refresh of certificates. Rozszerzenie można wdrożyć na poszczególnych maszynach wirtualnych lub w zestawach skalowania maszyn wirtualnych.The extension can be deployed to individual VMs or virtual machine scale sets. Schemat i konfiguracja są wspólne dla obu typów szablonów.The schema and configuration are common to both template types.

Konfiguracja JSON rozszerzenia maszyny wirtualnej musi być zagnieżdżona w ramach fragmentu zasobów maszyny wirtualnej szablonu, "resources": [] w odniesieniu do szablonu maszyny wirtualnej, a w przypadku zestawu skalowania maszyn wirtualnych w obszarze "virtualMachineProfile":"extensionProfile":{"extensions" :[] obiekt.The JSON configuration for a virtual machine extension must be nested inside the virtual machine resource fragment of the template, specifically "resources": [] object for the virtual machine template and in case of virtual machine scale set under "virtualMachineProfile":"extensionProfile":{"extensions" :[] object.

Uwaga

Rozszerzenie maszyny wirtualnej wymaga przypisania tożsamości zarządzanej przez system lub użytkownika do uwierzytelniania w magazynie kluczy.The VM extension would require system or user managed identity to be assigned to authenticate to Key vault. Zobacz Jak przeprowadzić uwierzytelnianie, aby Key Vault i przypisać zasady dostępu Key Vault.See How to authenticate to Key Vault and assign a Key Vault access policy.

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KeyVaultForLinux",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": 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"
        }      
      }
      }
    }

Porządkowanie rozszerzeńExtension Dependency Ordering

Rozszerzenie maszyny wirtualnej Key Vault obsługuje kolejność rozszerzeń, jeśli są skonfigurowane.The Key Vault VM extension supports extension ordering if configured. Domyślnie po rozpoczęciu sondowania rozszerzenia raporty zostały pomyślnie uruchomione.By default the extension reports that it has successfully started as soon as it has started polling. Można go jednak skonfigurować tak, aby czekał na pomyślne pobranie pełnej listy certyfikatów przed rozpoczęciem raportowania.However, it can be configured to wait until it has successfully downloaded the complete list of certificates before reporting a successful start. Jeśli inne rozszerzenia zależą od zainstalowania przed rozpoczęciem pełnego zestawu certyfikatów, włączenie tego ustawienia umożliwi tym rozszerzeniu zadeklarować zależność na rozszerzeniu Key Vault.If other extensions depend on having the full set of certificates install before they start, then enabling this setting will allow those extension to declare a dependency on the Key Vault extension. Uniemożliwi to uruchomienie tych rozszerzeń, dopóki nie zostaną zainstalowane wszystkie certyfikaty, od których zależą.This will prevent those extensions from starting until all certificates they depend on have been installed. Rozszerzenie ponowi próbę pobrania początkowego przez nieograniczony czas i pozostanie w Transitioning stanie.The extension will retry the initial download indefinitely and remain in a Transitioning state.

Aby je włączyć, ustaw następujące elementy:To turn this on set the following:

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

Korygując Korzystanie z tej funkcji jest niezgodne z szablonem usługi ARM, który tworzy tożsamość przypisaną do systemu i aktualizuje zasady dostępu Key Vault przy użyciu tej tożsamości.[Note] Using this feature is not compatible with an ARM template that creates a system assigned identity and updates a Key Vault access policy with that identity. Wykonanie tej czynności spowoduje zakleszczenie, ponieważ nie będzie można zaktualizować zasad dostępu do magazynu, dopóki nie zostaną uruchomione wszystkie rozszerzenia.Doing so will result in a deadlock as the vault access policy cannot be updated until all extensions have started. Przed wdrożeniem należy zamiast tego użyć pojedynczej tożsamości pliku MSI przypisanej do użytkownika i wstępnie listy ACL magazynów z tą tożsamością.You should instead use a single user assigned MSI identity and pre-ACL your vaults with that identity before deploying.

Wdrożenie Azure PowerShellAzure PowerShell deployment

Ostrzeżenie

Klienci programu PowerShell często dodają \ do " programu w settings.js, na którym spowoduje to niepowodzenie akvvm_service z powodu błędu: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.PowerShell clients often add \ to " in the settings.json which will cause akvvm_service fails with error: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell można użyć do wdrożenia rozszerzenia maszyny wirtualnej Key Vault do istniejącej maszyny wirtualnej lub zestawu skalowania maszyn wirtualnych.The Azure PowerShell can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.

  • Aby wdrożyć rozszerzenie na maszynie wirtualnej:To deploy the extension on a VM:

        # 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" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
    
    
  • Aby wdrożyć rozszerzenie na zestawie skalowania maszyn wirtualnych:To deploy the extension on a virtual machine scale set :

    
        # 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" -Setting $settings
    
        # Start the deployment
        Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss 
    
    

Wdrożenie interfejsu wiersza polecenia platformy AzureAzure CLI deployment

Interfejsu wiersza polecenia platformy Azure można użyć do wdrożenia rozszerzenia maszyny wirtualnej Key Vault na istniejącej maszynie wirtualnej lub w zestawie skalowania maszyn wirtualnych.The Azure CLI can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.

  • Aby wdrożyć rozszerzenie na maszynie wirtualnej:To deploy the extension on a VM:

       # Start the deployment
         az vm extension set -n "KeyVaultForLinux" `
         --publisher Microsoft.Azure.KeyVault `
         -g "<resourcegroup>" `
         --vm-name "<vmName>" `
         --version 2.0 `
         --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    
  • Aby wdrożyć rozszerzenie na zestawie skalowania maszyn wirtualnych:To deploy the extension on a virtual machine scale set :

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

Należy pamiętać o następujących ograniczeniach/wymaganiach:Please be aware of the following restrictions/requirements:

Często zadawane pytaniaFrequently Asked Questions

  • Czy istnieje limit liczby observedCertificates można skonfigurować?Is there is a limit on the number of observedCertificates you can setup? Nie, Key Vault rozszerzenie maszyny wirtualnej nie ma limitu liczby observedCertificates.No, Key Vault VM Extension doesn’t have limit on the number of observedCertificates.

Rozwiązywanie problemówTroubleshoot

Dane dotyczące stanu wdrożeń rozszerzeń można pobrać z Azure Portal i przy użyciu Azure PowerShell.Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure PowerShell. Aby wyświetlić stan wdrożenia dla danej maszyny wirtualnej, uruchom następujące polecenie przy użyciu Azure PowerShell.To see the deployment state of extensions for a given VM, run the following command using the Azure PowerShell.

Azure PowerShellAzure PowerShell

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

Interfejs wiersza polecenia platformy AzureAzure CLI

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

Dzienniki i konfiguracjaLogs and configuration

/var/log/waagent.log
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/*

Linki symboliczne lub linków symbolicznych są zasadniczo zaawansowanymi skrótami.Symbolic links or Symlinks are basically advanced shortcuts. Aby uniknąć monitorowania folderu i automatycznego uzyskiwania najnowszego certyfikatu, możesz użyć tego link symboliczny ([VaultName].[CertificateName]) do pobrania najnowszej wersji certyfikatu w systemie Linux.To avoid monitoring the folder and to get the latest certificate automatically, you can use this symlink ([VaultName].[CertificateName]) to get the latest version of certificate on Linux.

Często zadawane pytaniaFrequently Asked Questions

  • Czy istnieje limit liczby observedCertificates można skonfigurować?Is there is a limit on the number of observedCertificates you can setup? Nie, Key Vault rozszerzenie maszyny wirtualnej nie ma limitu liczby observedCertificates.No, Key Vault VM Extension doesn’t have limit on the number of observedCertificates.

Pomoc technicznaSupport

Jeśli potrzebujesz więcej pomocy w dowolnym punkcie tego artykułu, możesz skontaktować się z ekspertami platformy Azure na forach MSDN i Stack Overflow.If you need more help at any point in this article, you can contact the Azure experts on the MSDN Azure and Stack Overflow forums. Alternatywnie możesz zaplikować zdarzenie pomocy technicznej platformy Azure.Alternatively, you can file an Azure support incident. Przejdź do witryny pomocy technicznej systemu Azure i wybierz pozycję Uzyskaj pomoc techniczną.Go to the Azure support site and select Get support. Aby uzyskać informacje o korzystaniu z pomocy technicznej platformy Azure, przeczytaj temat Microsoft Azure support — często zadawane pytania.For information about using Azure Support, read the Microsoft Azure support FAQ.