Azure Key Vault tillägg för virtuella datorer för Linux

Tillägget Azure Key Vault virtuell dator uppdaterar automatiskt certifikat som lagras i en Azure key vault. Tillägget övervakar en lista över observerade certifikat som lagras i nyckelvalv. När tillägget identifierar en ändring hämtar och installerar det motsvarande certifikat. Den här artikeln beskriver de plattformar, konfigurationer och distributionsalternativ som stöds för Key Vault VM-tillägget för Linux.

Operativsystem

Det Key Vault VM-tillägget för Linux stöder följande distributioner på både AMD64 och ARM64:

• Ubuntu 24.04
• Azure Linux 3.0 och 4.0
• Red Hat Enterprise Linux (RHEL) 9

Innehållstyper för certifikat som stöds

Key Vault VM-tillägget stöder följande certifikatinnehållstyper:

• PKCS #12
• PEM

Egenskaper

Det Key Vault VM-tillägget för Linux version 4.x:

• Installerar de två senaste versionerna av varje certifikat.
• Installerar varje certifikat som delade filer: en fil med fullständig kedja .pem och en separat .keyid privat nyckelfil, var och en skriven som en version av filen med en stabil symbolisk länk som pekar på den senaste versionen.
• Utför validering av certifikatkedjan innan du installerar ett certifikat som har TLS Server Authentication Extended Key Usage (EKU). Valideringen är öppen vid fel: ett certifikat installeras fortfarande om valideringen inte kan slutföras på grund av tillfälliga nätverksproblem. Certifikat utan EKU för serverautentisering omfattas inte av den här kontrollen.
• Använder POSIX-ACL:er för att bevilja konfigurerade användare och grupper läsbehörighet till den privata nyckeln. Upprätthållande av ACL är alltid aktiverat.
• Stöder en valfri åsidosättning av autentisering per certifikat, vilket gör att enskilda certifikat som observeras kan autentisera mot Key Vault med en annan hanterad identitet än tilläggets standardinställning. Mer information finns i Tilläggsschema.
• Stöder loggningsintegrering av VM-tillägg via Fluentd. Mer information finns i Loggning med Fluentd.

Uppgradera från 3.0

Om du uppdaterar från 3.0 ändras eller tas följande funktioner bort.

Allmänna brytande ändringar:

• pollingIntervalInS är nu begränsad till mellan 5 och 60 minuter. Som standard kontrollerar tillägget en gång i timmen.
• requireInitialSync tas bort. Tillägget rapporterar endast att installationen lyckades om det installerar alla konfigurerade certifikat.
• Du kan inte längre konfigurera en viss version av ett certifikat. Observerade certifikat-URL:er måste vara versionslösa.
• Det äldre schemat där observedCertificates det finns en lista över URL-strängar stöds inte längre. Varje post måste vara ett objekt med en url egenskap.

Linux-specifika icke bakåtkompatibla ändringar:

• Certifikatkedjan och den privata nyckeln skrivs nu till separata filer. I 3.0 kombinerades hela kedjan och den privata nyckeln till en enda PEM-fil. I 4.x skriver tillägget hela kedjan till <vaultname>.<certname>.pem och den privata nyckeln till en separat <vaultname>.<certname>.keyid fil. Den här ändringen är inkompatibel: applikationer som förväntar sig att nyckeln och certifikatkedjan finns i en och samma fil måste uppdateras så att de läser certifikatkedjan från filen .pem och den privata nyckeln från filen .keyid. Filen .luma uppdateras när de symboliska länkarna har uppdaterats, så program bör övervaka ändringar i den här metadatafilen.
• customSymbolicLinkName tas bort. Tillägget använder alltid standardnamnet för symbolisk länk <vaultname>.<certname>.
• aclEnabled tas bort. ACL-funktioner är nu alltid aktiverade.
• certificateStoreName ignoreras i Linux och har ingen effekt.

Förutsättningar

Granska följande förutsättningar för att använda Key Vault VM-tillägget för Linux:

• En Azure Key Vault-instans med ett certifikat. Mer information finns i Skapa ett nyckelvalv med hjälp av Azure-portalen.

• En virtuell dator med en tilldelad hanterad identitet.

• Tilldela Key Vault Secrets User-rollen på Key Vault-omfångsnivå till den hanterade identiteten för den virtuella datorn eller Azure Virtual Machine Scale Sets. Denna roll hämtar den privata delen av ett certifikat. Mer information finns i följande artiklar:

  • Autentisering i Azure Key Vault
  • Använd Azure RBAC-hemlighet, nyckel och certifikatbehörigheter med Azure Key Vault
  • Nyckelvalvets omfångsrolltilldelning

• Konfigurera Virtual Machine Scale Sets med följande identity konfiguration:

  "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
         "[parameters('userAssignedIdentityResourceId')]": {}
      }
  }
  

• Konfigurera Key Vault VM-tillägget med följande authenticationSettings konfiguration:

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

Tilläggsschema

