Key Vault-extensie voor virtuele machines voor Linux

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:

• Ubuntu 22.04 en hoger
• Azure Linux

Ondersteunde certificaatinhoudstypen

• PKCS #12
• PEM

Kenmerken

Key Vault VM-extensie voor Linux versie 3.0+ ondersteunt:

• 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

Vereiste voorwaarden

• Key Vault-exemplaar met certificaat. Zie Create a Key Vault

• Toegewezen beheerde identiteit op virtuele machines/virtuele machineschaalsets.

• De Geheimen Gebruikersrol van Key Vault op het scopeniveau van Key Vault voor VM's en Azure Virtual Machine Scale Sets met beheerde identiteit. Deze rol haalt een deel van een geheim op dat betrekking heeft op een certificaat. Zie de volgende artikelen voor meer informatie:

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

• Virtuele machineschaalsets moeten 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]" }

Key Vault-VM-extensie upgraden

• Als u een upgrade wilt uitvoeren van een oudere versie naar versie 3.0+, moet u eerst de vorige versie verwijderen en vervolgens versie 3.0 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

• 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 de 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

De volgende JSON biedt het schema voor de Key Vault VM-extensie. Alle instellingen worden opgegeven als niet-beveiligd, omdat geen ervan als gevoelig wordt beschouwd. Als u de extensie wilt configureren, moet u een lijst met certificaten opgeven die moeten worden bewaakt, hoe vaak updates moeten worden gecontroleerd en het doelpad voor het opslaan van certificaten. 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.: "00001111-aaaa-2222-bbbb-3333cccc4444".>
        }>
       }
      }
    }

Vastgoedwaarden

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 virtuele machines of schaalsets van virtuele machines. Het schema en de configuratie zijn gebruikelijk voor beide sjabloontypen.

   {
      "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.: "00001111-aaaa-2222-bbbb-3333cccc4444">
          }
        } 
      }
    }

Uitbreidingsafhankelijkheidsvolgorde

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 probeert de eerste download maximaal 25 keer opnieuw uit te voeren met toenemende uitstelperioden, waarbij deze in een Transitioning status blijft. Als de herhalingspogingen zijn uitgeput, zal de extensie een Error status melden.

Als u uitbreidingsafhankelijkheid wilt inschakelen, stelt u het volgende in:

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

Azure PowerShell-implementatie

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 rol 'Key Vault Secrets User' moet aan Key Vault worden toegewezen voor VM-identiteit.

Problemen oplossen en ondersteuning bieden

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. Wanneer u onverwachte resultaten hebt met Azure CLI-opdrachten, raadpleegt u Hoe de Azure CLI succesvol te 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

Symlink gebruiken

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.

Certificaatinstallatie in Linux

De Key Vault VM-extensie voor Linux installeert certificaten als PEM-bestanden met de volledige certificaatketen. Wanneer een certificaat wordt gedownload uit Key Vault, is de extensie:

1. Hiermee maakt u een opslagmap op basis van de certificateStoreLocation instelling (standaard /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ als er niets is opgegeven)
2. Installeert de volledige certificaatketen en persoonlijke sleutel in een PEM-bestand volgens RFC 5246 sectie 7.4.2 in deze specifieke volgorde:
   • Leaf-certificaat (end-entity certificate) komt als eerste
   • Tussenliggende certificaten volgen elkaar in volgorde op, waarbij elk certificaat het certificaat direct ervoor certificeert.
   • Basiscertificaat, indien aanwezig (hoewel dit niet vereist is voor validatie als dit al wordt vertrouwd door het systeem)
   • De persoonlijke sleutel, die overeenkomt met het leaf-certificaat, wordt aan het einde van het bestand geplaatst
3. Hiermee wordt automatisch een symbolische koppeling gemaakt met de naam [VaultName].[CertificateName] die verwijst naar de nieuwste versie van het certificaat

Deze aanpak zorgt ervoor dat:

• Toepassingen hebben altijd toegang tot de volledige certificaatketen die nodig is voor validatie
• De certificaatketen is goed geordend voor TLS-handshakes volgens RFC-standaarden
• De persoonlijke sleutel is beschikbaar voor gebruik door de service
• Toepassingen kunnen verwijzen naar een stabiel symbolisch koppelingspad dat automatisch wordt bijgewerkt wanneer certificaten worden vernieuwd
• Er is geen herconfiguratie van toepassingen nodig wanneer certificaten worden gewisseld of vernieuwd

Voorbeeld van certificaatpadstructuur

Voor een certificaat van exampleVault.vault.azure.net met de naam myCertificate, ziet de mapstructuur er als volgt uit:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── exampleVault.myCertificate -> exampleVault.myCertificate.1234567890abcdef
├── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file (current version)
└── exampleVault.myCertificate.0987654321fedcba    # Previous version (if exists)

Toepassingen moeten worden geconfigureerd voor het gebruik van het symbolische koppelingspad (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) om ervoor te zorgen dat ze altijd toegang hebben tot de meest recente certificaatversie.

Wanneer u aangepaste locaties voor het certificaatarchief en de customSymbolicLinkName instelling gebruikt, volgt de structuur dit patroon:

/path/to/custom/store/
├── customLinkName -> exampleVault.myCertificate.1234567890abcdef
└── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file

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 Azure-ondersteuningsincident indienen. Ga naar de Ondersteuningssite van Azure en selecteer Ondersteuning krijgen. Lees de veelgestelde vragen over Microsoft Azure-ondersteuning voor informatie over het gebruik van Azure-ondersteuning.