Key Vault-extensie voor virtuele machines voor Linux

Artikel
02/20/2024

De Key Vault VM-extensie biedt automatische vernieuwing van certificaten die zijn opgeslagen in een Azure-sleutelkluis. Met name de extensie bewaakt een lijst met waargenomen certificaten die zijn opgeslagen in sleutelkluizen. De extensie haalt de bijbehorende certificaten op en installeert deze na het detecteren van een wijziging. In dit document worden de ondersteunde platforms, configuraties en implementatieopties voor de Key Vault-VM-extensie voor Linux beschreven.

Besturingssysteem

De Key Vault VM-extensie ondersteunt deze Linux-distributies:

Ubuntu 20.04, 22.04
Azure Linux

Notitie

De Key Vault VM-extensie downloadt de certificaten op de standaardlocatie of naar de locatie die wordt geleverd door de eigenschap certStoreLocation in de instellingen van de VM-extensie. De Key Vault-VM-extensie werkt de mapmachtiging bij naar 700 (drwx------) zodat alleen de eigenaar van de map kan lezen, schrijven en uitvoeren

Ondersteunde certificaatinhoudstypen

PKCS #12
PEM

Vereisten

Key Vault-exemplaar met certificaat. Zie Een sleutelkluis maken
Toegewezen beheerde identiteit op VM/VMSS
De key Vault-gebruikersrol Geheimen op het bereikniveau van Key Vault voor VM's en beheerde identiteit van Azure Virtual Machine Scale Sets. Met deze rol wordt het gedeelte van een certificaat van een geheim opgehaald. Raadpleeg voor meer informatie de volgende artikelen:
VMSS moet de volgende identiteitsinstelling hebben: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }
De AKV-extensie moet deze instelling hebben: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Versie van de Key Vault-VM-extensie

Gebruikers kunnen ervoor kiezen om hun versie van de Key Vault-VM-extensie te upgraden om V2.0 de volledige downloadfunctie voor certificaatketens te gebruiken. Certificaten van verleners (tussenliggend en basiscertificaat) zijn opgenomen in het PEM-bestand.
Als u liever een upgrade naar v2.0uitvoert, moet u eerst verwijderen v1.0 en vervolgens installeren 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

De vlag --versie 2.0 is optioneel omdat de nieuwste versie standaard is geïnstalleerd.

Als de VM certificaten bevat die zijn gedownload door v1.0, worden de gedownloade certificaten niet verwijderd door de AKVVM-extensie v1.0 te verwijderen. Na de installatie van v2.0 worden de bestaande certificaten niet gewijzigd. U moet de certificaatbestanden verwijderen of het certificaat overrollen om het PEM-bestand met volledige keten op de virtuele machine op te halen.

Extensieschema

In de volgende JSON ziet u het schema voor de Key Vault-VM-extensie. Voor de extensie zijn geen beveiligde instellingen vereist. Alle instellingen worden beschouwd als informatie zonder beveiligingsimpact. De extensie vereist een lijst met bewaakte geheimen, pollingfrequentie en het doelcertificaatarchief. Specifiek:

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

Notitie

De url's van de waargenomen certificaten moeten van het formulier https://myVaultName.vault.azure.net/secrets/myCertNamezijn.

Dit komt doordat het /secrets pad het volledige certificaat retourneert, inclusief de persoonlijke sleutel, terwijl het /certificates pad dat niet doet. Meer informatie over certificaten vindt u hier: Key Vault-certificaten

Belangrijk

De eigenschap 'verificatie Instellingen' is vereist voor VM's met een door de gebruiker toegewezen identiteiten. Zelfs als u een door het systeem toegewezen identiteit wilt gebruiken, is dit nog steeds vereist, anders weet de VM-extensie niet welke identiteit moet worden gebruikt. Zonder deze sectie leidt een VIRTUELE machine met door de gebruiker toegewezen identiteiten ertoe dat de Key Vault-extensie mislukt en geen certificaten kan downloaden. Stel msiClientId in op de identiteit die wordt geverifieerd bij Key Vault.

