Tillägg för virtuella Key Vault-datorer för Linux

  • Artikel

Tillägget för den virtuella Key Vault-datorn ger automatisk uppdatering av certifikat som lagras i ett Azure-nyckelvalv. Mer specifikt övervakar tillägget en lista över observerade certifikat som lagras i nyckelvalv. Tillägget hämtar och installerar motsvarande certifikat när en ändring har upptäckts. Det här dokumentet beskriver de plattformar, konfigurationer och distributionsalternativ som stöds för Key Vault VM-tillägget för Linux.

Operativsystem

Tillägget för den virtuella Key Vault-datorn stöder följande Linux-distributioner:

Kommentar

Key Vault VM-tillägget laddar ned certifikaten på standardplatsen eller till den plats som tillhandahålls av egenskapen "certStoreLocation" i inställningarna för VM-tillägget. Tillägget för den virtuella Key Vault-datorn uppdaterar mappbehörigheten till 700 (drwx------) som tillåter läs-, skriv- och körningsbehörighet till mappens ägare endast

Innehållstyper för certifikat som stöds

  • PKCS #12
  • PEM

Förutsättningar

Key Vault VM-tilläggsversion

  • Användare kan välja att uppgradera sin version av key vault-vm-tillägget till att V2.0 använda den fullständiga nedladdningsfunktionen för certifikatkedjan. Utfärdarcertifikat (mellanliggande och rot) ingår i lövcertifikatet i PEM-filen.

  • Om du föredrar att uppgradera till v2.0måste du ta bort v1.0 först och sedan installera 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

Flaggan --version 2.0 är valfri eftersom den senaste versionen är installerad som standard.

  • Om den virtuella datorn har certifikat som laddats ned av v1.0 tas inte de nedladdade certifikaten bort om du tar bort AKVVM-tillägget v1.0. När du har installerat v2.0 ändras inte de befintliga certifikaten. Du skulle behöva ta bort certifikatfilerna eller rulla över certifikatet för att hämta PEM-filen med fullständig kedja på den virtuella datorn.

Tilläggsschema

Följande JSON visar schemat för tillägget för den virtuella Key Vault-datorn. Tillägget kräver inte skyddade inställningar – alla dess inställningar betraktas som information utan säkerhetspåverkan. Tillägget kräver en lista över övervakade hemligheter, avsökningsfrekvens och målcertifikatarkivet. Specifikt:

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

Kommentar

Dina observerade certifikat-URL:er ska vara i formuläret https://myVaultName.vault.azure.net/secrets/myCertName.

Det beror på att /secrets sökvägen returnerar det fullständiga certifikatet, inklusive den privata nyckeln, medan /certificates sökvägen inte gör det. Mer information om certifikat finns här: Key Vault-certifikat

Viktigt!

Egenskapen "authentication Inställningar" krävs för virtuella datorer med användartilldelade identiteter. Även om du vill använda en systemtilldelad identitet krävs detta fortfarande, annars vet inte VM-tillägget vilken identitet som ska användas. Utan det här avsnittet leder en virtuell dator med användartilldelade identiteter till att Key Vault-tillägget misslyckas och inte kan ladda ned certifikat. Ange msiClientId till den identitet som ska autentiseras till Key Vault.

Krävs även för Azure Arc-aktiverade virtuella datorer. Ange msiEndpoint till http://localhost:40342/metadata/identity.

Egenskapsvärden

Name Värde/exempel Datatyp
apiVersion 2022-07-01 datum
Publisher Microsoft.Azure.KeyVault sträng
type KeyVaultForLinux sträng
typeHandlerVersion 2.0 heltal
pollingIntervalInS 3600 sträng
certificateStoreName Den ignoreras i Linux sträng
linkOnRenewal falskt boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store sträng
requireInitialSync true boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] strängmatris
msiEndpoint http://169.254.169.254/metadata/identity sträng
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 sträng

Malldistribution

Azure VM-tillägg kan distribueras med Azure Resource Manager-mallar. Mallar är idealiska när du distribuerar en eller flera virtuella datorer som kräver uppdatering efter distributionen av certifikat. Tillägget kan distribueras till enskilda virtuella datorer eller vm-skalningsuppsättningar. Schemat och konfigurationen är gemensamma för båda malltyperna.

