Rozszerzenie maszyny wirtualnej usługi Key Vault dla systemu Linux
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.0
do programu , musisz najpierw usunąćv1.0
element , a następnie zainstalować programv2.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.