rozszerzenie maszyny wirtualnej Azure Key Vault dla systemu Linux

Rozszerzenie maszyny wirtualnej Azure Key Vault automatycznie odświeża certyfikaty przechowywane w Azure key vault. Rozszerzenie monitoruje listę obserwowanych certyfikatów przechowywanych w magazynach kluczy. Gdy rozszerzenie wykryje zmianę, pobiera i instaluje odpowiednie certyfikaty. W tym artykule opisano obsługiwane platformy, konfiguracje i opcje wdrażania dla rozszerzenia maszyny wirtualnej Key Vault dla systemu Linux.

Uwaga

Wypróbuj pomoc maszyny wirtualnej, aby uzyskać szybszą diagnostykę. Zalecamy uruchomienie asysty VM dla Windows lub VM assist for Linux. Te narzędzia diagnostyczne oparte na skryptach ułatwiają identyfikowanie typowych problemów, które mają wpływ na agenta gościa maszyny wirtualnej Azure i ogólną kondycję maszyny wirtualnej.

Jeśli występują problemy z wydajnością maszyn wirtualnych, przed skontaktowaniem się z pomocą techniczną uruchom te narzędzia.

Systemy operacyjne

Rozszerzenie maszyny wirtualnej Key Vault dla systemu Linux obsługuje następujące dystrybucje, zarówno w przypadku procesorów AMD64, jak i ARM64:

  • Ubuntu 24.04
  • Azure Linux 3.0 i 4.0
  • Red Hat Enterprise Linux (RHEL) 9

Uwaga

Rozszerzenie podczas instalacji wybiera z /etc/os-release plik binarny odpowiedni dla danej dystrybucji. Instalacja w dowolnej innej dystrybucji kończy się niepowodzeniem z powodu błędu "dystrybucja nie jest obsługiwana", który pojawia się w stanie rozszerzenia.

Obsługiwane typy zawartości certyfikatów

Rozszerzenie maszyny wirtualnej usługi Key Vault obsługuje następujące typy zawartości certyfikatów:

  • PKCS #12
  • PEM

Uwaga

Rozszerzenie maszyny wirtualnej usługi Key Vault pobiera wszystkie certyfikaty do lokalizacji określonej we właściwości certificateStoreLocation w ustawieniach rozszerzenia maszyny wirtualnej lub do domyślnej lokalizacji magazynu /var/lib/waagent/Microsoft.Azure.KeyVault.Store/, jeśli nie określisz lokalizacji.

Funkcje

Rozszerzenie maszyny wirtualnej Key Vault dla systemu Linux w wersji 4.x:

  • Instaluje dwie najnowsze wersje każdego certyfikatu.
  • Instaluje każdy certyfikat jako oddzielne pliki: plik pełnego łańcucha .pem oraz oddzielny plik klucza prywatnego .keyid, przy czym każdy z nich jest zapisywany jako plik z numerem wersji i ma stabilne łącze symboliczne wskazujące na najnowszą wersję.
  • Przeprowadza walidację łańcucha certyfikatów przed zainstalowaniem dowolnego certyfikatu, który przenosi rozszerzone użycie klucza uwierzytelniania serwera TLS (EKU). Walidacja kończy się niepowodzeniem: certyfikat jest nadal instalowany, jeśli walidacja nie może zostać ukończona z powodu przejściowych problemów z siecią. Certyfikaty bez EKU uwierzytelniania serwera nie podlegają tej kontroli.
  • Stosuje listy ACL POSIX, aby przyznać skonfigurowanym użytkownikom i grupom prawo odczytu klucza prywatnego. Egzekwowanie list ACL jest zawsze włączone.
  • Obsługuje opcjonalne zastąpienie ustawień uwierzytelniania dla poszczególnych certyfikatów, co umożliwia poszczególnym monitorowanym certyfikatom uwierzytelnianie względem usługi Key Vault przy użyciu innej tożsamości zarządzanej niż domyślna tożsamość zarządzana rozszerzenia. Aby uzyskać więcej informacji, zobacz Schemat rozszerzenia.
  • Obsługuje integrację rejestrowania rozszerzeń maszyn wirtualnych za pośrednictwem rozwiązania Fluentd. Aby uzyskać więcej informacji, zobacz Rejestrowanie za pomocą biblioteki Fluentd.