JSON-konfigurationen för ett tillägg för en virtuell dator måste vara kapslad i mallens resursfragment för den virtuella datorn, specifikt "resources": [] objekt för mallen för den virtuella datorn och för en vm-skalningsuppsättning under "virtualMachineProfile":"extensionProfile":{"extensions" :[] objekt.

Kommentar

Vm-tillägget kräver att system- eller användarhanterad identitet tilldelas för att autentisera till Key Vault. Se Autentisera till Key Vault och tilldela en key vault-åtkomstprincip.

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

Beställning av tilläggsberoende

Tillägget för den virtuella Key Vault-datorn stöder tilläggsordning om det har konfigurerats. Som standard rapporterar tillägget lyckad start så snart avsökningen startar. Du kan dock konfigurera den så att den väntar tills den har laddat ned den fullständiga listan med certifikat innan en lyckad start rapporteras. Om andra tillägg är beroende av installerade certifikat innan de startas kan dessa tillägg deklarera ett beroende av Key Vault-tillägget genom att aktivera den här inställningen. Detta förhindrar att dessa tillägg startar tills alla certifikat som de är beroende av har installerats. Tillägget försöker ladda ned den första nedladdningen på obestämd tid och förblir i ett Transitioning tillstånd.

Om du vill aktivera tilläggsberoende anger du följande:

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

Kommentar

Att använda den här funktionen är inte kompatibelt med en ARM-mall som skapar en systemtilldelad identitet och uppdaterar en Key Vault-åtkomstprincip med den identiteten. Detta resulterar i ett dödläge eftersom åtkomstprincipen för valvet inte kan uppdateras förrän alla tillägg har startats. Du bör i stället använda en enskild användartilldelad MSI-identitet och pre-ACL dina valv med den identiteten innan du distribuerar.

Azure PowerShell-distribution

Varning

PowerShell-klienter lägger ofta till \" i i settings.json vilket orsakar akvvm_service misslyckas med fel: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell kan användas för att distribuera tillägget för den virtuella Key Vault-datorn till en befintlig virtuell dator eller vm-skalningsuppsättning.

  • Så här distribuerar du tillägget på en virtuell dator:

        # 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

  • Så här distribuerar du tillägget på en VM-skalningsuppsättning:

    
    # 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

Azure CLI-distribution

Azure CLI kan användas för att distribuera tillägget för den virtuella Key Vault-datorn till en befintlig virtuell dator eller vm-skalningsuppsättning.

  • Så här distribuerar du tillägget på en virtuell dator:

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

  • Så här distribuerar du tillägget på en VM-skalningsuppsättning:

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

Tänk på följande begränsningar/krav:

Felsökning och support

Data om tillståndet för tilläggsdistributioner kan hämtas från Azure-portalen och med hjälp av Azure PowerShell. Om du vill se distributionstillståndet för tillägg för en viss virtuell dator kör du följande kommando med hjälp av 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"

Azure CLI kan köras i flera gränssnittsmiljöer, men med små formatvariationer. Om du har oväntade resultat med Azure CLI-kommandon kan du läsa Så här använder du Azure CLI.

Loggar och konfiguration

Key Vault VM-tilläggsloggarna finns bara lokalt på den virtuella datorn och är mest informativa när det gäller felsökning.

Plats beskrivning
/var/log/waagent.log Visar när en uppdatering av tillägget inträffade.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Granska tjänstloggarna för Key Vault VM-tillägg för att fastställa status för akvvm_service-tjänsten och certifikatnedladdningen. Du hittar nedladdningsplatsen för PEM-filer i filer med en post som kallas certifikatfilnamn. Om certificateStoreLocation inte har angetts är standardvärdet /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-senaste< version>/config/* Konfigurationen och binärfilerna för key vault VM-tilläggstjänsten.

Symboliska länkar eller Symlinks är avancerade genvägar. Om du vill undvika att övervaka mappen och hämta det senaste certifikatet automatiskt kan du använda den här symlänken ([VaultName].[CertificateName]) för att hämta den senaste versionen av certifikatet i Linux.

Vanliga frågor och svar

  • Finns det en gräns för antalet observeradecertifikat som du kan konfigurera? Nej, Key Vault VM-tillägget har ingen gräns för antalet observeradeCertifikat.

Support

Om du behöver mer hjälp när som helst i den här artikeln kan du kontakta Azure-experterna på MSDN Azure- och Stack Overflow-forumen. Du kan också skapa en Azure-supportincident. Gå till Azure-supportwebbplatsen och välj Hämta support. Information om hur du använder Azure Support finns i Vanliga frågor och svar om Microsoft Azure-support.