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 :

Remarque

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 de l’extension de machine virtuelle (version 1/2) ou des paramètres de certificat individuels (version 3). 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

Mises à jour dans la version 3.0+

La version 3.0+ de l’extension de machine virtuelle Key Vault pour Linux ajoute la prise en charge des fonctionnalités suivantes :

  • Ajouter des autorisations de liste de contrôle d’accès pour les certificats téléchargés afin de fournir un accès en lecture pour les utilisateurs et les groupes
  • Configuration de l’emplacement d’installation du certificat
  • Prise en charge des noms symboliques personnalisés
  • Prise en charge de l’intégration de la journalisation des extensions de machine virtuelle via Fluentd

Prérequis

Version d’extension de machine virtuelle Key Vault

  • Les utilisateurs peuvent choisir de mettre à niveau leur version d’extension de machine virtuelle Key Vault existante vers une version plus récente.

  • Si vous préférez effectuer une mise à niveau vers une version plus récente, vous devez d’abord supprimer la version précédente, puis installer une version plus récente.

  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

L’indicateur --version 3.0 est facultatif, car la dernière version est installée par défaut.

  • Si la machine virtuelle a des certificats téléchargés par une version précédente, la suppression de l’extension de machine virtuelle ne supprime pas les certificats téléchargés. Après avoir installé une version plus récente, 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": "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".>
        }>
       }
      }
    }

Remarque

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 3.0 int
pollingIntervalInS 3600 string
certificateStoreName C’est ignoré sur Linux. string
linkOnRenewal false boolean
requireInitialSync true boolean
aclEnabled true booléen
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] tableau de chaînes
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName (facultatif) "app1Cert1" string
observedCertificates/acls (facultatif) "{...}, {...}" tableau de chaînes
authenticationSettings (facultatif) {...} object
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings (facultatif) {...} object
loggingSettings/logger "fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "forward" string
loggingSettings/servicename "akvvm_service" 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": "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">
          }
        } 
      }
    }

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. Toutefois, vous pouvez le configurer pour attendre qu’il télécharge correctement 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 :

L’extension de machine virtuelle Azure Key Vault peut être déployée avec Azure PowerShell. Enregistrez les paramètres d’extension de machine virtuelle Key Vault dans un fichier JSON (settings.json).

Les extraits de code JSON suivants fournissent des exemples de paramètres pour le déploiement de l’extension de machine virtuelle Key Vault avec 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"
   }      
}
  • Pour déployer l’extension 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 "3.0" -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 = (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

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 :

L’extension de machine virtuelle Azure Key Vault peut être déployée à l’aide d’Azure CLI. Enregistrez les paramètres d’extension de machine virtuelle Key Vault dans un fichier JSON (settings.json).

Les extraits de code JSON suivants fournissent des exemples de paramètres pour le déploiement de l’extension de machine virtuelle Key Vault avec 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"
   }      
}
  • 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 3.0 `
      --enable-auto-upgrade true `
      --settings "@settings.json"
  • 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 3.0 `
    --enable-auto-upgrade true `
    --settings "@settings.json"

Tenez compte des restrictions et conditions suivantes :

  • Restrictions de Key Vault :
    • Doit exister au moment du déploiement
    • Le rôle utilisateur des secrets Key Vault doit être attribué à Key Vault pour l’identité de machine virtuelle

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 machine virtuelle Key Vault existent localement sur la machine virtuelle et sont les plus informatifs en ce qui concerne la résolution des problèmes. Vous pouvez utiliser la section de journalisation facultative pour l’intégrer au fournisseur de journalisation via fluentd

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.