Azure Key Vault extension de machine virtuelle pour Linux

L’extension de machine virtuelle Azure Key Vault actualise automatiquement les certificats stockés dans un Azure key vault. L’extension surveille une liste de certificats observés stockés dans des coffres de clés. Lorsque l’extension détecte une modification, elle récupère et installe les certificats correspondants. Cet article décrit les plateformes, configurations et options de déploiement prises en charge pour l’extension de machine virtuelle Key Vault pour Linux.

Systèmes d’exploitation

L’extension de machine virtuelle Key Vault pour Linux prend en charge les distributions suivantes, sur AMD64 et ARM64 :

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

Types de contenu de certificat pris en charge

L’extension de machine virtuelle Key Vault prend en charge les types de contenu de certificat suivants :

• PKCS#12
• PEM

Fonctionnalités

Extension de machine virtuelle Key Vault pour Linux version 4.x :

• Installe les deux versions les plus récentes de chaque certificat.
• Installe chaque certificat sous forme de fichiers fractionnés : un fichier de chaîne .pem complète et un fichier de clé privée distinct .keyid , chacun écrit en tant que fichier avec version avec un lien symbolique stable qui pointe vers la dernière version.
• Effectue une validation de la chaîne de certificats avant d’installer tout certificat comportant l’utilisation étendue de la clé (EKU) Authentification du serveur TLS. La validation échoue : un certificat est toujours installé si la validation ne peut pas se terminer en raison de problèmes réseau temporaires. Les certificats sans la référence EKU d’authentification du serveur ne sont pas soumis à cette vérification.
• Applique des listes de contrôle d’accès POSIX pour accorder aux utilisateurs et groupes configurés l’accès en lecture à la clé privée. L’application des ACL est toujours activée.
• Prend en charge une substitution de l’authentification facultative pour chaque certificat, qui permet à chaque certificat observé de s’authentifier auprès de Key Vault à l’aide d’une identité managée différente de celle utilisée par défaut par l’extension. Pour plus d’informations, consultez schéma d’extension.
• Prend en charge l’intégration de la journalisation des extensions de machine virtuelle via Fluentd. Pour plus d’informations, consultez Journalisation avec Fluentd.

Mise à niveau à partir de la version 3.0

Si vous effectuez une mise à jour à partir de la version 3.0, les fonctionnalités suivantes sont modifiées ou supprimées.

Modifications avec rupture générales :

• pollingIntervalInS est maintenant limité à entre 5 et 60 minutes. Par défaut, l’extension interroge une fois par heure.
• requireInitialSync est supprimé. L’extension signale uniquement la réussite s’il installe tous les certificats configurés.
• Vous ne pouvez plus configurer une version spécifique d’un certificat. Les URL de certificat observées doivent être sans version.
• Le schéma hérité où observedCertificates se trouve une liste de chaînes d’URL n’est plus pris en charge. Chaque entrée doit être un objet avec une url propriété.

Modifications avec rupture propres à Linux :

• La chaîne de certificats et la clé privée sont désormais écrites dans des fichiers distincts. Dans la version 3.0, la chaîne complète et la clé privée ont été combinées en un seul fichier PEM. Dans la version 4.x, l’extension écrit la chaîne complète dans <vaultname>.<certname>.pem et la clé privée dans un fichier distinct <vaultname>.<certname>.keyid . Cette modification est avec rupture : les applications qui attendent la clé et la chaîne dans un même fichier doivent être mises à jour pour lire la chaîne dans le fichier .pem et la clé privée dans le fichier .keyid. Le .luma fichier est mis à jour une fois les liens symboliques mis à jour. Les applications doivent donc surveiller les modifications apportées à ce fichier de métadonnées.
• customSymbolicLinkName est supprimé. L’extension utilise toujours le nom <vaultname>.<certname>de lien symbolique par défaut.
• aclEnabled est supprimé. La fonctionnalité ACL est désormais toujours activée.
• certificateStoreName est ignoré sur Linux et n’a aucun effet.

Prérequis

Passez en revue les conditions préalables suivantes pour utiliser l’extension de machine virtuelle Key Vault pour Linux :

• Une instance Key Vault Azure avec un certificat. Pour plus d’informations, consultez Créer un coffre de clé avec le portail Azure.

• Une machine virtuelle avec une identité managée affectée.

• Attribuez le rôle d’utilisateur Key Vault Secrets au niveau de l’étendue Key Vault à l’identité managée pour la machine virtuelle ou Groupes de machines virtuelles identiques Azure. Ce rôle récupère la partie secrète d’un certificat. Pour plus d’informations, consultez les articles suivants :

  • Authentification dans Azure Key Vault
  • Utilisez les autorisations RBAC de secret, de clé et de certificat avec Azure Key Vault
  • attribution de rôle dans le périmètre de Key Vault

• Configurez Virtual Machine Scale Sets avec la configuration suivante identity :

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

• Configurez l’extension de machine virtuelle Key Vault avec la configuration suivante authenticationSettings :

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