Uaktualnianie z wersji 3.0

Jeśli aktualizujesz z wersji 3.0, następujące funkcje zostaną zmienione lub usunięte.

Ogólne zmiany powodujące niezgodność:

  • pollingIntervalInS Jest teraz ograniczona do 5–60 minut. Domyślnie rozszerzenie sprawdza co godzinę.
  • requireInitialSync jest usunięte. Rozszerzenie zgłasza powodzenie tylko wtedy, gdy instaluje wszystkie skonfigurowane certyfikaty.
  • Nie można już skonfigurować określonej wersji certyfikatu. Obserwowane adresy URL certyfikatów muszą być bez wersji.
  • Starszy schemat, w którym observedCertificates znajduje się lista ciągów adresu URL, nie jest już obsługiwany. Każdy wpis musi być obiektem z właściwością url .

Zmiany powodujące niezgodność specyficzne dla systemu Linux:

  • Łańcuch certyfikatów i klucz prywatny są teraz zapisywane w oddzielnych plikach. W wersji 3.0 pełny łańcuch i klucz prywatny zostały połączone w jeden plik PEM. W wersji 4.x rozszerzenie zapisuje pełny łańcuch do <vaultname>.<certname>.pem i klucz prywatny do oddzielnego <vaultname>.<certname>.keyid pliku. Ta zmiana powoduje niezgodność: aplikacje, które oczekują klucza i łańcucha w jednym pliku, muszą zostać zaktualizowane tak, aby odczytywały łańcuch z pliku .pem, a klucz prywatny z pliku .keyid. Plik .luma jest aktualizowany po zaktualizowaniu linków symbolicznych, dlatego aplikacje powinny monitorować zmiany w tym pliku metadanych.
  • customSymbolicLinkName jest usunięte. Rozszerzenie zawsze używa domyślnej nazwy łącza symbolicznego <vaultname>.<certname>.
  • aclEnabled jest usunięte. Funkcja ACL jest teraz zawsze włączona.
  • certificateStoreName jest ignorowany w systemie Linux i nie ma wpływu.

Uwaga

Uaktualnienie z poprzedniej wersji rozszerzenia nie powoduje usunięcia certyfikatów, które zostały już pobrane na dysk. Ponadto 4.x używa innego formatu nazwy pliku, więc wszystkie istniejące pliki pozostają nienaruszone.

Wymagania wstępne

Zapoznaj się z następującymi wymaganiami wstępnymi dotyczącymi używania rozszerzenia maszyny wirtualnej Key Vault dla systemu Linux:

  • Instancja Azure Key Vault z certyfikatem. Aby uzyskać więcej informacji, zobacz Tworzenie magazynu kluczy przy użyciu portalu Azure.

  • Maszyna wirtualna z przypisaną tożsamością zarządzaną.

  • Przypisz rolę Użytkownik wpisów tajnych usługi Key Vault na poziomie zakresu usługi Key Vault do tożsamości zarządzanej maszyny wirtualnej lub zestawów skalowania maszyn wirtualnych platformy Azure. Ta rola pobiera tajną część certyfikatu. Aby uzyskać więcej informacji, zobacz następujące artykuły:

  • Skonfiguruj zestawy skalowania maszyn wirtualnych przy użyciu następującej konfiguracji identity:

    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
           "[parameters('userAssignedIdentityResourceId')]": {}
        }
    }
    
  • Skonfiguruj rozszerzenie maszyny wirtualnej Key Vault przy użyciu następującej authenticationSettings konfiguracji:

    "authenticationSettings": {
        "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
        "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
    }
    

Uwaga

Możesz również użyć starego modelu uprawnień opartego na zasadach dostępu, aby przyznać dostęp do maszyn wirtualnych i zestawów skalowania maszyn wirtualnych. Ta metoda wymaga zasad z uprawnieniami get i list dla kluczy tajnych. Aby uzyskać więcej informacji, zobacz Przypisywanie zasad dostępu do usługi Key Vault.

