Azure Key Vault virtuele-machineextensie voor Linux

De extensie Azure Key Vault virtuele machine (VM) vernieuwt automatisch certificaten die zijn opgeslagen in een Azure key vault. De extensie bewaakt een lijst met waargenomen certificaten die zijn opgeslagen in sleutelkluizen. Wanneer de extensie een wijziging detecteert, worden de bijbehorende certificaten opgehaald en geïnstalleerd. In dit artikel worden de ondersteunde platforms, configuraties en implementatieopties voor de Key Vault VM-extensie voor Linux beschreven.

Besturingssystemen

De Key Vault VM-extensie voor Linux ondersteunt de volgende distributies op zowel AMD64 als ARM64:

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

Ondersteunde certificaatinhoudstypen

De Key Vault VM-extensie ondersteunt de volgende certificaatinhoudstypen:

• PKCS #12
• PEM

Kenmerken

De Key Vault VM-extensie voor Linux versie 4.x:

• Installeert de twee nieuwste versies van elk certificaat.
• Installeert elk certificaat als gesplitste bestanden: een volledig ketenbestand .pem en een afzonderlijk .keyid persoonlijk sleutelbestand, elk geschreven als een versiebestand met een stabiele symbolische koppeling die verwijst naar de nieuwste versie.
• Voert validatie van certificaatketens uit voordat u een certificaat installeert dat het TLS Server Authentication Extended Key Usage (EKU) bevat. Validatie is mislukt: er wordt nog steeds een certificaat geïnstalleerd als de validatie niet kan worden voltooid vanwege tijdelijke netwerkproblemen. Certificaten zonder serververificatie-EKU zijn niet onderworpen aan deze controle.
• Past POSIX-ACL's toe om geconfigureerde gebruikers en groepen leestoegang te verlenen tot de persoonlijke sleutel. De handhaving van ACL's is altijd ingeschakeld.
• Ondersteunt een optionele authenticatie-overschrijving per certificaat, waarmee afzonderlijke gedetecteerde certificaten zich bij Key Vault kunnen authenticeren met een andere beheerde identiteit dan de standaard van de extensie. Zie Extensieschema voor meer informatie.
• Ondersteunt integratie van logboekregistratie van VM-extensies via Fluentd. Zie Logboekregistratie met Fluentd voor meer informatie.

Upgraden vanaf 3.0

Als u bijwerkt vanaf 3.0, worden de volgende functies gewijzigd of verwijderd.

Algemene belangrijke wijzigingen:

• pollingIntervalInS is nu beperkt tot 5 tot 60 minuten. De extensie pollt standaard één keer per uur.
• requireInitialSync wordt verwijderd. De extensie meldt alleen succes als alle geconfigureerde certificaten zijn geïnstalleerd.
• U kunt geen specifieke versie van een certificaat meer configureren. Waargenomen certificaat-URL's moeten versieloos zijn.
• Het verouderde schema waarin observedCertificates een lijst met URL-tekenreeksen wordt niet meer ondersteund. Elke vermelding moet een object met een url eigenschap zijn.

Linux-specifieke wijzigingen die fouten veroorzaken:

• De certificaatketen en de persoonlijke sleutel worden nu naar afzonderlijke bestanden geschreven. In 3.0 werden de volledige keten en de persoonlijke sleutel gecombineerd tot één PEM-bestand. In 4.x schrijft de extensie de volledige keten naar <vaultname>.<certname>.pem en de persoonlijke sleutel naar een afzonderlijk <vaultname>.<certname>.keyid bestand. Deze wijziging is een brekende wijziging: toepassingen die verwachten dat de sleutel en de certificaatketen in één bestand staan, moeten worden bijgewerkt zodat ze de certificaatketen uit het bestand .pem lezen en de privésleutel uit het bestand .keyid. Het .luma bestand wordt bijgewerkt nadat de symbolische koppelingen zijn bijgewerkt, zodat toepassingen wijzigingen in dit metagegevensbestand moeten controleren.
• customSymbolicLinkName wordt verwijderd. De extensie gebruikt altijd de standaard symbolische koppelingsnaam <vaultname>.<certname>.
• aclEnabled wordt verwijderd. ACL-functionaliteit is nu altijd ingeschakeld.
• certificateStoreName wordt genegeerd in Linux en heeft geen effect.

Vereiste voorwaarden

Bekijk de volgende vereisten voor het gebruik van de Key Vault VM-extensie voor Linux:

• Een Azure Key Vault-exemplaar met een certificaat. Zie Een sleutelkluis maken met behulp van Azure Portal voor meer informatie.

• Een VM met een toegewezen beheerde identiteit.

• Wijs de rol Key Vault Secrets User toe op het scopniveau van Key Vault aan de beheerde identiteit voor de VM of Azure-schaalvergrotingssets voor virtuele machines. Met deze rol wordt het geheime gedeelte van een certificaat opgehaald. Zie de volgende artikelen voor meer informatie:

  • Verificatie in Azure Key Vault
  • Azure RBAC-geheime, sleutel- en certificaatmachtigingen gebruiken met Azure Key Vault
  • Roltoewijzing binnen het Key Vault-bereik