Ook vereist voor vm's met Azure Arc. Stel msiEndpoint in op http://localhost:40342/metadata/identity.

Eigenschapswaarden

Naam	Waarde/voorbeeld	Gegevenstype
apiVersion	2022-07-01	datum
Publisher	Microsoft.Azure.KeyVault	tekenreeks
type	KeyVaultForLinux	tekenreeks
typeHandlerVersion	2.0	int
pollingIntervalInS	3600	tekenreeks
certificateStoreName	Het wordt genegeerd in Linux	tekenreeks
linkOnRenewal	false	boolean
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	tekenreeks
requireInitialSync	true	boolean
observedCertificates	["https://myvault.vault.azure.net/secrets/mycertificate"; "https://myvault.vault.azure.net/secrets/mycertificate2"]	tekenreeksmatrix
msiEndpoint	http://169.254.169.254/metadata/identity	tekenreeks
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	tekenreeks

Sjabloonimplementatie

Azure VM-extensies kunnen worden geïmplementeerd met Azure Resource Manager-sjablonen. Sjablonen zijn ideaal bij het implementeren van een of meer virtuele machines waarvoor het vernieuwen van certificaten na de implementatie is vereist. De extensie kan worden geïmplementeerd op afzonderlijke VM's of virtuele-machineschaalsets. Het schema en de configuratie zijn gebruikelijk voor beide sjabloontypen.