Schemat rozszerzenia

Poniższy kod JSON przedstawia schemat rozszerzenia maszyny wirtualnej usługi Key Vault. Przed rozważenie opcji implementacji schematu zapoznaj się z następującymi ważnymi uwagami.

  • Rozszerzenie nie wymaga ustawień chronionych. Wszystkie ustawienia są informacjami publicznymi.

  • Obserwowane adresy URL certyfikatów muszą używać formularza https://myVaultName.vault.azure.net/secrets/myCertName.

    Ten formularz jest wymagany, ponieważ /secrets ścieżka zwraca pełny certyfikat, w tym klucz prywatny, ale /certificates ścieżka nie. Aby uzyskać więcej informacji na temat certyfikatów, zobacz Omówienie kluczy, wpisów tajnych i certyfikatów usługi Azure Key Vault. Nie można określić określonej wersji certyfikatu.

  • Host adresu URL musi być rozpoznanym hostem Azure Key Vault.

  • Właściwość jest wymaganaauthenticationSettings dla maszyn wirtualnych z dowolnymi tożsamościami przypisanymi przez użytkownika oraz dla maszyn wirtualnych z obsługą Azure Arc.

    Pomiń tę właściwość podczas korzystania z tożsamości przypisanej przez system. W przypadku maszyn wirtualnych z obsługą usługi Azure Arc ustaw msiEndpoint na http://localhost:40342/metadata/identity.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <Optional. Polling interval in seconds, between 300 (5 min) and 3600 (60 min). Example: "3600">,
             "certificateStoreLocation": <Optional. Default disk path where certificates are stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
             "observedCertificates": <An array of Key Vault URIs that represent monitored certificates, including per-certificate store location and ACL permissions on the 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 disk path where the certificate is stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "acls": <Optional. An array of users and groups to grant read access to the certificate private key. Example:
                    [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Wartości właściwości

Schemat JSON zawiera następujące właściwości.

Nazwa Wartość/przykład Typ danych
apiVersion 2025-04-01 termin
publisher Microsoft. Azure. KeyVault ciąg
type KeyVaultForLinux ciąg
typeHandlerVersion "4.0" ciąg
pollingIntervalInS (opcjonalny) "3600" (ograniczone do zakresu 300–3600) ciąg
certificateStoreLocation (opcjonalny) "/var/lib/waagent/Microsoft.Azure. KeyVault.Store" ciąg
observedCertificates [{...}, {...}] macierz
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate" ciąg
observedCertificates/certificateStoreLocation (opcjonalny) "/var/lib/waagent/Microsoft. Azure. KeyVault/app1" ciąg
observedCertificates/acls (opcjonalny) [{"user": "app1", "group": "appGroup1"}] tablica obiektów
observedCertificates/authenticationOverride (opcjonalny) {"msiClientId": "00001111-aaaa-2222-bbbb-3333cc4444"} obiekt
authenticationSettings/msiEndpoint "http://169.254.169.254/metadata/identity" ciąg
authenticationSettings/msiClientId "00001111-aaaa-2222-bbbb-3333cccc44444" ciąg

Uwaga

Schemat akceptuje certificateStoreName dla zachowania zgodności, ale system Linux je ignoruje. Jeśli nie określisz elementu certificateStoreLocation dla certyfikatu, system użyje secretsManagementSettings.certificateStoreLocation najwyższego poziomu, a jeśli ten nie jest ustawiony, użyje domyślnego /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Template deployment

Wdrażanie rozszerzeń maszyn wirtualnych Azure przy użyciu szablonów Azure Resource Manager (ARM). Szablony są idealne podczas wdrażania co najmniej jednej maszyny wirtualnej, która wymaga odświeżania certyfikatów po wdrożeniu. Rozszerzenie można wdrożyć do poszczególnych maszyn wirtualnych lub wystąpień zestawów skalowania maszyn wirtualnych. Schemat i konfiguracja są wspólne dla obu typów szablonów.

Konfiguracja JSON rozszerzenia skarbca kluczy jest zagnieżdżona wewnątrz szablonu maszyny wirtualnej lub zestawów skalowania maszyn wirtualnych. W przypadku rozszerzenia zasobu maszyny wirtualnej konfiguracja jest zagnieżdżona pod obiektem "resources": [] maszyny wirtualnej. W przypadku rozszerzenia wystąpienia usługi Virtual Machine Scale Sets konfiguracja jest zagnieżdżona pod obiektem "virtualMachineProfile":"extensionProfile":{"extensions" :[] .

Poniższy fragment JSON zawiera przykładowe ustawienia wdrożenia szablonu ARM dla rozszerzenia maszyny wirtualnej usługi Key Vault.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": "3600",
             "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
             "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"
                }
             ]
         },
         "authenticationSettings": {
            "msiEndpoint":  "http://169.254.169.254/metadata/identity",
            "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
         }
      }
   }
}