• Configureer de Virtual Machine Scale Sets met de volgende identity configuratie:

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

• Configureer de Key Vault VM-extensie met de volgende authenticationSettings configuratie:

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

Extensieschema

In de volgende JSON ziet u het schema voor de Key Vault-VM-extensie. Bekijk de volgende belangrijke opmerkingen voordat u de implementatieopties voor schema's bekijkt.

• Voor de extensie zijn geen beveiligde instellingen vereist. Alle instellingen zijn openbare informatie.

• Waargenomen certificaat-URL's moeten het formulier https://myVaultName.vault.azure.net/secrets/myCertNamegebruiken.

  Dit formulier is vereist omdat het /secrets pad het volledige certificaat retourneert, inclusief de persoonlijke sleutel, maar het /certificates pad niet. Zie het overzicht van Azure Key Vault-sleutels, geheimen en certificaten voor meer informatie over certificaten. U kunt geen specifieke versie van het certificaat opgeven.

• De URL-host moet een herkende Azure Key Vault host zijn.

• De authenticationSettings eigenschap is vereist voor VM's met een door de gebruiker toegewezen identiteiten en voor Azure Arc-VM's.

  Laat deze eigenschap weg wanneer u een door het systeem toegewezen identiteit gebruikt. Voor VM's met Azure Arc stelt u msiEndpoint in op 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">
         }
      }
   }
}

Vastgoedwaarden

Het JSON-schema bevat de volgende eigenschappen.

Sjabloonimplementatie

Implementeer Azure VM-extensies met behulp van arm-sjablonen (Azure Resource Manager). Sjablonen zijn ideaal wanneer u een of meer virtuele machines implementeert waarvoor het vernieuwen van certificaten na de implementatie is vereist. U kunt de extensie implementeren op afzonderlijke VM's of Virtual Machine Scale Sets exemplaren. Het schema en de configuratie zijn gebruikelijk voor beide sjabloontypen.

De JSON-configuratie voor een sleutelkluisextensie is genest in de sjabloon van virtuele machines of Virtual Machine Scale Sets. Voor een VM-resource-extensie is de configuratie genest onder het object van de "resources": [] virtuele machine. Voor een instantie-extensie van virtuele machineschaalsets is de configuratie genesteld onder het "virtualMachineProfile":"extensionProfile":{"extensions" :[] object.

Het volgende JSON-fragment bevat voorbeeldinstellingen voor een ARM-sjabloonimplementatie van de Key Vault VM-extensie.

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

Automatische upgrade van extensie

De Key Vault VM-extensie ondersteunt automatische upgrade van extensies voor virtuele machines en schaalsets in Azure. Azure houdt de extensie automatisch up-to-date wanneer u de autoUpgradeMinorVersion en enableAutomaticUpgrade eigenschappen in de voorgaande voorbeelden instelt op true.

Ordening van uitbreidingsafhankelijkheden

De Key Vault VM-extensie ondersteunt het ordenen van uitbreidingsafhankelijkheid. De extensie rapporteert een geslaagde start nadat deze alle certificaten heeft gedownload en geïnstalleerd.

Als u andere extensies gebruikt waarvoor de installatie van certificaten is vereist voordat ze worden gestart, kunt u de volgorde van uitbreidingsafhankelijkheid gebruiken om een afhankelijkheid te declareren voor de Key Vault VM-extensie.

Bij het opstarten probeert de Key Vault VM-extensie certificaten maximaal 25 keer opnieuw te downloaden en te installeren met toenemende uitstelperioden, waarbij de extensie een Transitioning status heeft. Als de nieuwe pogingen zijn uitgeput, rapporteert de extensie een foutstatus . Nadat alle certificaten zijn geïnstalleerd, rapporteert de Key Vault VM-extensie een geslaagde start.

Zie Sequentiële extensie-inrichting in Virtual Machine Scale Sets voor meer informatie over het configureren van afhankelijkheden tussen extensies.

implementatie van Azure PowerShell

Implementeer de Azure Key Vault VM-extensie met behulp van Azure PowerShell. Sla de instellingen van de Key Vault-VM-extensie op in een JSON-bestand (settings.json).

Het volgende JSON-fragment bevat voorbeeldinstellingen voor het implementeren van de Key Vault VM-extensie met behulp van 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"
   }
}

Implementeren op een VIRTUELE machine

# 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

Implementeren op een exemplaar van virtuele-machineschaalsets

# 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

implementatie van Azure CLI

Implementeer de Azure Key Vault VM-extensie met behulp van de Azure CLI. Sla de instellingen van de Key Vault-VM-extensie op in een JSON-bestand (settings.json).

Het volgende JSON-fragment bevat voorbeeldinstellingen voor het implementeren van de Key Vault VM-extensie met behulp van de 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"
   }
}

Implementeren op een VIRTUELE machine

# 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"

Implementeren op een exemplaar van virtuele-machineschaalsets

# 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>"

Logboekregistratie met Fluentd

