Rozszerzenie maszyny wirtualnej usługi Key Vault dla systemu Linux

Artykuł
02/20/2024

Rozszerzenie maszyny wirtualnej usługi Key Vault zapewnia automatyczne odświeżanie certyfikatów przechowywanych w magazynie kluczy platformy Azure. W szczególności rozszerzenie monitoruje listę obserwowanych certyfikatów przechowywanych w magazynach kluczy. Rozszerzenie pobiera i instaluje odpowiednie certyfikaty po wykryciu zmiany. Ten dokument zawiera szczegółowe informacje o obsługiwanych platformach, konfiguracjach i opcjach wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault dla systemu Linux.

System operacyjny

Rozszerzenie maszyny wirtualnej usługi Key Vault obsługuje następujące dystrybucje systemu Linux:

Ubuntu 20.04, 22.04
Azure Linux

Uwaga

Rozszerzenie maszyny wirtualnej usługi Key Vault pobiera certyfikaty w domyślnej lokalizacji lub do lokalizacji udostępnionej przez właściwość "certStoreLocation" w ustawieniach rozszerzenia maszyny wirtualnej. Rozszerzenie maszyny wirtualnej usługi Key Vault aktualizuje uprawnienie do folderu 700 (drwx------) zezwalając na uprawnienia tylko do odczytu, zapisu i wykonywania dla właściciela folderu

Obsługiwane typy zawartości certyfikatów

PKCS #12
PEM

Wymagania wstępne

Wystąpienie usługi Key Vault z certyfikatem. Zobacz Tworzenie usługi Key Vault
Przypisana tożsamość zarządzana na maszynach wirtualnych/maszynach wirtualnych
Rola Użytkownika wpisów tajnych usługi Key Vault na poziomie zakresu usługi Key Vault dla maszyn wirtualnych i tożsamości zarządzanej usługi Azure Virtual Machine Scale Sets. Ta rola pobiera część wpisu tajnego certyfikatu. Aby uzyskać więcej informacji, zobacz następujące artykuły:
Zestaw skalowania maszyn wirtualnych powinien mieć następujące ustawienie tożsamości: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
Rozszerzenie AKV powinno mieć to ustawienie: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Wersja rozszerzenia maszyny wirtualnej usługi Key Vault

Użytkownicy mogą zdecydować się na uaktualnienie wersji rozszerzenia maszyny wirtualnej usługi Key Vault, aby V2.0 użyć funkcji pobierania pełnego łańcucha certyfikatów. Certyfikaty wystawcy (pośrednie i główne) są dołączone do certyfikatu liścia w pliku PEM.
Jeśli wolisz przeprowadzić uaktualnienie v2.0do programu , musisz najpierw usunąć v1.0 element , a następnie zainstalować program 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 --version 2.0 jest opcjonalna, ponieważ najnowsza wersja jest instalowana domyślnie.

Jeśli maszyna wirtualna ma certyfikaty pobrane przez 1.0, usunięcie rozszerzenia AKVVM w wersji 1.0 nie spowoduje usunięcia pobranych certyfikatów. Po zainstalowaniu wersji 2.0 istniejące certyfikaty nie są modyfikowane. Aby uzyskać plik PEM z pełnym łańcuchem na maszynie wirtualnej, należy usunąć pliki certyfikatu lub przerzucić go.

Schemat rozszerzenia

Poniższy kod JSON przedstawia schemat rozszerzenia maszyny wirtualnej usługi Key Vault. Rozszerzenie nie wymaga ustawień chronionych — wszystkie jego ustawienia są uznawane za informacje bez wpływu na zabezpieczenia. Rozszerzenie wymaga listy monitorowanych wpisów tajnych, częstotliwości sondowania i docelowego magazynu certyfikatów. Szczególnie:

    {
      "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".>
        }
       }
      }
    }

Uwaga

Obserwowane adresy URL certyfikatów powinny mieć postać https://myVaultName.vault.azure.net/secrets/myCertName.

Jest to spowodowane tym, że /secrets ścieżka zwraca pełny certyfikat, w tym klucz prywatny, a /certificates ścieżka nie. Więcej informacji na temat certyfikatów można znaleźć tutaj: Certyfikaty usługi Key Vault

Ważne

Właściwość "authentication Ustawienia" jest wymagana dla maszyn wirtualnych z dowolnymi tożsamościami przypisanymi przez użytkownika. Nawet jeśli chcesz użyć tożsamości przypisanej przez system, nadal jest to wymagane. W przeciwnym razie rozszerzenie maszyny wirtualnej nie wie, której tożsamości użyć. Bez tej sekcji maszyna wirtualna z tożsamościami przypisanymi przez użytkownika spowoduje niepowodzenie rozszerzenia usługi Key Vault i brak możliwości pobrania certyfikatów. Ustaw wartość msiClientId na tożsamość, która będzie uwierzytelniana w usłudze Key Vault.