Automatyczna aktualizacja rozszerzenia

Rozszerzenie maszyny wirtualnej Key Vault obsługuje automatyczne uaktualnianie rozszerzeń dla maszyn wirtualnych i zestawów skalowania w Azure. Azure automatycznie aktualizuje rozszerzenie, gdy we wcześniejszych przykładach ustawisz właściwości autoUpgradeMinorVersion i enableAutomaticUpgrade na true.

Porządkowanie zależności rozszerzeń

Rozszerzenie maszyny wirtualnej Key Vault obsługuje kolejność zależności rozszerzeń. Rozszerzenie zgłasza pomyślny start po pobraniu i zainstalowaniu wszystkich certyfikatów.

Jeśli używasz innych rozszerzeń, które wymagają instalacji certyfikatów przed ich uruchomieniem, możesz użyć kolejności zależności rozszerzenia, aby zadeklarować zależność od rozszerzenia maszyny wirtualnej Key Vault.

Przy uruchomieniu rozszerzenie maszyny wirtualnej Key Vault ponawia próbę pobierania i instalowania certyfikatów do 25 razy z rosnącymi przerwami między próbami, podczas których pozostaje w stanie Transitioning. Jeśli próby ponowienia zostaną wyczerpane, rozszerzenie zgłasza tryb Błąd. Po pomyślnym zainstalowaniu wszystkich certyfikatów rozszerzenie maszyny wirtualnej usługi Key Vault zgłasza pomyślny start.

Aby uzyskać więcej informacji na temat konfigurowania zależności między rozszerzeniami, zobacz Sekwencyjne aprowizowanie rozszerzeń w Virtual Machine Scale Sets.

Ważne

Funkcja kolejności zależności rozszerzenia nie jest zgodna z szablonem ARM, który tworzy tożsamość przypisaną przez system i aktualizuje zasady dostępu Key Vault używając tej tożsamości. Jeśli spróbujesz użyć funkcji w tym scenariuszu, występuje zakleszczenie, ponieważ zasady dostępu usługi Key Vault nie mogą być aktualizowane dopiero po uruchomieniu wszystkich rozszerzeń. Zamiast tego należy użyć tożsamości zarządzanej przypisanej przez jednego użytkownika i przyznać tej tożsamości dostęp do magazynów kluczy przed wdrożeniem.

wdrażanie Azure PowerShell

Wdróż rozszerzenie maszyny wirtualnej Azure Key Vault przy użyciu Azure PowerShell. Zapisz ustawienia rozszerzenia maszyny wirtualnej Key Vault w pliku JSON (settings.json).

Ostrzeżenie

Klienci PowerShell często dodają \ przed " w pliku settings.json. To zachowanie powoduje, że akvvm_service kończy się niepowodzeniem z błędem [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.. Użyj Azure CLI lub przekaż ustawienia jako nieprzetworzonego ciągu, jak pokazano w poniższym przykładzie.

Poniższy fragment kodu JSON zawiera przykładowe ustawienia wdrażania rozszerzenia maszyny wirtualnej Key Vault przy użyciu programu PowerShell.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Wdrażanie na maszynie wirtualnej

# Build settings
$settings = (Get-Content -Raw ".\settings.json")
$extName =  "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"

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

Wdrażanie na instancji Virtual Machine Scale Sets

