Udostępnij za pośrednictwem

Rozszerzenie maszyny wirtualnej usługi Key Vault dla systemu Linux

  • Artykuł

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:

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 (wersja 1/2) lub poszczególnych ustawień certyfikatu (wersja 3). 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

Aktualizacje w wersji 3.0 lub nowszej

Wersja 3.0 lub nowsza rozszerzenia maszyny wirtualnej usługi Key Vault dla systemu Linux dodaje obsługę następujących funkcji:

  • Dodawanie uprawnień listy ACL dla pobranych certyfikatów w celu zapewnienia dostępu do odczytu dla użytkowników i grup
  • Konfiguracja lokalizacji instalacji certyfikatu
  • Obsługa niestandardowych nazw symbolicznych
  • Obsługa integracji rejestrowania rozszerzeń maszyn wirtualnych za pośrednictwem usługi Fluentd

Wymagania wstępne

Wersja rozszerzenia maszyny wirtualnej usługi Key Vault

  • Użytkownicy mogą zdecydować się na uaktualnienie istniejącej wersji rozszerzenia maszyny wirtualnej usługi Key Vault do nowszej wersji.

  • Jeśli wolisz uaktualnić do nowszej wersji, musisz najpierw usunąć poprzednią wersję, a następnie zainstalować nowszą wersję.

  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

Flaga --version 3.0 jest opcjonalna, ponieważ najnowsza wersja jest instalowana domyślnie.

  • Jeśli maszyna wirtualna ma certyfikaty pobrane przez poprzednią wersję, usunięcie rozszerzenia maszyny wirtualnej nie spowoduje usunięcia pobranych certyfikatów. Po zainstalowaniu nowszej wersji istniejące certyfikaty nie zostaną zmodyfikowane. 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": "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".>
        }>
       }
      }
    }

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ść "authenticationSettings" 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
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3.0 int
pollingIntervalInS 3600 string
certificateStoreName Jest on ignorowany w systemie Linux string
linkOnRenewal fałsz boolean
requireInitialSync prawda boolean
aclEnabled prawda boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] tablica ciągów
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName (opcjonalny) "app1Cert1" string
observedCertificates/acls (opcjonalny) "{...}, {...}" tablica ciągów
authenticationSettings (opcjonalny) {...} obiekt
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings (opcjonalny) {...} obiekt
loggingSettings/logger "Fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "do przodu" string
loggingSettings/servicename "akvvm_service" 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": "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">
          }
        } 
      }
    }

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 raportowaniem pomyślnego uruchomienia. 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:

Rozszerzenie maszyny wirtualnej usługi Azure Key Vault można wdrożyć za pomocą programu Azure PowerShell. Zapisz ustawienia rozszerzenia maszyny wirtualnej usługi Key Vault w pliku JSON (settings.json).

Poniższe fragmenty kodu JSON zawierają przykładowe ustawienia wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault za pomocą programu PowerShell.

{
   "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"
   }      
}
  • Aby wdrożyć rozszerzenie 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 "3.0" -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 = (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

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:

Rozszerzenie maszyny wirtualnej usługi Azure Key Vault można wdrożyć przy użyciu interfejsu wiersza polecenia platformy Azure. Zapisz ustawienia rozszerzenia maszyny wirtualnej usługi Key Vault w pliku JSON (settings.json).

Poniższe fragmenty kodu JSON zawierają przykładowe ustawienia wdrażania rozszerzenia maszyny wirtualnej usługi Key Vault przy użyciu interfejsu wiersza polecenia platformy Azure.

{
   "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"
   }      
}
  • 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 3.0 `
      --enable-auto-upgrade true `
      --settings "@settings.json"
  • 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 3.0 `
    --enable-auto-upgrade true `
    --settings "@settings.json"

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

  • Ograniczenia usługi Key Vault:
    • Musi istnieć w momencie wdrożenia
    • Rola Użytkownika wpisów tajnych usługi Key Vault musi być przypisana do usługi Key Vault na potrzeby tożsamości maszyny wirtualnej

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ą lokalnie na maszynie wirtualnej i są najbardziej informacyjne, jeśli chodzi o rozwiązywanie problemów. Możesz użyć opcjonalnej sekcji rejestrowania, aby zintegrować się z dostawcą rejestrowania za pośrednictwem fluentd

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.

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.