Schéma d’extensions

L’extrait JSON suivant illustre le schéma de l’extension de machine virtuelle Key Vault. Avant d’examiner les options d’implémentation de schéma, passez en revue les notes importantes suivantes.

• L’extension ne nécessite pas de paramètre protégés. Tous les paramètres sont des informations publiques.

• Les URL de certificat observées doivent utiliser le formulaire https://myVaultName.vault.azure.net/secrets/myCertName.

  Ce format est requis, car le chemin /secrets renvoie le certificat complet, y compris la clé privée, tandis que le chemin /certificates ne le renvoie pas. Pour plus d’informations sur les certificats, consultez Vue d’ensemble des clés, des secrets et des certificats Azure Key Vault. Vous ne pouvez pas spécifier une version spécifique du certificat.

• L’hôte d’URL doit être un hôte Azure Key Vault reconnu.

• La authenticationSettings propriété est requise pour les machines virtuelles avec toutes les identités affectées par l’utilisateur et pour les machines virtuelles compatibles avec Azure Arc.

  Omettez cette propriété lorsque vous utilisez une identité affectée par le système. Pour les machines virtuelles compatibles avec Azure Arc, définissez msiEndpoint sur 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">
         }
      }
   }
}

Valeurs de propriétés

Le schéma JSON comprend les propriétés suivantes.

Déploiement de modèle

Déployez Azure extensions de machine virtuelle à l’aide de modèles Azure Resource Manager (ARM). Les modèles sont idéaux lorsque vous déployez une ou plusieurs machines virtuelles qui nécessitent une actualisation post-déploiement des certificats. Vous pouvez déployer l’extension sur des machines virtuelles individuelles ou des instances Virtual Machine Scale Sets. La configuration et le schéma sont communs aux deux types de modèle.

La configuration JSON d’une extension de coffre de clés est imbriquée dans le modèle de machine virtuelle ou de Virtual Machine Scale Sets. Pour une extension de ressource de machine virtuelle, la configuration est imbriquée sous l’objet "resources": [] de machine virtuelle. Pour une extension d’instance de Virtual Machine Scale Sets, la configuration est imbriquée sous l’objet "virtualMachineProfile":"extensionProfile":{"extensions" :[].

L’extrait de code JSON suivant fournit des exemples de paramètres pour un déploiement de modèle ARM de l’extension de machine virtuelle Key Vault.

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

Mise à niveau automatique de l’extension

L’extension de machine virtuelle Key Vault prend en charge la mise à niveau automatique des extensions pour les machines virtuelles et les groupes identiques dans Azure. Azure met automatiquement l’extension à jour lorsque vous définissez sur autoUpgradeMinorVersion les propriétés enableAutomaticUpgrade et true dans les exemples précédents.

Tri des dépendances d’extension

L’extension de machine virtuelle Key Vault prend en charge l’ordre des dépendances d’extension. L’extension signale un démarrage réussi après le téléchargement et l’installation de tous les certificats.

Si vous utilisez d’autres extensions qui nécessitent l’installation de certificats avant de commencer, vous pouvez utiliser l’ordre des dépendances d’extension pour déclarer une dépendance sur l’extension de machine virtuelle Key Vault.

Au démarrage, l’extension de machine virtuelle Key Vault tente de télécharger et d’installer des certificats jusqu’à 25 fois avec des périodes d’interruption croissantes, pendant lesquelles elle reste dans un état Transitioning. Si les nouvelles tentatives sont épuisées, l’extension signale un état d’erreur . Une fois tous les certificats installés, l’extension de machine virtuelle Key Vault signale un démarrage réussi.

Pour plus d’informations sur la configuration des dépendances entre les extensions, consultez Provisionnement d’extensions de séquence dans Virtual Machine Scale Sets.

déploiement Azure PowerShell

Déployez l’extension de machine virtuelle Azure Key Vault à l’aide de Azure PowerShell. Enregistrez Key Vault paramètres d’extension de machine virtuelle dans un fichier JSON (settings.json).

L’extrait de code JSON suivant fournit des exemples de paramètres pour déployer l’extension de machine virtuelle Key Vault à l’aide de 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"
   }
}

Déployer sur une machine virtuelle

# 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

Déployer sur un Virtual Machine Scale Sets instance

# 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

déploiement Azure CLI

Déployez l’extension de machine virtuelle Azure Key Vault à l’aide de la Azure CLI. Enregistrez Key Vault paramètres d’extension de machine virtuelle dans un fichier JSON (settings.json).

L’extrait de code JSON suivant fournit des exemples de paramètres pour déployer l’extension de machine virtuelle Key Vault à l’aide du 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"
   }
}

Déployer sur une machine virtuelle

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

Déployer sur un Virtual Machine Scale Sets instance

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

Journalisation avec Fluentd

L’extension de machine virtuelle Key Vault peut transférer ses journaux à un collecteur de journaux Fluentd. Vérifiez que votre collecteur de journaux est en cours d’exécution et à l’écoute sur le point de terminaison spécifié dans les paramètres.