De JSON-configuratie voor een virtuele-machineextensie moet zijn genest in het resourcefragment van de virtuele machine van de sjabloon, met name "resources": [] het object voor de virtuele-machinesjabloon en voor een virtuele-machineschaalset onder "virtualMachineProfile":"extensionProfile":{"extensions" :[] object.

Notitie

Voor de VM-extensie moet een door het systeem of door de gebruiker beheerde identiteit worden toegewezen om te worden geverifieerd bij Key Vault. Zie Verifiëren bij Key Vault en een Key Vault-toegangsbeleid toewijzen.

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

Volgorde van uitbreidingsafhankelijkheid

De Key Vault-VM-extensie biedt ondersteuning voor het bestellen van extensies als deze is geconfigureerd. De extensie rapporteert standaard dat de start is voltooid zodra de polling wordt gestart. U kunt deze echter configureren om te wachten totdat de volledige lijst met certificaten is gedownload voordat een geslaagde start wordt gerapporteerd. Als andere extensies afhankelijk zijn van geïnstalleerde certificaten voordat ze worden gestart, staat het inschakelen van deze extensies toe dat deze extensies een afhankelijkheid van de Key Vault-extensie declareren. Hiermee voorkomt u dat deze extensies worden gestart totdat alle certificaten waarvoor ze afhankelijk zijn, zijn geïnstalleerd. De extensie voert de eerste download voor onbepaalde tijd opnieuw uit en blijft in een Transitioning status.

Als u uitbreidingsafhankelijkheid wilt inschakelen, stelt u het volgende in:

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

Notitie

Het gebruik van deze functie is niet compatibel met een ARM-sjabloon waarmee een door het systeem toegewezen identiteit wordt gemaakt en een Key Vault-toegangsbeleid met die identiteit wordt bijgewerkt. Als u dit doet, ontstaat er een impasse omdat het toegangsbeleid voor de kluis pas kan worden bijgewerkt als alle extensies zijn gestart. Gebruik in plaats daarvan één door de gebruiker toegewezen MSI-identiteit en vooraf ACL uw kluizen met die identiteit voordat u implementeert.

Azure PowerShell-implementatie

Waarschuwing

PowerShell-clients voegen vaak toe \ aan " de settings.json waardoor akvvm_service mislukt met de volgende fout: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

De Azure PowerShell kan worden gebruikt om de Key Vault-VM-extensie te implementeren op een bestaande virtuele machine of virtuele-machineschaalset.

De extensie implementeren op een virtuele machine:

    # 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

De extensie implementeren op een virtuele-machineschaalset:


    # 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

Implementatie van Azure CLI

De Azure CLI kan worden gebruikt om de Key Vault-VM-extensie te implementeren op een bestaande virtuele machine of virtuele-machineschaalset.

De extensie implementeren op een virtuele machine:

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

De extensie implementeren op een virtuele-machineschaalset:

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

Houd rekening met de volgende beperkingen/vereisten:

Key Vault-beperkingen:
- Deze moet bestaan op het moment van de implementatie
- Het Key Vault-toegangsbeleid moet worden ingesteld voor VM/VMSS-identiteit met behulp van een beheerde identiteit. Zie Verifiëren bij Key Vault en toegangsbeleid voor Key Vault toewijzen.

Problemen met en ondersteuning oplossen

Gegevens over de status van extensie-implementaties kunnen worden opgehaald uit Azure Portal en met behulp van Azure PowerShell. Als u de implementatiestatus van extensies voor een bepaalde VM wilt zien, voert u de volgende opdracht uit met behulp van Azure PowerShell.

Azure PowerShell

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

Azure-CLI

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

De Azure CLI kan in verschillende shell-omgevingen worden uitgevoerd, maar met kleine variaties in de indeling. Als u onverwachte resultaten hebt met Azure CLI-opdrachten, raadpleegt u De Azure CLI gebruiken.

Logboeken en configuratie

De Key Vault VM-extensielogboeken bestaan alleen lokaal op de VIRTUELE machine en zijn het meest informatief als het gaat om het oplossen van problemen.

Locatie	Beschrijving
/var/log/waagent.log	Geeft weer wanneer er een update van de extensie is opgetreden.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	Bekijk de servicelogboeken van de Key Vault-VM-extensie om de status van de akvvm_service-service en het downloaden van certificaten te bepalen. U vindt de downloadlocatie van PEM-bestanden in bestanden met een vermelding met de naam van het certificaatbestand. Als certificateStoreLocation niet is opgegeven, wordt deze standaard ingesteld op /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-meest< recente versie>/config/*	De configuratie en binaire bestanden voor de Key Vault VM-extensieservice.

Symlink gebruiken

Symbolische koppelingen of Symlinks zijn geavanceerde sneltoetsen. Als u wilt voorkomen dat u de map bewaakt en het meest recente certificaat automatisch opvragen, kunt u deze symlink ([VaultName].[CertificateName]) gebruiken om de nieuwste versie van het certificaat op Linux op te halen.

Veelgestelde vragen

Is er een limiet voor het aantal waargenomen certificaten dat u kunt configureren? Nee, de Key Vault-VM-extensie heeft geen limiet voor het aantal waargenomen certificaten.

Ondersteuning

Als u op elk gewenst moment in dit artikel meer hulp nodig hebt, kunt u contact opnemen met de Azure-experts op de MSDN Azure- en Stack Overflow-forums. U kunt ook een ondersteuning voor Azure incident indienen. Ga naar de ondersteuning voor Azure-site en selecteer Ondersteuning krijgen. Lees de veelgestelde vragen over microsoft ondersteuning voor Azure voor informatie over het gebruik van Azure-ondersteuning.

Key Vault-extensie voor virtuele machines voor Linux

Besturingssysteem

Ondersteunde certificaatinhoudstypen

Vereisten

Versie van de Key Vault-VM-extensie

Extensieschema

Eigenschapswaarden

Sjabloonimplementatie

Volgorde van uitbreidingsafhankelijkheid

Azure PowerShell-implementatie

Implementatie van Azure CLI

Problemen met en ondersteuning oplossen

Logboeken en configuratie

Symlink gebruiken

Veelgestelde vragen

Ondersteuning

Aanvullende resources