Extension de machine virtuelle Key Vault pour Linux

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 :

• Ubuntu 22.04 et versions ultérieures
• Linux Azure

Types de contenu de certificat pris en charge

• PKCS#12
• PEM

Fonctionnalités

L’extension de machine virtuelle Key Vault pour Linux version 3.0+ prend en charge :

• 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

• Une instance Key Vault avec certificat. Voir Créer un coffre de clés.

• Identité managée affectée sur les machines virtuelles/groupes de machines virtuelles identiques.

• Le rôle Utilisateur des secrets Key Vault au niveau de l’étendue Key Vault pour les machines virtuelles et l’identité managée Azure Virtual Machine Scale Sets. Ce rôle récupère la partie d’un secret d’un certificat. Pour plus d’informations, consultez les articles suivants :

  • Authentification dans Azure Key Vault
  • Utilisation des autorisations de secret, de clé et de certificat de RBAC Azure avec Azure Key Vault
  • Attribution de rôle d’étendue de coffre de clés

• Les groupes de machines virtuelles identiques doivent avoir le paramètre d’identité suivant : "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

• L’extension AKV doit avoir ce paramètre : "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Mise à niveau de l’extension de machine virtuelle Key Vault

• Si vous devez effectuer une mise à niveau d’une version antérieure vers la version 3.0+, vous devez d’abord supprimer la version précédente, puis installer la version 3.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 3.0

• 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é la version la 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

Le code JSON suivant fournit le schéma de l’extension de machine virtuelle Key Vault. Tous les paramètres sont spécifiés en tant que paramètres simples (non protégés), car aucun n’est considéré comme sensible. Pour configurer l’extension, vous devez spécifier une liste de certificats à surveiller, la fréquence à laquelle interroger les mises à jour et le chemin de destination pour le stockage des certificats. 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.: "00001111-aaaa-2222-bbbb-3333cccc4444".>
        }>
       }
      }
    }

Valeurs de propriétés

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.

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

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 effectue une nouvelle tentative de téléchargement initial jusqu’à 25 fois avec des périodes d’interruption croissantes, pendant lesquelles elle reste dans un Transitioning état. Si les nouvelles tentatives sont épuisées, l’extension signale un état Error.

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

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

Déploiement d’Azure PowerShell

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

Liens symboliques

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.

Installation de certificat sur Linux

L’extension de machine virtuelle Key Vault pour Linux installe des certificats en tant que fichiers PEM avec la chaîne de certificats complète incluse. Lorsqu’un certificat est téléchargé à partir de Key Vault, l’extension :

1. Crée un dossier de stockage en fonction du certificateStoreLocation paramètre (par défaut /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ , s’il n’est pas spécifié)
2. Installe la chaîne de certificats complète et la clé privée dans un fichier PEM suivant la section RFC 5246 7.4.2 dans cet ordre spécifique :
   • Le certificat final (certificat d’entité finale) est fourni en premier
   • Les certificats intermédiaires suivent dans l'ordre, chacun certifiant directement le précédent.
   • Certificat racine, s’il est présent (bien qu’il ne soit pas requis pour la validation s’il est déjà approuvé par le système)
   • Clé privée, correspondant au certificat de feuille, est placée à la fin du fichier
3. Crée automatiquement un lien symbolique nommé [VaultName].[CertificateName] qui pointe vers la dernière version du certificat

Cette approche garantit que :

• Les applications ont toujours accès à la chaîne de certificats complète nécessaire à la validation
• La chaîne de certificats est correctement ordonnée pour les établissements de liaisons TLS en fonction des normes RFC
• La clé privée est disponible pour une utilisation par le service
• Les applications peuvent référencer un chemin de lien symbolique stable qui est automatiquement mis à jour lorsque les certificats sont renouvelés
• Aucune reconfiguration d’application n’est nécessaire lorsque les certificats sont pivotés ou renouvelés

Exemple de structure de chemin d’accès au certificat

Pour un certificat de exampleVault.vault.azure.net portant le nom myCertificate, la structure de répertoires se présente comme suit :

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

Les applications doivent être configurées pour utiliser le chemin de liaison symbolique (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) pour s’assurer qu’elles accèdent toujours à la version de certificat la plus récente.

Lorsque vous utilisez des emplacements de magasin de certificats personnalisés et le customSymbolicLinkName paramètre, la structure suit ce modèle :

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

Forum Aux Questions (FAQ)

• Le nombre de observedCertificates que vous pouvez configurer est-il limité ? Non, l’extension de machine virtuelle Key Vault n’a pas de limite sur le nombre de certificats observés.

Soutien

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.