Extension de machine virtuelle Key Vault pour Linux

  • Article

L’extension de machine virtuelle Key Vault assure l’actualisation automatique des certificats stockés dans un coffre de clés Azure. Plus précisément, l’extension surveille une liste de certificats observés stockés dans des coffres de clés. L’extension récupère et installe les certificats correspondants après la détection d’un changement. Ce document présente les plateformes, configurations et options de déploiement qui sont prises en charge pour l’extension de machine virtuelle Key Vault pour Linux.

Système d’exploitation

L’extension de machine virtuelle Key Vault prend en charge les distributions Linux suivantes :

Notes

L’extension de machine virtuelle Key Vault télécharge les certificats à l’emplacement par défaut ou à l’emplacement fourni par la propriété « certStoreLocation » dans les paramètres d’extension de machine virtuelle. L’extension de machine virtuelle Key Vault met à jour l’autorisation du dossier sur 700 (drwx------) qui octroie l’autorisation de lecture, d’écriture et d’exécution au propriétaire du dossier uniquement

Types de contenu de certificat pris en charge

  • PKCS#12
  • PEM

Prérequis

Version d’extension de machine virtuelle Key Vault

  • Les utilisateurs peuvent choisir de mettre à niveau leur version d’extension de machine virtuelle du coffre de clés vers V2.0 pour utiliser la fonctionnalité de téléchargement de chaîne d’approbation complète. Les certificats d’émetteur (intermédiaire et racine) sont inclus avec le certificat feuille dans le fichier PEM.

  • Si vous préférez mettre à niveau vers v2.0, vous devez d'abord supprimer v1.0, puis installer v2.0.

  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 2.0

L’indicateur --version 2.0 est facultatif, car la version la plus récente est installée par défaut.

  • Si la machine virtuelle dispose de certificats téléchargés par v1.0, la suppression de l’extension AKVVM v1.0 ne supprime pas les certificats téléchargés. Après l’installation de v2.0, les certificats existants ne sont pas modifiés. Vous devez supprimer les fichiers de certificat ou restaurer le certificat pour obtenir le fichier PEM avec une chaîne complète sur la machine virtuelle.

Schéma d’extensions

L’extrait JSON suivant illustre le schéma de l’extension de machine virtuelle Key Vault. L’extension ne nécessite pas de paramètres protégés, car tous ses paramètres sont considérés comme des informations sans impact sur la sécurité. Par contre, la liste des secrets surveillés, la fréquence d’interrogation et le magasin de certificats de destination lui sont indispensables. Plus précisément :

    {
      "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": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <It's ignored on Linux>,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        },
        "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".>
        }
       }
      }
    }

Notes

Vos URL de certificats observés doivent être de la forme https://myVaultName.vault.azure.net/secrets/myCertName.

Ceci est dû au fait que le chemin /secrets retourne le certificat complet, y compris la clé privée, contrairement au chemin /certificates. Vous trouverez plus d’informations sur les certificats ici : Certificats Key Vault

Important

La propriété « authenticationSettings » est requise pour les machines virtuelles avec n’importe quelles identités affectées par l’utilisateur. Même si vous voulez utiliser une identité affectée par le système, cela reste nécessaire ; sinon, l’extension de la machine virtuelle ne sait pas quelle identité utiliser. Sans cette section, une machine virtuelle avec des identités affectées par l’utilisateur entraîne l’échec de l’extension Key Vault et l’impossibilité de télécharger des certificats. Définissez msiClientId sur l’identité qui s’authentifiera auprès du Key Vault.

Également requis pour les machines virtuelles avec Azure Arc. Affectez à msiEndpoint la valeur http://localhost:40342/metadata/identity.

Valeurs de propriétés

Nom Valeur/Exemple Type de données
apiVersion 2022-07-01 Date
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 2.0 int
pollingIntervalInS 3600 string
certificateStoreName C’est ignoré sur Linux. string
linkOnRenewal false boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
requireInitialSync true boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] tableau de chaînes
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Déploiement de modèle

Les extensions de machines virtuelles Azure peuvent être déployées avec des modèles Azure Resource Manager. Les modèles sont idéaux lorsque vous déployez une ou plusieurs machines virtuelles nécessitant une actualisation de certificats après le déploiement. Vous pouvez déployer l’extension sur des machines virtuelles individuelles ou dans des groupes de machines virtuelles identiques. La configuration et le schéma sont communs aux deux types de modèle.

La configuration JSON d’une extension de machine virtuelle doit être imbriquée dans le fragment de la ressource de machine virtuelle du modèle, plus précisément dans l’objet "resources": [] de la machine virtuelle et, dans le cas d’un groupe de machines virtuelles identiques, sous l’objet "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Notes

L’extension de machine virtuelle nécessite l’attribution d’une identité managée par le système ou l’utilisateur pour s’authentifier auprès du coffre de clés. Consultez Comment s’authentifier auprès de Key Vault et attribuer une stratégie d’accès Key Vault.

    {
      "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": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ingnored on linux>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        }
      }
      }
    }

Tri des dépendances d’extension