Följande JSON visar schemat för tillägget för den virtuella Key Vault-datorn. Innan du överväger alternativen för schemaimplementering bör du läsa följande viktiga anteckningar.

• Tillägget kräver inte skyddade inställningar. Alla inställningar är offentlig information.

• Observerade certifikat-URL:er måste använda formuläret https://myVaultName.vault.azure.net/secrets/myCertName.

  Det här formuläret krävs eftersom /secrets sökvägen returnerar det fullständiga certifikatet, inklusive den privata nyckeln, men /certificates sökvägen gör det inte. Mer information om certifikat finns i Översikt över Azure Key Vault-nycklar, hemligheter och certifikat. Du kan inte ange en specifik version av certifikatet.

• URL-värdnamnet måste vara ett giltigt Azure Key Vault-värdnamn.

• Egenskapen authenticationSettingskrävs för virtuella datorer med användartilldelade identiteter och för Azure Arc-aktiverade virtuella datorer.

  Utelämna den här egenskapen när du använder en systemtilldelad identitet. För Azure Arc-aktiverade virtuella datorer anger du msiEndpoint till http://localhost:40342/metadata/identity.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <Optional. Polling interval in seconds, between 300 (5 min) and 3600 (60 min). Example: "3600">,
             "certificateStoreLocation": <Optional. Default disk path where certificates are stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
             "observedCertificates": <An array of Key Vault URIs that represent monitored certificates, including per-certificate store location and ACL permissions on the 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 disk path where the certificate is stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "acls": <Optional. An array of users and groups to grant read access to the certificate private key. Example:
                    [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Egenskapsvärden

JSON-schemat innehåller följande egenskaper.

Malltillämpning

Distribuera Azure VM-tillägg med hjälp av arm-mallar (Azure Resource Manager). Mallar är idealiska när du distribuerar en eller flera virtuella datorer som kräver uppdatering efter distributionen av certifikat. Du kan distribuera tillägget till enskilda virtuella datorer eller Virtual Machine Scale Sets instanser. Schemat och konfigurationen är gemensamma för båda malltyperna.

JSON-konfigurationen för ett nyckelvalvstillägg är kapslad i mallen VM eller Vm Scale Sets. För ett vm-resurstillägg kapslas konfigurationen under objektet för den "resources": [] virtuella datorn. För ett instanstillägg i Virtuella maskinskalningsuppsättningar kapslas konfigurationen in under "virtualMachineProfile":"extensionProfile":{"extensions" :[]-objektet.

Följande JSON-kodfragment innehåller exempelinställningar för en ARM-malldistribution av Key Vault VM-tillägget.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": "3600",
             "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
             "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"
                }
             ]
         },
         "authenticationSettings": {
            "msiEndpoint":  "http://169.254.169.254/metadata/identity",
            "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
         }
      }
   }
}

Automatisk uppgradering av tillägg

Det Key Vault VM-tillägget stöder automatisk tilläggsuppgradering för virtuella datorer och skalningsuppsättningar i Azure. Azure håller tillägget uppdaterat automatiskt när du anger autoUpgradeMinorVersion egenskaperna och enableAutomaticUpgrade i föregående exempel till true.

Tilläggsberoendens ordning

Det Key Vault VM-tillägget stöder fältordning av tilläggsberoenden. Tillägget rapporterar en lyckad start när det har laddat ned och installerat alla certifikat.

Om du använder andra tillägg som kräver installation av certifikat innan de startas kan du använda tilläggsberoendeordning för att deklarera ett beroende av Key Vault VM-tillägget.

När den startar försöker Key Vault VM-tillägget ladda ned och installera certifikaten upp till 25 gånger med ökande återhämtningsperioder, under vilka det förblir i ett övergångstillstånd. Om återförsöken är uttömda rapporterar tillägget ett feltillstånd . När alla certifikat har installerats rapporterar tillägget för den virtuella Key Vault-datorn en lyckad start.

Mer information om hur du konfigurerar beroenden mellan tillägg finns i Etablering av sekvenstillägg i Virtual Machine Scale Sets.

Azure PowerShell-driftsättning

Distribuera Azure Key Vault VM-tillägget med hjälp av Azure PowerShell. Spara inställningarna för Key Vault VM-tillägg i en JSON-fil (settings.json).

Följande JSON-kodfragment innehåller exempelinställningar för att distribuera Key Vault VM-tillägget med hjälp av PowerShell.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Distribuera 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 "4.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Distribuera på en instans av en skalningsuppsättning för virtuella maskiner

# 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 "4.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Azure CLI distribution

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

Följande JSON-kodfragment innehåller exempelinställningar för att distribuera Key Vault VM-tillägget med hjälp av Azure CLI.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Distribuera på en virtuell dator

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Distribuera på en instans av en skalningsuppsättning för virtuella maskiner

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

az vm extension delete --name "KeyVaultForLinux" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Loggning med Fluentd

Det Key Vault VM-tillägget kan vidarebefordra loggarna till en Fluentd-logginsamlare. Kontrollera att logginsamlaren körs och lyssnar på den ändpunkt som du anger i inställningarna.