De Key Vault VM-extensie kan de logboeken doorsturen naar een Fluentd-logboekverzamelaar. Zorg ervoor dat uw logverzamelaar actief is en luistert op het eindpunt dat u in de instellingen opgeeft.

Voeg de volgende sectie toe aan uw extensie-instellingen:

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

Problemen oplossen

Gebruik deze suggesties om implementatieproblemen op te lossen.

Raadpleeg veelgestelde vragen

Is er een limiet voor het aantal waargenomen certificaten?

Nee. De Key Vault VM-extensie beperkt het aantal waargenomen certificaten (observedCertificates) niet.

Wat is de standaardlocatie waar certificaten worden geïnstalleerd?

Als u certificateStoreLocation niet opgeeft, schrijft de extensie certificaten naar /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Hoe forceer ik de extensie om een nieuw certificaat op te halen?

Start de akvvm_service service opnieuw op (weergavenaam Key Vault VM-extensie).

Hoe gebruik ik een andere identiteit voor een specifiek certificaat?

Voeg een authenticationOverride object met het doel msiClientId toe aan de vermelding van dat certificaat in observedCertificates. Certificaten zonder overschrijving gebruiken het element op het hoogste niveau authenticationSettings.

Extensiestatus weergeven

Controleer de status van uw extensie-implementatie in de Azure-portal of met behulp van PowerShell of de Azure CLI.

Voer de volgende opdrachten uit om de implementatiestatus van extensies voor een bepaalde VIRTUELE machine te zien.

• Azure PowerShell:

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

• De Azure CLI:

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

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

Logboeken en configuratie controleren

De Key Vault VM-extensielogboeken bestaan alleen lokaal op de virtuele machine. Bekijk de logboekdetails voor hulp bij het oplossen van problemen.

Certificaatinstallatie in Linux

De Key Vault VM-extensie voor Linux installeert certificaten als PEM-bestanden. Wanneer de extensie een certificaat uit Key Vault downloadt, wordt het volgende gebruikt:

1. Hiermee maakt u een opslagmap op basis van de certificateStoreLocation instelling. Als u deze instelling niet opgeeft, wordt de standaardlocatie ingesteld op /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Hiermee schrijft u de certificaatketen (leaf, dan tussenliggende bestanden, root indien aanwezig in Key Vault) naar een bestand met volledige ketenversies .pem en schrijft u de bijbehorende persoonlijke sleutel naar een geversied .keyid bestand.
3. Past POSIX-ACL's toe op de persoonlijke sleutel op basis van de acls opgegeven in de configuratie, die leestoegang verleent tot de vermelde gebruikers en groepen. Bestanden zijn anders alleen toegankelijk voor de eigenaar.
4. Hiermee maakt of werkt u een stabiele symbolische koppeling (<vaultname>.<certname>.pem en <vaultname>.<certname>.keyid) bij die verwijst naar de nieuwste versie van het certificaat. Koppeling vindt altijd plaats.

Standaardlocatie voor certificaatarchief

Als u geen locatie opgeeft, installeert de extensie certificaten onder /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. De extensie negeert certificateStoreName op Linux.

Uitvoerbestanden van certificaten

Voor vault mykv en secret server-tls produceert een succesvolle synchronisatie:

/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)

Configureer toepassingen om te verwijzen naar het stabiele symbolische koppelingspad (bijvoorbeeld /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem) zodat ze altijd de meest recente certificaatversie lezen zonder opnieuw te configureren bij verlenging.

Toegangsbeheer voor certificaten

Certificaat- en persoonlijke sleutelbestanden zijn standaard alleen leesbaar door hun eigenaar. Leestoegang verlenen aan extra gebruikers en groepen met behulp van de acls matrix in de certificaatconfiguratie:

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

Elke vermelding kan een gebruiker, een groep of beide opgeven. ACL-handhaving is altijd ingeschakeld en geeft momenteel leestoegang.

Certificaat vernieuwen

Wanneer certificaten worden vernieuwd in Key Vault, voert de extensie automatisch de volgende acties uit op de volgende poll:

1. Downloadt de nieuwe certificaatversie.
2. Hiermee schrijft u de nieuwe versie .pem en .keyid bestanden.
3. Werkt de stabiele symbolische koppeling bij zodat deze verwijst naar de nieuwe versie, zodat bestaande toepassingspaden blijven omzetten naar het meest recente certificaat.

Ondersteuning krijgen

Microsoft biedt alleen ondersteuning voor primaire versie 3.0 en hoger van de Key Vault VM-extensie. Als u versie 1.0 gebruikt, voert u een upgrade uit naar de nieuwste versie voordat u ondersteuning aanvraagt.

Gebruik deze andere opties om implementatieproblemen op te lossen:

• Neem voor hulp contact op met de Azure experts in Microsoft Q& A.

• Als u geen antwoord op de site vindt, kunt u een vraag plaatsen voor invoer van Microsoft of andere leden van de community.

• U kunt ook contact opnemen met Microsoft Ondersteuning. Zie Hoe u een ondersteuning voor Azure aanvraag maakt voor meer informatie over het gebruik van ondersteuning voor Azure.