Ajoutez la section suivante à vos paramètres d’extension :

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

Résoudre les problèmes

Utilisez ces suggestions pour résoudre les problèmes de déploiement.

Questions fréquentes

Existe-t-il une limite au nombre de certificats observés ?

Non. L’extension de machine virtuelle Key Vault ne limite pas le nombre de certificats observés (observedCertificates).

Quel est l’emplacement par défaut où les certificats sont installés ?

Si vous ne spécifiez certificateStoreLocationpas, l'extension écrit des certificats dans /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Comment forcer l’extension à récupérer un nouveau certificat ?

Redémarrez le service akvvm_service (nom d’affichage extension de machine virtuelle Key Vault).

Comment utiliser une identité différente pour un certificat spécifique ?

Ajoutez un objet authenticationOverride avec la cible msiClientId à l’entrée de ce certificat dans observedCertificates. Les certificats sans dérogation utilisent l’élément authenticationSettings de niveau supérieur.

Afficher l’état de l’extension

Vérifiez l’état de votre déploiement d’extension dans le portail Azure, ou à l’aide de PowerShell ou d’Azure CLI.

Pour voir l’état du déploiement des extensions pour une machine virtuelle donnée, exécutez les commandes suivantes.

• Azure PowerShell :

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

• Interface de ligne de commande Azure :

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

Le Azure CLI peut s’exécuter dans plusieurs environnements shell, mais avec de légères variations de format. Si vous avez des résultats inattendus avec des commandes Azure CLI, voir Comment utiliser Azure CLI avec succès.

Passer en revue les journaux et la configuration

Les journaux d’extension Key Vault machine virtuelle existent uniquement localement sur la machine virtuelle. Passez en revue les détails du journal pour vous aider à résoudre les problèmes.

Installation de certificat sur Linux

L’extension de machine virtuelle Key Vault pour Linux installe des certificats en tant que fichiers PEM. Lorsque l’extension télécharge un certificat à partir de Key Vault, il :

1. Crée un dossier de stockage basé sur le certificateStoreLocation paramètre. Si vous ne spécifiez pas ce paramètre, l'emplacement par défaut est /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Écrit la chaîne de certificats (feuille, puis intermédiaires, puis racine s’il est présent dans Key Vault) dans un fichier de chaîne .pem complète avec version et écrit la clé privée correspondante dans un fichier avec version.keyid.
3. Applique des ACL POSIX à la clé privée en fonction de la acls configuration spécifiée, ce qui accorde l’accès en lecture aux utilisateurs et groupes répertoriés. Les fichiers sont sinon accessibles uniquement à leur propriétaire.
4. Crée ou met à jour un lien symbolique stable (<vaultname>.<certname>.pem et <vaultname>.<certname>.keyid) qui pointe vers la dernière version du certificat. La liaison se produit toujours.

Emplacement du magasin de certificats par défaut

Si vous ne spécifiez pas d'emplacement, l'extension installe les certificats sous /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. L’extension ignore certificateStoreName sur Linux.

Fichiers de sortie de certificat

Pour le coffre mykv et le secret server-tls, une synchronisation réussie produit :

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

Configurez les applications pour référencer le chemin de lien symbolique stable (par exemple) /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pemafin qu’elles lisent toujours la version de certificat la plus récente sans reconfiguration lors du renouvellement.

Contrôle d’accès au certificat

Par défaut, les fichiers de certificat et de clé privée sont lisibles uniquement par leur propriétaire. Accordez l’accès en lecture à d’autres utilisateurs et groupes à l’aide du acls tableau dans la configuration du certificat :

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

Chaque entrée peut spécifier un utilisateur, un groupe ou les deux. L’application des ACL est toujours activée et accorde actuellement un accès en lecture.

Renouvellement du certificat

Lorsque les certificats sont renouvelés dans Key Vault, l’extension effectue automatiquement les actions suivantes lors du prochain sondage :

1. Télécharge la nouvelle version du certificat.
2. Écrit les nouveaux fichiers versionnés .pem et .keyid.
3. Met à jour le lien symbolique stable pour pointer vers la nouvelle version afin que les chemins d’accès d’application existants continuent de se résoudre vers le dernier certificat.

Obtenir du support

Microsoft fournit uniquement la prise en charge de la version majeure 3.0 et ultérieure de l’extension de machine virtuelle Key Vault. Si vous utilisez la version 1.0, effectuez une mise à niveau vers la dernière version avant de demander la prise en charge.

Utilisez ces autres options pour résoudre les problèmes de déploiement :

• Pour obtenir de l’aide, contactez les experts Azure dans Microsoft Q& A.

• Si vous ne trouvez pas de réponse sur le site, vous pouvez publier une question pour recevoir des réponses de Microsoft ou d'autres membres de la communauté.

• Vous pouvez aussi contacter le Support Microsoft. Pour plus d’informations sur l’utilisation de support Azure, consultez How to create an support Azure request.