Lägg till följande avsnitt i tilläggsinställningarna:

"loggingSettings": {
   "logger": "fluentd",
   "endpoint": "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket",
   "format": "forward",
   "servicename": "akvvm_service"
}

Åtgärda problem

Använd de här förslagen för att felsöka distributionsproblem.

Kontrollera vanliga frågor och svar

Finns det en gräns för antalet observerade certifikat?

No. Tillägget för den virtuella Key Vault-datorn begränsar inte antalet observerade certifikat (observedCertificates).

Vilken är standardplatsen där certifikat installeras?

Om du inte anger certificateStoreLocationskriver tillägget certifikat till /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Hur tvingar jag tillägget att hämta ett nytt certifikat?

akvvm_service Starta om tjänsten (visningsnamn Key Vault VM-tillägg).

Hur använder jag en annan identitet för ett specifikt certifikat?

Lägg till ett authenticationOverride objekt med målet msiClientId till certifikatets post i observedCertificates. Certifikat utan åsidosättning använder den översta nivån authenticationSettings.

Visa tilläggsstatus

Kontrollera statusen för tilläggsdistributionen i Azure-portalen eller med hjälp av PowerShell eller Azure CLI.

Om du vill se distributionstillståndet för tillägg för en viss virtuell dator kör du följande kommandon.

• Azure PowerShell:

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• Azure CLI:

  az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --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.

Granska loggar och konfiguration

Key Vault VM-tilläggsloggarna finns bara lokalt på den virtuella datorn. Granska logginformationen för att få hjälp med felsökning.

Certifikatinstallation i Linux

Det Key Vault VM-tillägget för Linux installerar certifikat som PEM-filer. När tillägget laddar ned ett certifikat från Key Vault:

1. Skapar en lagringsmapp baserat på inställningen certificateStoreLocation . Om du inte anger den här inställningen är platsen som standard /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Skriver certifikatkedjan (slutcertifikat, sedan mellanliggande certifikat och därefter roten, om den finns i Key Vault) till en versionshanterad fullkedjefil .pem och den motsvarande privata nyckeln till en versionshanterad fil .keyid.
3. Tillämpar POSIX-ACL:er på den privata nyckeln baserat på den acls angivna i konfigurationen, vilket ger läsåtkomst till de listade användarna och grupperna. Filer är annars endast åtkomliga för ägaren.
4. Skapar eller uppdaterar en stabil symbolisk länk (<vaultname>.<certname>.pem och <vaultname>.<certname>.keyid) som pekar på den senaste versionen av certifikatet. Länkning sker alltid.

Standardplats för certifikatarkiv

Om du inte anger någon plats installerar tillägget certifikat under /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. Tillägget ignorerar certificateStoreName i Linux.

Utdatafiler för certifikat

För valv mykv och hemlighet server-tlsgenererar en lyckad synkronisering:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── mykv.server-tls.pem -> mykv.server-tls.<version>.pem.<timestamp>     # symlink to latest full chain
├── mykv.server-tls.keyid -> mykv.server-tls.<version>.keyid.<timestamp> # symlink to latest private key
├── mykv.server-tls.<version>.pem.<timestamp>                            # full chain PEM (mode 600)
├── mykv.server-tls.<version>.keyid.<timestamp>                          # private key (mode 600)
└── mykv.server-tls.luma                                                 # certificate management metadata (mode 644)

Konfigurera program för att referera till den stabila symboliska länksökvägen (till exempel /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem) så att de alltid läser den senaste certifikatversionen utan omkonfiguration vid förnyelse.

Åtkomstkontroll för certifikat

Som standard är certifikat- och privata nyckelfiler skrivbara endast av ägaren. Bevilja läsbehörighet till ytterligare användare och grupper med hjälp av matrisen acls i certifikatkonfigurationen:

"acls": [
   { "user": "app1", "group": "appGroup1" },
   { "user": "service1" }
]

Varje post kan ange en användare, en grupp eller båda. ACL tillämpas alltid och ger för närvarande läsåtkomst.

Certifikatförnyelse

När certifikat förnyas i Key Vault utför tillägget automatiskt följande åtgärder vid nästa avsökning:

1. Laddar ned den nya certifikatversionen.
2. Skriver den nya versionen .pem och .keyid filerna.
3. Uppdaterar den stabila symboliska länken så att den pekar på den nya versionen så att befintliga programsökvägar fortsätter att matcha det senaste certifikatet.

Få support

Microsoft ger endast stöd för huvudversion 3.0 och senare av Key Vault VM-tillägget. Om du använder version 1.0 uppgraderar du till den senaste versionen innan du begär support.

Använd de här andra alternativen för att lösa distributionsproblem:

• Kontakta Azure experter på Microsoft Q& A.

• Om du inte hittar något svar på webbplatsen kan du skicka en fråga för indata från Microsoft eller andra medlemmar i communityn.

• Du kan också kontakta Microsoft Support. Information om hur du använder Azure support finns i Så här skapar du en Azure support begäran.