# 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 "4.0" -Setting $settings

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

wdrażanie Azure CLI

Wdróż rozszerzenie maszyny wirtualnej Azure Key Vault przy użyciu Azure CLI. Zapisz ustawienia rozszerzenia maszyny wirtualnej Key Vault w pliku JSON (settings.json).

Poniższy fragment kodu JSON zawiera przykładowe ustawienia wdrażania rozszerzenia maszyny wirtualnej Key Vault przy użyciu Azure CLI.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Wdrażanie na maszynie wirtualnej

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Wdrażanie na instancji Virtual Machine Scale Sets

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Wskazówka

Jeśli wdrożenie rozszerzenia zakończy się niepowodzeniem, może być konieczne usunięcie istniejącego rozszerzenia przed ponowną instalacją z poprawną wersją. Azure nie zezwala na obniżenie poziomu rozszerzenia, dlatego najpierw może być konieczne usunięcie wadliwego rozszerzenia:

az vm extension delete --name "KeyVaultForLinux" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Rejestrowanie za pomocą Fluentd

Rozszerzenie maszyny wirtualnej Key Vault może przekazywać dzienniki do modułu zbierającego dzienniki Fluentd. Upewnij się, że moduł zbierający dzienniki jest uruchomiony i nasłuchuje w punkcie końcowym określonym w ustawieniach.

Dodaj następującą sekcję do ustawień rozszerzenia:

"loggingSettings": {
   "logger": "fluentd",
   "endpoint": "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket",
   "format": "forward",
   "servicename": "akvvm_service"
}
Nazwa Wartość/przykład Typ danych
loggingSettings/logger "Fluentd" ciąg
loggingSettings/endpoint "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket" lub "tcp://localhost:24224" ciąg
loggingSettings/format "do przodu" ciąg
loggingSettings/servicename "akvvm_service" ciąg

Rozwiązywanie problemów

Skorzystaj z tych sugestii, aby rozwiązać problemy z wdrażaniem.

Sprawdź często zadawane pytania

Czy istnieje limit liczby obserwowanych certyfikatów?

Nie. Rozszerzenie maszyny wirtualnej usługi Key Vault nie ogranicza liczby obserwowanych certyfikatów (observedCertificates).

Jaka jest domyślna lokalizacja, w której są zainstalowane certyfikaty?

Jeśli nie określisz certificateStoreLocation, rozszerzenie zapisuje certyfikaty w lokalizacji /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Jak wymusić pobranie nowego certyfikatu przez rozszerzenie?

Uruchom ponownie usługę akvvm_service (nazwa wyświetlana: Key Vault VM Extension).

Jak używać innej tożsamości dla określonego certyfikatu?

Dodaj obiekt authenticationOverride z elementem docelowym msiClientId do wpisu tego certyfikatu w observedCertificates. Certyfikaty bez zastąpienia używają najwyższego poziomu authenticationSettings.

Wyświetlanie stanu rozszerzenia

Sprawdź stan wdrożenia rozszerzenia w portalu Azure lub przy użyciu programu PowerShell lub Azure CLI.

Aby wyświetlić stan wdrożenia rozszerzeń dla danej maszyny wirtualnej, uruchom następujące polecenia.

  • Azure PowerShell:

    Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
    
  • Interfejs wiersza polecenia platformy Azure:

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

Azure CLI można uruchamiać na różnych powłokach, ale z niewielkimi różnicami w formacie. Jeśli masz nieoczekiwane wyniki z poleceniami Azure CLI, zobacz Jak pomyślnie użyć Azure CLI.

Przeglądanie dzienników i konfiguracji

Dzienniki rozszerzenia VM usługi Key Vault istnieją tylko lokalnie na tej maszynie wirtualnej. Przejrzyj szczegóły dziennika, aby uzyskać pomoc dotyczącą rozwiązywania problemów.