L’extension de machine virtuelle Key Vault prend en charge le tri des extensions si elle est configurée. Par défaut, l’extension signale un démarrage réussi dès le début de l’interrogation. Cependant, vous pouvez la configurer de façon à attendre d’avoir téléchargé la liste complète des certificats avant de signaler un démarrage réussi. Si d’autres extensions dépendent de certificats installés pour démarrer, l’activation de ce paramètre va permettre à ces extensions de déclarer une dépendance vis-à-vis de l’extension Key Vault. Cela empêchera ces extensions de démarrer avant que tous les certificats dont elles dépendent aient été installés. L’extension retentera le téléchargement initial indéfiniment et restera à l’état Transitioning.

Pour activer la dépendance d’extension, définissez ce qui suit :

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

Remarque

L’utilisation de cette fonctionnalité n’est pas compatible avec un modèle ARM qui crée une identité affectée par le système et met à jour une stratégie d’accès Key Vault avec celle-ci. Cela conduit à une impasse, car la stratégie d’accès du coffre ne peut pas être mise à jour tant que toutes les extensions n’ont pas démarré. Vous devez utiliser à la place une identité MSI unique affectée par l’utilisateur et inscrire vos coffres au préalable sur une liste de contrôle d’accès en utilisant cette identité avant de les déployer.

Déploiement d’Azure PowerShell

Avertissement

Les clients PowerShell ajoutent souvent \ à " dans settings.json, ce qui entraîne l’échec de akvvm_service avec l’erreur suivante : [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell vous permet de déployer l’extension de machine virtuelle Key Vault sur une machine virtuelle ou un groupe de machines virtuelles identiques existants.

  • Pour déployer l’extension sur une machine virtuelle :

        # Build settings
    $settings = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName =  "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"


    # Start the deployment
    Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

  • Pour déployer l’extension sur un groupe de machines virtuelles identiques :

    
    # Build settings
    $settings = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"

    # Add Extension to VMSS
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -Setting $settings

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

Déploiement de l’interface de ligne de commande Azure

L’interface de ligne de commande Azure permet de déployer l’extension de machine virtuelle Key Vault sur une machine virtuelle ou un groupe de machines virtuelles identiques existants.

  • Pour déployer l’extension sur une machine virtuelle :

       # Start the deployment
     az vm extension set -n "KeyVaultForLinux" `
     --publisher Microsoft.Azure.KeyVault `
     -g "<resourcegroup>" `
     --vm-name "<vmName>" `
     --version 2.0 `
     --enable-auto-upgrade true `
     --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

  • Pour déployer l’extension sur un groupe de machines virtuelles identiques :

          # Start the deployment
      az vmss extension set -n "KeyVaultForLinux" `
      --publisher Microsoft.Azure.KeyVault `
      -g "<resourcegroup>" `
      --vmss-name "<vmssName>" `
      --version 2.0 `
      --enable-auto-upgrade true `
      --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

Tenez compte des restrictions et conditions suivantes :

Dépannage et support

Vous pouvez récupérer des données sur l’état des déploiements des extensions à partir du portail Azure et par le biais d’Azure PowerShell. Pour voir l’état de déploiement des extensions d’une machine virtuelle donnée, exécutez la commande suivante à l’aide d’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 peut s’exécuter dans plusieurs environnements d’interpréteur de commandes, mais avec de légères variantes de format. Si vous avez des résultats inattendus avec des commandes Azure CLI, consultez Comment utiliser Azure CLI avec succès.

Journaux et configuration

Les journaux d’extension de machines virtuelles Key Vault existent uniquement localement sur la machine virtuelle et sont plus instructifs lorsqu’il s’agit de résoudre des problèmes.

Emplacement Description
/var/log/waagent.log Indique quand une mise à jour de l’extension s’est produite.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Examinez les journaux du service d’extension de machines virtuelles Key Vault pour déterminer l’état du service akvvm_service et du télécharger du certificat. Vous pouvez trouver l’emplacement de téléchargement des fichiers PEM dans les fichiers qui ont une entrée appelée « certificate file name » (nom du fichier de certificat). Si certificateStoreLocation n’est pas spécifié, sa valeur par défaut est /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/* La configuration et fichiers binaires pour le service d’extension de machines virtuelles Key Vault.

Les liens symboliques ou Symkink sont des raccourcis avancés. Vous pouvez utiliser ce lien symbolique ([VaultName].[CertificateName]) pour récupérer automatiquement la dernière version du certificat sur Linux sans avoir à analyser le dossier.

Forums Aux Questions (FAQ)

  • Le nombre de observedCertificates que vous pouvez configurer est-il limité ? Non, l'extension de machine virtuelle Key Vault ne limite pas le nombre de observedCertificates.

Support

Si vous avez besoin d’une aide supplémentaire à quelque étape que ce soit dans cet article, vous pouvez contacter les experts Azure sur les forums MSDN Azure et Stack Overflow. Vous pouvez également signaler un incident au support Azure. Accédez au site du support Azure , puis cliquez sur Obtenir un support. Pour plus d’informations sur l’utilisation du support Azure, lisez le FAQ du support Microsoft Azure.