Wymagane również dla maszyn wirtualnych z obsługą usługi Azure Arc. Ustaw wartość msiEndpoint na http://localhost:40342/metadata/identity.

Wartości właściwości

Nazwisko	Wartość / przykład	Typ danych
apiVersion	2022-07-01	data
Wydawca	Microsoft.Azure.KeyVault	string
type	KeyVaultForLinux	string
typeHandlerVersion	2.0	int
pollingIntervalInS	3600	string
certificateStoreName	Jest on ignorowany w systemie Linux	string
linkOnRenewal	fałsz	boolean
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	string
requireInitialSync	prawda	boolean
obserwowaneCertyfikaty	["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]	tablica ciągów
msiEndpoint	http://169.254.169.254/metadata/identity	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

Wdrażanie na podstawie szablonu

Rozszerzenia maszyn wirtualnych platformy Azure można wdrażać za pomocą szablonów usługi Azure Resource Manager. Szablony są idealne podczas wdrażania co najmniej jednej maszyny wirtualnej, które wymagają po wdrożeniu odświeżania certyfikatów. Rozszerzenie można wdrożyć na poszczególnych maszynach wirtualnych lub w zestawach skalowania maszyn wirtualnych. Schemat i konfiguracja są wspólne dla obu typów szablonów.

Konfiguracja JSON rozszerzenia maszyny wirtualnej musi być zagnieżdżona wewnątrz fragmentu zasobu maszyny wirtualnej szablonu, w szczególności "resources": [] obiektu dla szablonu maszyny wirtualnej i zestawu skalowania maszyn wirtualnych w obszarze "virtualMachineProfile":"extensionProfile":{"extensions" :[] obiektu.

Uwaga

Rozszerzenie maszyny wirtualnej wymagałoby przypisania tożsamości zarządzanej przez system lub użytkownika w celu uwierzytelnienia w magazynie kluczy. Zobacz Jak uwierzytelniać się w usłudze Key Vault i przypisywać zasady dostępu usługi Key Vault.

    {
      "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"
        }
      }
      }
    }

Kolejność zależności rozszerzenia

Rozszerzenie maszyny wirtualnej usługi Key Vault obsługuje kolejność rozszerzeń w przypadku skonfigurowania. Domyślnie rozszerzenie zgłasza pomyślne rozpoczęcie od razu po rozpoczęciu sondowania. Można jednak skonfigurować ją tak, aby czekała, aż pomyślnie pobierze pełną listę certyfikatów przed pomyślnym rozpoczęciem. Jeśli inne rozszerzenia zależą od zainstalowanych certyfikatów przed rozpoczęciem, włączenie tego ustawienia umożliwi tym rozszerzeń zadeklarowanie zależności od rozszerzenia usługi Key Vault. Uniemożliwi to uruchamianie tych rozszerzeń do momentu zainstalowania wszystkich certyfikatów, od których zależą. Rozszerzenie ponowi próbę początkowego pobrania na czas nieokreślony i pozostanie w Transitioning stanie.

Aby włączyć zależność rozszerzenia, ustaw następujące ustawienia:

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

Uwaga

Użycie tej funkcji nie jest zgodne z szablonem usługi ARM, który tworzy tożsamość przypisaną przez system i aktualizuje zasady dostępu usługi Key Vault za pomocą tej tożsamości. Spowoduje to zakleszczenie, ponieważ zasady dostępu do magazynu nie zostaną zaktualizowane do momentu uruchomienia wszystkich rozszerzeń. Zamiast tego przed wdrożeniem należy użyć tożsamości tożsamości usługi zarządzanej przypisanej przez jednego użytkownika i listy ACL magazynów z tej tożsamości.

Wdrażanie programu Azure PowerShell

Ostrzeżenie

Klienci programu PowerShell często dodają \ element do " settings.json, co spowoduje niepowodzenie akvvm_service z błędem: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Za pomocą programu Azure PowerShell można wdrożyć rozszerzenie maszyny wirtualnej usługi Key Vault na istniejącej maszynie wirtualnej lub zestawie skalowania maszyn wirtualnych.

Aby wdrożyć rozszerzenie na maszynie wirtualnej:

    # 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

Aby wdrożyć rozszerzenie w zestawie skalowania maszyn wirtualnych:


    # 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

Wdrożenie za pomocą interfejsu wiersza polecenia platformy Azure