Plik dziennika Opis
/var/log/waagent.log Pokazuje, kiedy występują aktualizacje rozszerzenia.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Pokazuje stan pobierania akvvm_service usługi i certyfikatu. Lokalizacja pobierania pliku PEM jest wyświetlana w pozycjach o nazwie nazwa pliku certyfikatu.
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/* Konfiguracja i pliki binarne dla usługi rozszerzenia maszyny wirtualnej Key Vault.

Instalacja certyfikatu w systemie Linux

Rozszerzenie maszyny wirtualnej Key Vault dla systemu Linux instaluje certyfikaty jako pliki PEM. Gdy rozszerzenie pobiera certyfikat z Key Vault, to:

  1. Tworzy folder przechowywania na podstawie ustawienia certificateStoreLocation. Jeśli to ustawienie nie zostanie określone, wartość domyślna lokalizacji to /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
  2. Zapisuje łańcuch certyfikatów (certyfikat końcowy, następnie certyfikaty pośrednie, a potem certyfikat główny, jeśli jest obecny w Key Vault) do wersjonowanego pliku pełnego łańcucha .pem, a odpowiadający mu klucz prywatny zapisuje do wersjonowanego pliku .keyid.
  3. Stosuje listy kontroli dostępu POSIX (ACL) do klucza prywatnego na podstawie wartości acls określonej w konfiguracji, co przyznaje wymienionym użytkownikom i grupom uprawnienia do odczytu. Poza tym pliki są dostępne tylko dla właściciela.
  4. Tworzy lub aktualizuje stabilny link symboliczny (<vaultname>.<certname>.pem i <vaultname>.<certname>.keyid), który wskazuje najnowszą wersję certyfikatu. Łączenie zawsze występuje.

Domyślna lokalizacja magazynu certyfikatów

Jeśli nie określisz lokalizacji, rozszerzenie instaluje certyfikaty w obszarze /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. Rozszerzenie ignoruje certificateStoreName w systemie Linux.

Pliki wyjściowe certyfikatu

Dla magazynu mykv i klucza tajnego server-tls pomyślna synchronizacja daje wynik:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── mykv.server-tls.pem -> mykv.server-tls.<version>.pem.<timestamp>     # symlink to latest full chain
├── mykv.server-tls.keyid -> mykv.server-tls.<version>.keyid.<timestamp> # symlink to latest private key
├── mykv.server-tls.<version>.pem.<timestamp>                            # full chain PEM (mode 600)
├── mykv.server-tls.<version>.keyid.<timestamp>                          # private key (mode 600)
└── mykv.server-tls.luma                                                 # certificate management metadata (mode 644)

Skonfiguruj aplikacje tak, aby odwoływały się do stabilnej ścieżki dowiązania symbolicznego (na przykład /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem), aby zawsze odczytywały najnowszą wersję certyfikatu bez ponownej konfiguracji po odnowieniu.

Kontrola dostępu do certyfikatu

Domyślnie pliki certyfikatu i klucza prywatnego można odczytywać tylko przez ich właściciela. Przyznaj uprawnienia do odczytu dodatkowym użytkownikom i grupom za pomocą tablicy acls w konfiguracji certyfikatu:

"acls": [
   { "user": "app1", "group": "appGroup1" },
   { "user": "service1" }
]

Każdy wpis może określać użytkownika, grupę lub oba te elementy. Egzekwowanie list ACL jest zawsze włączone i obecnie przyznaje dostęp do odczytu.

Odnawianie certyfikatu

Po odnowieniu certyfikatów w Key Vault rozszerzenie automatycznie wykonuje następujące akcje w następnej ankiecie:

  1. Pobiera nową wersję certyfikatu.
  2. Zapisuje nowe pliki z numerami wersji .pem i .keyid.
  3. Aktualizuje stabilny link symboliczny, aby wskazywał nową wersję, aby istniejące ścieżki aplikacji nadal rozpoznawały najnowszy certyfikat.

Uzyskaj pomoc techniczną

Microsoft zapewnia obsługę tylko wersji głównej 3.0 i nowszej rozszerzenia maszyny wirtualnej Key Vault. Jeśli używasz wersji 1.0, przed zażądaniem pomocy technicznej przeprowadź uaktualnienie do najnowszej wersji.

Użyj tych innych opcji, aby rozwiązać problemy z wdrażaniem: