Delen via

Key Vault-extensie voor virtuele machines voor Linux

  • Artikel

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:

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 (versie 1/2) of afzonderlijke certificaatinstellingen (versie 3). 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

Updates in versie 3.0+

Versie 3.0+ van de Key Vault VM-extensie voor Linux biedt ondersteuning voor de volgende functies:

  • ACL-machtigingen voor gedownloade certificaten toevoegen om leestoegang te bieden voor gebruikers en groepen
  • Configuratie van certificaatinstallatielocatie
  • Ondersteuning voor aangepaste symbolische namen
  • Integratieondersteuning voor logboekregistratie van VM-extensies via Fluentd

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 bestaande versie van de Key Vault-VM-extensie te upgraden naar een nieuwere versie.

  • Als u liever een upgrade naar een nieuwere versie uitvoert, moet u eerst de vorige versie verwijderen en vervolgens nieuwere versie installeren.

  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

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

  • Als de VM certificaten bevat die zijn gedownload door de vorige versie, worden de gedownloade certificaten niet verwijderd door de VM-extensie te verwijderen. Na de installatie van een nieuwere versie 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": "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".>
        }>
       }
      }
    }

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 authenticationSettings 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 3,0 int
pollingIntervalInS 3600 tekenreeks
certificateStoreName Het wordt genegeerd in Linux tekenreeks
linkOnRenewal false boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store tekenreeks
observedCertificates [{...}, {...}] tekenreeksmatrix
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" tekenreeks
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" tekenreeks
observedCertificates/customSymbolicLinkName (optioneel) "app1Cert1" tekenreeks
observedCertificates/acls (optioneel) "{...}, {...}" tekenreeksmatrix
authenticationSettings (optioneel) {...} object
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity tekenreeks
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 tekenreeks
loggingSettings (optioneel) {...} object
loggingSettings/logger "fluentd" tekenreeks
loggingSettings/endpoint "tcp://localhost:24224" tekenreeks
loggingSettings/format "doorsturen" tekenreeks
loggingSettings/servicename "akvvm_service" 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": "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">
          }
        } 
      }
    }

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 u een geslaagde start rapporteert. 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:

De AZURE Key Vault VM-extensie kan worden geïmplementeerd met Azure PowerShell. Sla de instellingen van de Key Vault-VM-extensie op in een JSON-bestand (settings.json).

De volgende JSON-fragmenten bevatten voorbeeldinstellingen voor het implementeren van de Key Vault VM-extensie met 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"
   }      
}
  • De extensie 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 "3.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
  • De extensie implementeren op een virtuele-machineschaalset:
    # 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

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:

De Azure Key Vault-VM-extensie kan worden geïmplementeerd met behulp van de Azure CLI. Sla de instellingen van de Key Vault-VM-extensie op in een JSON-bestand (settings.json).

De volgende JSON-fragmenten bevatten voorbeeldinstellingen voor het implementeren van de Key Vault VM-extensie met de 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"
   }      
}
  • De extensie op een virtuele machine implementeren

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

Houd rekening met de volgende beperkingen/vereisten:

  • Key Vault-beperkingen:
    • Deze moet bestaan op het moment van de implementatie
    • De gebruikersrol Key Vault-geheimen moet worden toegewezen aan Key Vault voor VM-identiteit

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 lokaal op de virtuele machine en zijn het meest informatief als het gaat om het oplossen van problemen. U kunt optionele sectie voor logboekregistratie gebruiken om te integreren met de logboekregistratieprovider via fluentd

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.

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.