Dela via

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 (version 1/2) eller enskilda certifikatinställningar (version 3). 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

Uppdateringar i version 3.0+

Version 3.0+ av Key Vault VM-tillägget för Linux lägger till stöd för följande funktioner:

  • Lägga till ACL-behörigheter för nedladdade certifikat för att ge läsbehörighet för användare och grupper
  • Platskonfiguration för certifikatinstallation
  • Stöd för anpassat symboliskt namn
  • Integreringsstöd för vm-tilläggsloggning via Fluentd

Förutsättningar

Key Vault VM-tilläggsversion

  • Användare kan välja att uppgradera sin befintliga version av Key Vault VM-tillägget till en nyare version.

  • Om du föredrar att uppgradera till en nyare version måste du först ta bort den tidigare versionen och sedan installera nyare version.

  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

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

  • Om den virtuella datorn har certifikat som laddats ned av tidigare version tar du inte bort de nedladdade certifikaten om du tar bort VM-tillägget. När du har installerat en nyare version ä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": "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".>
        }>
       }
      }
    }

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 "authenticationSettings" krävs för virtuella datorer med alla 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 3,0 heltal
pollingIntervalInS 3600 sträng
certificateStoreName Den ignoreras i Linux sträng
linkOnRenewal falskt boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store sträng
observedCertificates [{...}, {...}] strängmatris
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" sträng
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" sträng
observedCertificates/customSymbolicLinkName (valfritt) "app1Cert1" sträng
observedCertificates/acls (valfritt) "{...}, {...}" strängmatris
authenticationSettings (valfritt) {...} objekt
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity sträng
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 sträng
loggingSettings (valfritt) {...} objekt
loggingSettings/logger "flytande" sträng
loggingSettings/endpoint "tcp://localhost:24224" sträng
loggingSettings/format "framåt" sträng
loggingSettings/servicename "akvvm_service" 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": "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">
          }
        } 
      }
    }

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:

Azure Key Vault VM-tillägget kan distribueras med Azure PowerShell. Spara inställningar för Key Vault VM-tillägg till en JSON-fil (settings.json).

Följande JSON-kodfragment innehåller exempelinställningar för att distribuera tillägget för den virtuella Key Vault-datorn med 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"
   }      
}
  • Så här distribuerar du tillägget på en virtuell dator:
# 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
  • Så här distribuerar du tillägget på en VM-skalningsuppsättning:
    # 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

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:

Azure Key Vault VM-tillägget kan distribueras med hjälp av Azure CLI. Spara inställningar för Key Vault VM-tillägg till en JSON-fil (settings.json).

Följande JSON-kodfragment innehåller exempelinställningar för distribution av key vault VM-tillägget med Azure CLI.

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

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

  • Key Vault-begränsningar:
    • Den måste finnas vid tidpunkten för distributionen
    • Användarrollen Key Vault-hemligheter måste tilldelas till Key Vault för VM-identitet

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 lokalt på den virtuella datorn och är mest informativa när det gäller felsökning. Du kan använda det valfria loggningsavsnittet för att integrera med loggningsprovidern via fluentd

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.