Interfejs wiersza polecenia platformy Azure może służyć do wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault do istniejącej maszyny wirtualnej lub zestawu skalowania maszyn wirtualnych.

Aby wdrożyć rozszerzenie na maszynie wirtualnej:

   # 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> \"] }}'

Aby wdrożyć rozszerzenie w zestawie skalowania maszyn wirtualnych:

      # 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> \"] }}'

Należy pamiętać o następujących ograniczeniach/wymaganiach:

Ograniczenia usługi Key Vault:
- Musi istnieć w momencie wdrożenia
- Zasady dostępu usługi Key Vault muszą być ustawione dla tożsamości vm/VMSS przy użyciu tożsamości zarządzanej. Zobacz How to Authenticate to Key Vault (Jak uwierzytelniać się w usłudze Key Vault) i Assign a Key Vault access policy (Przypisywanie zasad dostępu do usługi Key Vault).

Rozwiązywanie problemów i pomoc techniczna

Dane dotyczące stanu wdrożeń rozszerzeń można pobrać z witryny Azure Portal i przy użyciu programu Azure PowerShell. Aby wyświetlić stan wdrożenia rozszerzeń dla danej maszyny wirtualnej, uruchom następujące polecenie przy użyciu programu Azure PowerShell.

Azure PowerShell

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

Interfejs wiersza polecenia platformy Azure

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

Interfejs wiersza polecenia platformy Azure może działać w kilku środowiskach powłoki, ale z niewielkimi odmianami formatu. Jeśli masz nieoczekiwane wyniki za pomocą poleceń interfejsu wiersza polecenia platformy Azure, zobacz Jak pomyślnie używać interfejsu wiersza polecenia platformy Azure.

Dzienniki i konfiguracja

Dzienniki rozszerzenia maszyny wirtualnej usługi Key Vault istnieją tylko lokalnie na maszynie wirtualnej i są najbardziej informacyjne, jeśli chodzi o rozwiązywanie problemów.

Lokalizacja	opis
/var/log/waagent.log	Pokazuje, kiedy wystąpiła aktualizacja rozszerzenia.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	Sprawdź dzienniki usługi rozszerzenia maszyny wirtualnej usługi Key Vault, aby określić stan pobierania usługi akvvm_service i certyfikatu. Lokalizację pobierania plików PEM można znaleźć w plikach z wpisem o nazwie nazwa pliku certyfikatu. Jeśli parametr certificateStoreLocation nie zostanie określony, wartość domyślna to /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-najnowsza< wersja>/config/*	Konfiguracja i pliki binarne dla usługi rozszerzenia maszyny wirtualnej usługi Key Vault.

Korzystanie z funkcji Symlink

Linki symboliczne lub linki Symlinki to zaawansowane skróty. Aby uniknąć automatycznego monitorowania folderu i pobierania najnowszego certyfikatu, możesz użyć tego linku symlinku ([VaultName].[CertificateName]) , aby uzyskać najnowszą wersję certyfikatu w systemie Linux.

Często zadawane pytania

Czy istnieje limit liczby obserwowanychcertyfikatów, które można skonfigurować? Nie, rozszerzenie maszyny wirtualnej usługi Key Vault nie ma limitu liczby obserwowanychcertyfikatów.

Pomoc techniczna

Jeśli potrzebujesz więcej pomocy w dowolnym momencie tego artykułu, możesz skontaktować się z ekspertami platformy Azure na forach MSDN Azure i Stack Overflow. Alternatywnie możesz zgłosić zdarzenie pomoc techniczna platformy Azure. Przejdź do witryny pomoc techniczna platformy Azure i wybierz pozycję Uzyskaj pomoc techniczną. Aby uzyskać informacje na temat korzystania z pomocy technicznej platformy Azure, zapoznaj się z często zadawanymi pytaniami dotyczącymi usługi Microsoft pomoc techniczna platformy Azure.

Rozszerzenie maszyny wirtualnej usługi Key Vault dla systemu Linux

System operacyjny

Obsługiwane typy zawartości certyfikatów

Wymagania wstępne

Wersja rozszerzenia maszyny wirtualnej usługi Key Vault

Schemat rozszerzenia

Wartości właściwości

Wdrażanie na podstawie szablonu

Kolejność zależności rozszerzenia

Wdrażanie programu Azure PowerShell

Wdrożenie za pomocą interfejsu wiersza polecenia platformy Azure

Rozwiązywanie problemów i pomoc techniczna

Dzienniki i konfiguracja

Korzystanie z funkcji Symlink

Często zadawane pytania

Pomoc techniczna

Dodatkowe zasoby