Partager via

Créer un fichier Bicep ou un modèle JSON de modèle ARM pour Azure Image Builder

  • Article

S’applique à : ✔️ Machines virtuelles Linux ✔️ Machines virtuelles Windows ✔️ Groupes identiques flexibles

Azure Image Builder utilise un fichier Bicep ou un fichier de modèle JSON de modèle ARM pour passer des informations au service Image Builder. Cet article présente les sections des fichiers pour vous aider à créer le vôtre. Pour les dernières versions de l’API, consultez Référence de modèle. Pour voir des exemples de fichiers .json complets, consultez GitHub sur le générateur d’images Azure.

Le format de base est le suivant :

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "customize": [],
    "errorHandling":[],
    "distribute": [],
    "optimize": [],
    "source": {},
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "validate": {},
    "vmProfile": {
      "vmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
        "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
        "proxyVmSize": "<vmSize>"
      },
      "userAssignedIdentities": [
              "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName1>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName2>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName3>",
        ...
      ]
    }
  }
}

Version d’API

La version de l’API change au fil du temps à mesure que l’API change. Consultez Nouveautés d’Azure VM Image Builder pour les principales modifications et mises à jour de fonctionnalités de l’API pour le service Azure VM Image Builder.

Type

type est le type de ressource, qui doit être Microsoft.VirtualMachineImages/imageTemplates.

"type": "Microsoft.VirtualMachineImages/imageTemplates",

Emplacement

L’emplacement est la région où l’image personnalisée est créée. Les régions suivantes sont prises en charge :

  • USA Est
  • USA Est 2
  • Centre-USA Ouest
  • USA Ouest
  • USA Ouest 2
  • USA Ouest 3
  • États-Unis - partie centrale méridionale
  • Europe Nord
  • Europe Ouest
  • Asie Sud-Est
  • Sud-Australie Est
  • Australie Est
  • Sud du Royaume-Uni
  • Ouest du Royaume-Uni
  • Brésil Sud
  • Centre du Canada
  • Inde centrale
  • USA Centre
  • France Centre
  • Allemagne Centre-Ouest
  • Japon Est
  • Centre-Nord des États-Unis
  • Norvège Est
  • Suisse Nord
  • Inde Ouest Jio
  • Émirats arabes unis Nord
  • Asie Est
  • Centre de la Corée
  • Afrique du Sud Nord
  • Qatar Central
  • USGov Arizona (préversion publique)
  • USGov Virginie (préversion publique)
  • Chine Nord 3 (Préversion publique)
  • Suède Centre
  • Pologne Centre
  • Italie Nord
  • Israël Central

Important

Inscrivez la fonctionnalité Microsoft.VirtualMachineImages/FairfaxPublicPreview pour accéder à la préversion publique d’Azure Image Builder dans les régions Azure Government (USGov Arizona et USGov Virginie).

Important

Inscrire la fonctionnalité Microsoft.VirtualMachineImages/MooncakePublicPreview pour accéder à la préversion publique d’Azure Image Builder dans la région Chine Nord 3.

Pour accéder à la préversion publique d’Azure VM Image Builder dans les régions Azure Government (USGov Arizona et USGov Virginie), vous devez inscrire la fonctionnalité Microsoft.VirtualMachineImages/FairfaxPublicPreview. Exécutez pour cela la commande suivante dans PowerShell ou Azure CLI :

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

Pour accéder à la préversion publique d’Azure VM Image Builder dans la région Chine Nord 3, vous devez inscrire la fonctionnalité Microsoft.VirtualMachineImages/MooncakePublicPreview. Exécutez pour cela la commande suivante dans PowerShell ou Azure CLI :

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Résidence des données

Le service Azure VM Image Builder ne stocke pas/ne traite pas les données client en dehors des régions qui imposent des exigences strictes en matière de résidence des données dans une seule région lorsqu'un client demande une build dans cette région. En cas d’interruption de service pour des régions qui sont soumises à des exigences en matière de résidence des données, vous devez créer des fichiers Bicep/modèles dans une région et une zone géographique différentes.

Redondance de zone

La distribution prend en charge la redondance de zone, les disques durs virtuels sont distribués dans un compte de stockage redondant dans une zone (ZRS) par défaut et la version Azure Compute Gallery (anciennement Shared Image Gallery) prend en charge un type de stockage ZRS, s’il est spécifié.

Étiquettes

Les étiquettes sont des paires clé/valeur que vous pouvez spécifier pour l’image générée.

Identité

Il existe deux façons d’ajouter des identités affectées par l’utilisateur, comme expliqué ci-dessous.

Identité affectée par l’utilisateur pour la ressource de modèle d’image Azure Image Builder

(Obligatoire) Pour qu’Image Builder soit autorisé à lire/écrire des images, ainsi qu’à lire des scripts provenant du Stockage Azure, vous devez créer une identité affectée par l’utilisateur Azure disposant d’autorisations sur les différentes ressources. Pour plus d’informations sur le fonctionnement des autorisations Image Builder et les étapes pertinentes, consultez Créer une image et utiliser une identité managée affectée par l’utilisateur pour accéder aux fichiers dans un compte de stockage Azure.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<imgBuilderId>": {}
    }
}

Identité affectée par l’utilisateur du service Image Builder :

  • Prise en charge d’une seule identité.
  • Non-prise en charge des noms de domaine personnalisés.

Pour en savoir plus, consultez Que sont les identités managées pour les ressources Azure ?. Pour plus d’informations sur le déploiement de cette fonctionnalité, consultez Configurer des identités managées pour ressources Azure sur une machine virtuelle Azure en utilisant Azure CLI.

Identité affectée par l’utilisateur pour la machine virtuelle de build Image Builder

Cette propriété est uniquement disponible dans les versions 2021-10-01 et ultérieures de l’API.

Facultatif : la machine virtuelle de build Image Builder, créée par le service Image Builder dans votre abonnement est utilisée pour générer et personnaliser l’image. Pour que la machine virtuelle de build Image Builder dispose des autorisations nécessaires pour s’authentifier auprès d’autres services comme Azure Key Vault dans votre abonnement, vous devez créer une ou plusieurs identités assignées par l’utilisateur Azure qui disposent d’autorisations sur les ressources individuelles. Azure Image Builder peut ensuite associer ces identités affectées à l’utilisateur à la machine virtuelle de build. Les scripts de personnalisation qui s’exécutent à l’intérieur de la machine virtuelle de build peuvent ensuite extraire des jetons pour ces identités et interagir avec d’autres ressources Azure en fonction des besoins. Sachez que l’identité affectée par l’utilisateur pour Azure Image Builder doit avoir l’attribution de rôle « Opérateur d’identité managée » sur toutes les identités affectées par l’utilisateur pour qu’Azure Image Builder puisse les associer à la machine virtuelle de build.

Notes

N’oubliez pas que plusieurs identités peuvent être spécifiées pour la machine virtuelle de build Image Builder, notamment l’identité que vous avez créée pour la ressource de modèle d’image. Par défaut, l’identité que vous avez créée pour la ressource de modèle d’image n’est pas automatiquement ajoutée à la machine virtuelle de build.

"properties": {
  "vmProfile": {
    "userAssignedIdentities": [
      "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
    ]
  }
}

Identité affectée par l’utilisateur de la machine virtuelle de build Image Builder :

  • Prend en charge une liste d’une ou plusieurs identités managées affectées par l’utilisateur pour être configurées sur la machine virtuelle.
  • Prend en charge les scénarios d’abonnements multiples (identité créée dans un abonnement alors que le modèle d’image est créé dans un autre abonnement sous le même locataire).
  • Ne prend pas en charge les scénarios inter-locataires (identité créée dans un locataire alors que le modèle d’image est créé dans un autre locataire).

Pour plus d'informations, consultez les rubriques suivantes :

Propriétés : buildTimeoutInMinutes

Durée maximale d’attente lors de la création du modèle d’image (inclut l’ensemble des personnalisations, validations et distributions).

Si vous ne spécifiez pas la propriété ou définissez la valeur sur 0, la valeur par défaut est utilisée, soit 240 minutes ou quatre heures. La valeur minimale est de 6 minutes et la valeur maximale de 960 minutes ou 16 heures. Quand la valeur du délai d’expiration est atteinte (que la build de l’image soit terminée ou non), vous voyez une erreur similaire à ceci :

[ERROR] Failed while waiting for packerizer: Timeout waiting for microservice to
[ERROR] complete: 'context deadline exceeded'

Pour Windows, nous vous déconseillons de définir une valeur de buildTimeoutInMinutes inférieure à 60 minutes. Si vous constatez que vous avez atteint le délai d’expiration, consultez les journaux pour voir si l’étape de personnalisation attend par exemple une entrée de l’utilisateur. Si vous constatez que vous avez besoin de plus de temps pour que les personnalisations se terminent, augmentez la valeur de buildTimeoutInMinutes. Toutefois, ne définissez pas une valeur trop élevée, car vous devrez peut-être attendre qu’il expire avant d’afficher une erreur.

Propriétés : personnaliser

Image Builder prend en charge plusieurs « personnalisateurs » qui sont des fonctions utilisées pour personnaliser votre image, telles que l’exécution de scripts ou le redémarrage de serveurs.

Lorsque vous utilisez customize :

  • Vous pouvez utiliser plusieurs personnalisateurs.
  • Les personnalisateurs sont exécutés dans l’ordre spécifié dans le modèle.
  • En cas d’échec d’un personnalisateur, l’ensemble du composant de personnalisation échoue et renvoie une erreur.
  • Testez soigneusement les scripts avant de les utiliser dans un modèle. Le débogage des scripts par eux-mêmes est plus facile.
  • Ne placez pas de données sensibles dans les scripts. Les commandes inline peuvent être affichées dans la définition du modèle d’image. Les informations sensibles (notamment les mots de passe, le jeton SAS, les jetons d’authentification, etc.) doivent être déplacées dans des scripts dans le Stockage Azure, où l’accès exige une authentification.
  • Les emplacements de script doivent être accessibles publiquement, sauf si vous utilisez MSI.

La section customize est un tableau. Les types de personnalisateurs pris en charge sont les suivants : Fichier, PowerShell, Shell, WindowsRestart et WindowsUpdate.

"customize": [
  {
    "type": "File",
    "destination": "string",
    "sha256Checksum": "string",
    "sourceUri": "string"
  },
  {
    "type": "PowerShell",
    "inline": [ "string" ],
    "runAsSystem": "bool",
    "runElevated": "bool",
    "scriptUri": "string",
    "sha256Checksum": "string",
    "validExitCodes": [ "int" ]
  },
  {
    "type": "Shell",
    "inline": [ "string" ],
    "scriptUri": "string",
    "sha256Checksum": "string"
  },
  {
    "type": "WindowsRestart",
    "restartCheckCommand": "string",
    "restartCommand": "string",
    "restartTimeout": "string"
  },
  {
    "type": "WindowsUpdate",
    "filters": [ "string" ],
    "searchCriteria": "string",
    "updateLimit": "int"
  }
]

Personnalisateur de l’interpréteur de commandes

Le personnalisateur Shell prend en charge l’exécution de scripts d’interpréteur de commandes sur Linux. Les scripts d’interpréteur de commandes doivent être accessibles publiquement ou vous devez avoir configuré un MSI pour que le générateur d’images y accède.

"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<link to script>",
    "sha256Checksum": "<sha256 checksum>"
  }
],
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "inline": "<commands to run>"
  }
]

Propriétés de personnalisation :

  • type - Interpréteur de commandes.

  • name - Nom pour le suivi de la personnalisation.

  • scriptUri - URI de l’emplacement du fichier.

  • inline - Tableau de commandes d’interpréteur de commandes, séparées par des virgules.

  • sha256Checksum - Valeur de la somme de contrôle sha256 du fichier. Vous la générez localement, puis Image Builder vérifie la somme de contrôle et valide.

    Pour générer la somme de contrôle sha256, à l’aide d’un terminal sur Mac/Linux, exécutez la commande : sha256sum <fileName>

Notes

Les commandes inline sont stockées au sein de la définition du modèle d’image. Vous pouvez les voir quand vous videz la définition de l’image. Si vous avez des commandes et des valeurs sensibles (notamment des mots de passe, un jeton SAS, des jetons d’authentification, etc.), il est recommandé de les déplacer dans des scripts et d’utiliser une identité d’utilisateur pour l’authentification auprès du Stockage Azure.

Privilèges de super utilisateur

Préfixez les commandes avec sudo pour les exécuter avec des privilèges de super utilisateur. Vous pouvez ajouter les commandes dans des scripts ou les utiliser dans des commandes incluses, par exemple :

"type": "Shell",
"name": "setupBuildPath",
"inline": [
    "sudo mkdir /buildArtifacts",
    "sudo cp /tmp/index.html /buildArtifacts/index.html"
]

Exemple de script utilisant sudo que vous pouvez référencer à l’aide de scriptUri :

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

echo "Telemetry: running sudo 'as-is' in a script"
sudo touch /myfiles/somethingElevated.txt

Personnalisateur de redémarrage Windows

Le personnalisateur WindowsRestart vous permet de redémarrer une machine virtuelle Windows et d’attendre qu’elle revienne en ligne, vous permettant ainsi d’installer un logiciel qui nécessite un redémarrage.

"customize": [
  {
    "type": "WindowsRestart",
    "restartCommand": "shutdown /r /f /t 0",
    "restartCheckCommand": "echo Azure-Image-Builder-Restarted-the-VM  > c:\\buildArtifacts\\azureImageBuilderRestart.txt",
    "restartTimeout": "5m"
  }
]

Propriétés de personnalisation :

  • Type : WindowsRestart.
  • restartCommand - Commande pour exécuter le redémarrage (facultatif). Par défaut, il s’agit de 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand - Commande pour vérifier si le redémarrage a réussi (facultatif).
  • restartTimeout : délai d’expiration de redémarrage, spécifié sous forme de chaîne de grandeur et d’unité. Par exemple, 5m (5 minutes) ou 2h (2 heures). La valeur par défaut est 5m.

Notes

Il n’existe aucun personnalisateur de redémarrage Linux.

Personnalisateur PowerShell

Le personnalisateur PowerShell prend en charge l’exécution de scripts PowerShell et de commande en ligne sur Windows. Les scripts doivent être accessibles publiquement pour que le générateur d’images puisse y accéder.

"customize": [
  {
    "type": "PowerShell",
    "name":   "<name>",
    "scriptUri": "<path to script>",
    "runElevated": <true false>,
    "runAsSystem": <true false>,
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "PowerShell",
    "name": "<name>",
    "inline": "<PowerShell syntax to run>",
    "validExitCodes": [<exit code>],
    "runElevated": <true or false>,
    "runAsSystem": <true or false>
  }
]

Propriétés de personnalisation :

  • type - PowerShell.

  • scriptUri - URI vers l’emplacement du fichier de script PowerShell.

  • inline - Commandes en ligne à exécuter, séparées par des virgules.

  • validExitCodes – Codes valides facultatifs qui peuvent être retournés à partir de la commande de script/incluse. La propriété évite l’échec signalé de la commande de script/incluse.

  • runElevated - Facultatif, booléen avec prise en charge de l’exécution de commandes et de scripts avec des autorisations élevées.

  • runAsSystem : facultatif, booléen, détermine si le script PowerShell doit être exécuté en tant qu’utilisateur système.

  • sha256Checksum : générez la somme de contrôle SHA256 du fichier localement, mettez à jour la valeur de la somme de contrôle en l’indiquant en minuscules et Image Builder valide la somme de contrôle pendant le déploiement du modèle d’image.

    Pour générer la somme sha256Checksum, utilisez la cmdlet Get-FileHash dans PowerShell.

Personnalisateur de fichier

Le personnalisateur File permet à Image Builder de télécharger un fichier à partir d’un dépôt GitHub ou du Stockage Azure. Le personnalisateur prend en charge Linux et Windows. Si vous disposez d’un pipeline de build d’image qui s’appuie sur des artefacts, vous pouvez définir le personnalisateur de fichier à télécharger du partage de build et déplacer les artefacts dans l’image.

"customize": [
  {
    "type": "File",
    "name": "<name>",
    "sourceUri": "<source location>",
    "destination": "<destination>",
    "sha256Checksum": "<sha256 checksum>"
  }
]

Propriétés du personnalisateur de fichier :

  • sourceUri - Point de terminaison de stockage accessible, ce point de terminaison peut être GitHub ou Stockage Azure. Vous pouvez uniquement télécharger un fichier, pas un répertoire complet. Si vous devez télécharger un répertoire, utilisez un fichier compressé, puis décompressez-le à l’aide du personnalisateur de l’interpréteur de commandes ou PowerShell.

    Notes

    Si la valeur sourceUri est un compte de Stockage Azure, que l’objet blob est marqué, ou non, comme public, vous devez accorder les autorisations d’identité managée de l’utilisateur pour un accès en lecture sur l’objet blob. Pour définir les autorisations de stockage, consultez cet exemple.

  • destination - Nom de destination complet et nom du fichier. Le chemin d’accès et les sous-répertoires référencés devant exister, utilisez les personnalisateurs de l’interpréteur de commandes ou PowerShell pour les définir au préalable. Vous pouvez utiliser les personnalisateurs de script pour créer le chemin d’accès.

Ce personnalisateur est pris en charge par les répertoires Windows et les chemins d’accès Linux, mais à quelques différences près :

  • Linux - Le seul chemin d’accès sous lequel Image Builder peut écrire est /tmp.
  • Windows - Aucune restriction de chemin d’accès, mais le chemin d’accès doit exister.

Si une erreur se produit lors de la tentative de téléchargement du fichier ou de son placement dans un répertoire spécifié, l’étape de personnalisation échoue, et cette erreur sera consignée dans le fichier customization.log.

Notes

Le personnalisateur de fichiers est uniquement adapté au téléchargement de fichiers de petite taille (<20 Mo). Pour le téléchargement de fichiers plus volumineux, utilisez un script ou une commande incluse, le code d’utilisation pour télécharger des fichiers, tel que wget ou curl pour Linux et Invoke-WebRequest pour Windows. Pour les fichiers qui se trouvent dans le stockage Azure, assurez-vous d’attribuer une identité avec des autorisations pour afficher ce fichier sur la machine virtuelle de build en suivant la documentation Identité affectée par l’utilisateur pour la machine virtuelle de build Image Builder. Tout fichier qui n’est pas stocké dans Azure doit être accessible publiquement pour qu’Azure Image Builder puisse le télécharger.

  • sha256Checksum : générez la somme de contrôle SHA256 du fichier localement, mettez à jour la valeur de la somme de contrôle en l’indiquant en minuscules et Image Builder valide la somme de contrôle pendant le déploiement du modèle d’image.

    Pour générer la somme sha256Checksum, utilisez la cmdlet Get-FileHash dans PowerShell.

Personnalisateur de Windows Update

Le personnalisateur WindowsUpdate est basé sur l’approvisionneur Windows Update de la communauté pour Packer, un projet open source géré par la communauté Packer. Microsoft teste et valide le provisionneur à l’aide du service Image Builder et prend en charge l’examen des problèmes rencontrés, et travaille à la résolution des problèmes, mais le projet open source n’est pas officiellement pris en charge par Microsoft. Pour obtenir une documentation détaillée et une aide sur le provisionneur de Windows Update, consultez le référentiel du projet.

"customize": [
  {
    "type": "WindowsUpdate",
    "searchCriteria": "IsInstalled=0",
    "filters": [
      "exclude:$_.Title -like '*Preview*'",
      "include:$true"
    ],
    "updateLimit": 20
  }
]

Propriétés du personnalisateur :

  • type : WindowsUpdate.
  • searchCriteria : facultatif, définit les types de mises à jour installées (comme Recommandées ou Importantes), BrowseOnly = 0 et IsInstalled = 0 (recommandé) sont les valeurs par défaut.
  • filters : facultatif, vous permet de spécifier un filtre pour inclure ou exclure des mises à jour.
  • updateLimit : facultatif, définit le nombre de mises à jour pouvant être installées, par défaut 1 000.

Notes

Le personnalisateur de Windows Update peut échouer si des redémarrages de Windows sont en suspens ou si des installations d’applications sont en cours. En général, vous pouvez voir cette erreur dans le fichier customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. Nous vous recommandons vivement d’ajouter un redémarrage de Windows et/ou de laisser aux applications suffisamment de temps pour effectuer leurs installations à l’aide des commandes sleep ou wait dans les scripts ou commandes inline avant d’exécuter Windows Update.

Généraliser

Par défaut, Azure VM Image Builder exécute également du code de deprovision à la fin de chaque phase de personnalisation d’image pour généraliser l’image. La généralisation est un processus dans lequel l’image est configurée pour pouvoir être réutilisée afin de créer plusieurs machines virtuelles. Pour les machines virtuelles Windows, le générateur d’images Azure utilise Sysprep. Pour Linux, Azure Image Builder exécute waagent -deprovision.

Les commandes d’Image Builder utilisées pour généraliser peuvent ne pas convenir à chaque situation : Azure Image Builder vous permet donc de personnaliser cette commande si nécessaire.

Si vous migrez une personnalisation existante et que vous utilisez différentes commandes Sysprep/waagent, vous pouvez utiliser les commandes génériques du générateur d’images. De plus, si la création de la machine virtuelle échoue, utilisez vos propres commandes Sysprep ou waagent.

Si Azure Image Builder crée une image personnalisée Windows avec succès et que vous créez une machine virtuelle à partir de celle-ci, puis que vous constatez que la création de la machine virtuelle échoue ou ne se termine pas correctement, vous devez consulter la documentation de Windows Server Sysprep ou ouvrir une demande de support auprès de l’équipe du support technique du service client Windows Server Sysprep Services, qui peut résoudre les problèmes et vous conseiller sur l’utilisation correcte de Sysprep.

Commande Sysprep par défaut

Write-Output '>>> Waiting for GA Service (RdAgent) to start ...'
while ((Get-Service RdAgent).Status -ne 'Running') { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureTelemetryService) to start ...'
while ((Get-Service WindowsAzureTelemetryService) -and ((Get-Service WindowsAzureTelemetryService).Status -ne 'Running')) { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureGuestAgent) to start ...'
while ((Get-Service WindowsAzureGuestAgent).Status -ne 'Running') { Start-Sleep -s 5 }
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Write-Output '>>> Removing Sysprep\unattend.xml ...'
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
if (Test-Path $Env:SystemRoot\Panther\unattend.xml) {
  Write-Output '>>> Removing Panther\unattend.xml ...'
  Remove-Item $Env:SystemRoot\Panther\unattend.xml -Force
}
Write-Output '>>> Sysprepping VM ...'
& $Env:SystemRoot\System32\Sysprep\Sysprep.exe /oobe /generalize /quiet /quit
while($true) {
  $imageState = (Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\State).ImageState
  Write-Output $imageState
  if ($imageState -eq 'IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE') { break }
  Start-Sleep -s 5
}
Write-Output '>>> Sysprep complete ...'

Commande de déprovisionnement Linux par défaut

WAAGENT=/usr/sbin/waagent
waagent -version 1> /dev/null 2>&1
if [ $? -eq 0 ]; then
  WAAGENT=waagent
fi
$WAAGENT -force -deprovision+user && export HISTSIZE=0 && sync

Remplacement de commandes

Pour remplacer les commandes, utilisez les fournisseurs de script PowerShell ou de l’interpréteur de commandes pour créer les fichiers de commandes avec le nom de fichier exact, puis placez-les dans les répertoires appropriés :

  • Windows : c:\DeprovisioningScript.ps1
  • Linux : /tmp/DeprovisioningScript.sh

Image Builder lit ces commandes ; ces commandes sont écrites dans les journaux AIB, customization.log. Consultez la section de dépannage pour savoir comment collecter les journaux.

Propriétés : Gestion des erreurs (errorHandling)

La propriété errorHandling vous permet de configurer la façon dont les erreurs sont gérées lors de la création d’images.

{
  "errorHandling": {
    "onCustomizerError": "abort",
    "onValidationError": "cleanup"
  }
}

La propriété errorHandling vous permet de configurer la façon dont les erreurs sont gérées lors de la création d’images. Elle contient deux propriétés :

  • onCustomizerError : spécifie l’action à entreprendre lorsqu’une erreur se produit pendant la phase de personnalisation de la création d’images.
  • onValidationError : spécifie l’action à entreprendre lorsqu’une erreur se produit lors de la validation du modèle d’image.

La propriété errorHandling a également deux valeurs possibles pour gérer les erreurs lors de la création de l’image :

  • cleanup (nettoyage) - Garantit que les ressources temporaires créées par Packer sont nettoyées même si Packer ou l’une des personnalisations/validations rencontre une erreur. Cela maintient la rétrocompatibilité avec le comportement existant.
  • abort (abandonner) - Si Packer rencontre une erreur, le service Azure Image Builder (AIB) ignore le nettoyage des ressources temporaires. En tant que propriétaire du modèle AIB, vous êtes responsable du nettoyage de ces ressources à partir de votre abonnement. Ces ressources peuvent contenir des informations utiles telles que les journaux et les fichiers laissés derrière eux dans une machine virtuelle temporaire, ce qui peut vous aider à examiner l’erreur rencontrée par Packer.

Propriétés : distribuer

Le générateur d’images Azure prend en charge trois cibles de distribution :

  • managedImage - Image managée.
  • sharedImage - Azure Compute Gallery.
  • VHD - Disque dur virtuel dans un compte de stockage.

Vous pouvez distribuer une image sur les deux types de cibles dans la même configuration.

Notes

La commande sysprep AIB par défaut n’inclut pas « /mode:vm », mais cette propriété peut être nécessaire lors de la création d’images pour lesquelles le rôle HyperV est installé. Si vous devez ajouter cet argument de commande, vous devez écraser la commande sysprep.

Comme vous pouvez avoir plusieurs cibles sur lesquelles distribuer, le générateur d’images gère un état pour chaque cible de distribution accessible en interrogeant runOutputName. runOutputName est un objet que vous pouvez interroger après la distribution pour plus d’informations sur cette distribution. Par exemple, vous pouvez interroger l’emplacement du disque dur virtuel, ou des régions dans lesquelles la version de l’image a été répliquée ou la version de l’image SIG créée. Il s’agit d’une propriété de chaque cible de distribution. runOutputName doit être unique pour chaque cible de distribution. Voici un exemple qui interroge une distribution Azure Compute Gallery :

subscriptionID=<subcriptionID>
imageResourceGroup=<resourceGroup of image template>
runOutputName=<runOutputName>

az resource show \
  --ids "/subscriptions/$subscriptionID/resourcegroups/$imageResourceGroup/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/$runOutputName" \
--api-version=2023-07-01

Sortie :

{
  "id": "/subscriptions/xxxxxx/resourcegroups/rheltest/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/rhel77",
  "identity": null,
  "kind": null,
  "location": null,
  "managedBy": null,
  "name": "rhel77",
  "plan": null,
  "properties": {
    "artifactId": "/subscriptions/xxxxxx/resourceGroups/aibDevOpsImg/providers/Microsoft.Compute/galleries/devOpsSIG/images/rhel/versions/0.24105.52755",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "rheltest",
  "sku": null,
  "tags": null,
  "type": "Microsoft.VirtualMachineImages/imageTemplates/runOutputs"
}

Distribuer : managedImage

La sortie de l’image est une ressource d’image managée.

{
  "type":"ManagedImage",
  "imageId": "<resource ID>",
  "location": "<region>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Propriétés de distribution :

  • type – ManagedImage
  • imageId : ID de ressource de l’image de destination, format attendu : /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>.
  • location - Emplacement de l’image managée.
  • runOutputName - Nom unique d’identification de la distribution.
  • artifactTags - Facultatif, balises de paire de valeur de clé spécifiées par l’utilisateur.

Notes

Le groupe de ressources de destination doit exister. Si vous souhaitez distribuer l’image dans une autre région, le temps de déploiement est prolongé.

Distribuer : sharedImage

La galerie Azure Compute Gallery est un nouveau service de gestion des images qui permet de gérer la réplication de la région d’image, le contrôle de version et le partage d’images personnalisées. Le générateur d’images Azure prend en charge la distribution avec ce service, vous pouvez donc distribuer des images dans des régions prises en charge par les galeries Azure Compute Gallery.

une galerie Azure Compute Gallery est constituée des éléments suivants :

  • Galerie : Conteneur pour plusieurs images. Une galerie est déployée dans une région.
  • Définitions d’image : regroupement logique d’images.
  • Versions d’image : type d’image utilisé pour le déploiement d’une machine virtuelle ou d’un groupe identique. Des versions d’image peuvent être répliquées vers d’autres régions où des machines virtuelles doivent être déployées.

Avant de pouvoir distribuer dans la galerie, vous devez créer une galerie et une définition d’image, consultez Créer une galerie.

Notes

L’ID de version de l’image doit être distinct ou différent de toutes les versions d’image qui se trouvent dans l’Azure Compute Gallery existante.

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Le code JSON suivant est un exemple d’utilisation du champ replicationRegions pour distribuer à une galerie Azure Compute Gallery.

  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]

Notes

replicationRegions est déprécié pour les distributions à une galerie, comme targetRegions est une propriété mise à jour. Pour plus d’informations, consultez targetRegions.

Distribuer : targetRegions

Le code JSON suivant est un exemple d’utilisation du champ targetRegions pour distribuer à une galerie Azure Compute Gallery.

"distribute": [
      {
        "type": "SharedImage",
        "galleryImageId": "<resource ID>",
        "runOutputName": "<name>",
        "artifactTags": {
          "<name>": "<value>",
          "<name>": "<value>"
        },
        "targetRegions": [
             {
              "name": "eastus",
              "replicaCount": 2,
              "storageAccountType": "Standard_ZRS"
             },
             {
              "name": "eastus2",
              "replicaCount": 3,
              "storageAccountType": "Premium_LRS"
             }
          ]
       },
    ]

Distribuer des propriétés pour des galeries :

  • type - sharedImage

  • galleryImageId - ID de la galerie Azure Compute Gallery ; cette propriété peut être spécifiée dans deux formats :

    • Gestion de versions automatique : Image Builder génère automatiquement pour vous un numéro de version monotone. Cette propriété est utile pour continuer à reconstruire des images à partir du même modèle. Le format est : /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Contrôle de version explicite – Vous pouvez transmettre le numéro de version qu’Image Builder devra utiliser. Le format est /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>.

  • runOutputName - Nom unique d’identification de la distribution.

  • artifactTags - Facultatif, balises clé/valeur spécifiées par l’utilisateur.

  • replicationRegions - Tableau de régions pour la réplication. Une des régions doit être la région où la galerie est déployée. L’ajout de régions entraîne une augmentation du temps de build, car la build ne se termine pas tant que la réplication n’est pas achevée. Ce champ est déprécié à compter de la version d’API 2022-07-01. Utilisez targetRegions lors de la distribution d’un type « SharedImage ».

  • targetRegions : un tableau de régions pour la réplication. Il vient d’être introduit dans le cadre de l’API 2022-07-01 et s’applique seulement à la distribution de type SharedImage.

  • excludeFromLatest (facultatif) : permet d’indiquer que la version de l’image créée ne doit pas être utilisée comme dernière version dans la définition de la galerie. La valeur par défaut est « false ».

  • storageAccountType (facultatif) : AIB permet de spécifier les types de stockage suivants pour la version de l’image à créer :

    • « Standard_LRS »
    • "Standard_ZRS","

Notes

Si le modèle d’image et la référence image definition ne se trouvent pas au même emplacement, la création d’images prendra plus de temps. À l’heure actuelle, Image Builder ne comporte pas de paramètre location pour la ressource de version de l’image. Nous récupérons celui de la valeur image definition parente. Prenons par exemple une définition d’image se trouvant dans la région westus et supposons que vous souhaitiez répliquer la version de l’image dans la région eastus. Un blob est copié dans la région westus, une ressource de version de l’image est créée dans la région westus, puis répliquée dans la région eastus. Pour éviter le temps de réplication supplémentaire, veillez à ce que image definition et le modèle d’image se trouvent au même emplacement.

contrôle de version

La propriété versioning est destinée seulement au type de distribution sharedImage. C’est un type enum avec deux valeurs possibles :

  • latest : nouveau schéma strictement croissant par conception
  • source : schéma basé sur le numéro de version de l’image source.

Le schéma de numérotation par défaut des versions est latest. Le schéma le plus récent a une propriété supplémentaire, « major », qui spécifie la version majeure sous laquelle générer la dernière version.

Notes

La logique existante de génération des versions pour une distribution sharedImage est dépréciée. Deux nouvelles options sont fournies : les versions avec croissance monotone qui sont toujours la version la plus récente d’une galerie et les versions générées en fonction du numéro de version de l’image source. L’énumération spécifiant le schéma de génération de version permet une expansion future avec des schémas de génération de version supplémentaires.

    "distribute": [
        "versioning": {
            "scheme": "Latest",
            "major": 1
        }
    ]

propriétés de gestion de versions :

  • scheme : générer un nouveau numéro de version pour la distribution. Latest ou Source sont deux valeurs possibles.
  • major : spécifie la version majeure sous laquelle générer la version la plus récente. Applicable seulement quand scheme est défini sur Latest. Par exemple, dans une galerie avec les versions suivantes publiées : 0.1.1, 0.1.2, 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0, 2.0.0, 2.0.1, 2.1.0
    • Avec major non défini ou major défini sur 2, le schéma Latest génère une version 2.1.1
    • Avec major défini sur 1, le dernier schéma génère une version 1.2.1
    • Avec major défini sur 0, le schéma « latest » génère une version 0.1.3

Distribuer : Disque dur virtuel (VHD)

Vous pouvez générer sur un disque dur virtuel. Vous pouvez ensuite copier le disque dur virtuel et l’utiliser pour publier sur la Place de marché Azure ou l’utiliser avec Azure Stack.

{
  "type": "VHD",
  "runOutputName": "<VHD name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Système d’exploitation pris en charge : Windows et Linux

Distribuer des paramètres de disque dur virtuel :

  • type - Disque dur virtuel.
  • runOutputName - Nom unique d’identification de la distribution.
  • tags - Facultatif, balises de paire de valeur de clé spécifiées par l’utilisateur.

Le générateur d’images Azure ne permet pas à l’utilisateur de spécifier un emplacement de compte de stockage, mais vous pouvez interroger l’état de runOutputs pour obtenir l’emplacement.

az resource show \
  --ids "/subscriptions/$subscriptionId/resourcegroups/<imageResourceGroup>/providers/Microsoft.VirtualMachineImages/imageTemplates/<imageTemplateName>/runOutputs/<runOutputName>"  | grep artifactUri

Notes

Lorsque le disque dur virtuel est créé, copiez-le dès que possible dans un autre emplacement. Le disque dur virtuel est stocké dans un compte de stockage dans le groupe de ressources temporaire créé lors de l’envoi du modèle d’image au service de générateur d’images Azure. Si vous supprimez le modèle d’image, vous perdez le disque dur virtuel.

Le code JSON suivant distribue l’image en tant que disque dur virtuel à un compte de stockage personnalisé.

"distribute": [
  {
    "type": "VHD",
    "runOutputName": "<VHD name>",
    "artifactTags": {
        "<name>": "<value>",
        "<name>": "<value>"
    },
    "uri": "<replace with Azure storage URI>"
  }
]

Propriétés de distribution de disque dur virtuel (VHD) :

uri : URI de stockage Azure facultatif pour l’objet blob VHD distribué. À omettre pour utiliser la valeur par défaut (chaîne vide), auquel cas le VHD est publié sur le compte de stockage dans le groupe de ressources intermédiaires.

Propriétés : optimize

Vous pouvez activer la propriété optimize lors de la création d’une image de machine virtuelle et l’optimisation de la machine virtuelle pour améliorer le temps de création de l’image.

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot : configuration liée au processus de démarrage de la machine virtuelle utilisée pour contrôler les optimisations qui peuvent améliorer le temps de démarrage ou d’autres aspects des performances.
  • état : l'état de la fonctionnalité d'optimisation du démarrage dans vmBoot, la valeur Enabled indiquant que la fonctionnalité est activée pour améliorer le temps de création d'image.

Pour plus d’informations, consultez l’optimisation des machines virtuelles pour les images de galerie avec Le Générateur d’images de machine virtuelle Azure.

Propriétés : source

La section source fournit des informations sur l’image source qui sera utilisée par le générateur d’images. Azure Image Builder prend en charge seulement les images généralisées en tant qu’images sources. Pour l’instant, les images spécialisées ne sont pas prises en charge.

L’API nécessite un SourceType qui définit la source pour la génération d’image. Il en existe actuellement trois types :

  • PlatformImage : indique que l’image source est une image de la Place de marché.
  • ManagedImag : utilisé au démarrage à partir d’une image managée classique.
  • SharedImageVersion : utilisé lorsque vous utilisez une version d’image dans une galerie Azure Compute Gallery comme source.

Notes

Lorsque vous utilisez des images personnalisées Windows existantes, vous pouvez exécuter la commande sysprep jusqu’à trois fois sur une seule image Windows 7 ou Windows Server 2008 R2, ou 1001 fois sur une image Windows unique pour les versions ultérieures. Pour plus d’informations, consultez la documentation de sysprep.

Source PlatformImage

Azure Image Builder prend en charge les images Windows Server et client, ainsi que les images de Place de marché Azure pour Linux. Pour accéder à la liste complète, consultez En savoir plus sur Azure Image Builder.

"source": {
  "type": "PlatformImage",
  "publisher": "Canonical",
  "offer": "UbuntuServer",
  "sku": "18.04-LTS",
  "version": "latest"
}

Ces propriétés sont les mêmes que celles utilisées pour créer des machines virtuelles, à l’aide d’AZ CLI. Exécutez la commande ci-dessous pour obtenir les propriétés :

az vm image list -l westus -f UbuntuServer -p Canonical --output table --all

Vous pouvez utiliser latest dans la version ; la version est évaluée lors de la génération de l’image, et non lors de l’envoi du modèle. Si vous utilisez cette fonctionnalité avec la destination Azure Compute Gallery, vous pouvez éviter de soumettre à nouveau le modèle, puis réexécuter la génération de l’image par intervalles afin que vos images soient recréées à partir des images les plus récentes.

Prise en charge des informations sur les offres de la Place de marché

Vous pouvez également spécifier des informations de plan, par exemple :

"source": {
  "type": "PlatformImage",
  "publisher": "RedHat",
  "offer": "rhel-byos",
  "sku": "rhel-lvm75",
  "version": "latest",
  "planInfo": {
    "planName": "rhel-lvm75",
    "planProduct": "rhel-byos",
    "planPublisher": "redhat"
  }
}

Source ManagedImage

Définit l’image source comme une image managée existante d’un disque dur virtuel généralisé ou d’une machine virtuelle.

Notes

L’image managée source doit provenir d’un système d’exploitation pris en charge, et résider dans le même abonnement et la même région que votre modèle Azure Image Builder.

"source": {
  "type": "ManagedImage",
  "imageId": "/subscriptions/<subscriptionId>/resourceGroups/{destinationResourceGroupName}/providers/Microsoft.Compute/images/<imageName>"
}

imageId doit être l’ID de ressource de l’image managée. Utilisez az image list pour répertorier les images disponibles.

Source SharedImageVersion

Définit l’image source comme une version d’image existante dans une galerie Azure Compute Gallery.

Notes

La version de l’image partagée source doit provenir d’un système d’exploitation pris en charge, et doit résider dans la même région que votre modèle Azure Image Builder. Si ce n’est pas le cas, veuillez répliquer la version de l’image dans la région du modèle Image Builder.

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId : ID de ressource du modèle ARM de la version de l’image. Quand le nom de la version de l’image est « latest », la version est évaluée lors de la génération de l’image. Le imageVersionId doit être le ResourceId de la version de l’image. Utilisez az sig image-version list pour répertorier les versions d’image.

Le code JSON suivant définit l’image source en tant qu’image stockée dans une galerie partagée directe.

Notes

La galerie partagée directe est actuellement disponible en préversion.

    source: {
      "type": "SharedImageVersion",
      "imageVersionId": "<replace with resourceId of the image stored in the Direct Shared Gallery>"
    },

Le code JSON suivant définit l’image source comme la version d’image la plus récente pour une image stockée dans une galerie Azure Compute Gallery.

"properties": {
    "source": {
        "type": "SharedImageVersion",
        "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<azureComputeGalleryName>/images/<imageDefinitionName>/versions/latest"
    }
},

Propriétés de SharedImageVersion :

imageVersionId : ID de ressource du modèle ARM de la version de l’image. Quand le nom de la version de l’image est « latest », la version est évaluée lors de la génération de l’image.

Propriétés : stagingResourceGroup

La propriété stagingResourceGroup contient des informations sur le groupe de ressources intermédiaire que le service Image Builder crée en vue d’une utilisation pendant le processus de génération d’image. La propriété stagingResourceGroup est facultative pour toute personne qui souhaite plus de contrôle sur le groupe de ressources créé par Image Builder pendant le processus de génération d’image. Vous pouvez créer votre propre groupe de ressources et le spécifier dans la section stagingResourceGroup, ou en créer un en votre nom.

Important

Le groupe de ressources de préproduction spécifié ne peut pas être associé à un autre modèle d’image, doit être vide (ne contient aucune ressource), dans la même région que le modèle d’image, et avoir rôle RBAC (contrôle d’accès en fonction du rôle) de « Contributeur » ou « Propriétaire » appliqué à l’identité affectée à la ressource de modèle d’image Azure Image Builder.

"properties": {
  "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>"
}

Scénarios de création de modèle

  • La propriété stagingResourceGroup est laissée vide

    Si la propriété stagingResourceGroup n’est pas spécifiée ou si elle est spécifiée avec une chaîne vide, le service Image Builder crée un groupe de ressources intermédiaire avec la convention de nommage par défaut « IT_*** ». Par défaut, les étiquettes createdBy, imageTemplateName et imageTemplateResourceGroupName sont appliquées au groupe de ressources intermédiaire. En outre, le contrôle d’accès en fonction du rôle (RBAC) par défaut est appliqué à la ressource de modèle Azure Image Builder, qui est « Contributeur ».

  • La propriété stagingResourceGroup est spécifiée avec un groupe de ressources qui existe

    Si la propriété stagingResourceGroup est spécifiée avec un groupe de ressources qui existe, le service Image Builder vérifie que le groupe de ressources n’est pas associé à un autre modèle d’image, qu’il est vide (ne contient aucune ressource), est dans la même région que le modèle d’image, et que le contrôle d’accès en fonction du rôle (RBAC) de « Contributeur » ou « Propriétaire » est appliqué à l’identité affectée à la ressource de modèle d’image Azure Image Builder. Si une des exigences mentionnées ci-dessus n’est pas remplie, une erreur est générée. Les étiquettes usedBy, imageTemplateName et imageTemplateResourceGroupName sont ajoutées au groupe de ressources intermédiaire. Les balises préexistantes ne sont pas supprimées.

Important

Vous devez attribuer le rôle contributeur au groupe de ressources du principal de service correspondant à l’application tierce d’Azure Image Builder lors de la tentative de spécifier un groupe de ressources et un réseau virtuel pré-existant au service Azure Image Builder avec une image source Windows. Pour obtenir des instructions sur la commande CLI et le portail sur l’attribution du rôle contributeur au groupe de ressources, consultez la documentation suivante Résoudre les problèmes liés au Générateur d’images Azure de machine virtuelle : Erreur d’autorisation de création de disque

  • La propriété stagingResourceGroup est spécifiée avec un groupe de ressources qui n’existe pas

    Si la propriété stagingResourceGroup est spécifiée avec un groupe de ressources qui n’existe pas, le service Image Builder crée un groupe de ressources intermédiaire avec le nom fourni dans la propriété stagingResourceGroup. Une erreur s’affiche si le nom donné ne répond pas aux exigences de dénomination Azure pour les groupes de ressources. Par défaut, les étiquettes createdBy, imageTemplateName et imageTemplateResourceGroupName sont appliquées au groupe de ressources intermédiaire. Par défaut, le contrôle d’accès en fonction du rôle RBAC « Contributeur » est appliqué à l’identité affectée à la ressource de modèle d’image Azure Image Builder dans le groupe de ressources.

Suppression de modèle

Tout groupe de ressources de mise en lots créé par le service Image Builder est supprimé une fois le modèle d’image supprimé. La suppression inclut les groupes de ressources de mise en lots spécifiés dans la propriété stagingResourceGroup, mais qui n’existent pas avant la génération de l’image.

Si Image Builder n’a pas créé le groupe de ressources de mise en lots, mais a créé des ressources à l’intérieur de celui-ci, ces ressources seront supprimées une fois le modèle d’image supprimé étant donné que le service Image Builder dispose des autorisations ou du rôle appropriés nécessaires pour supprimer des ressources.

Propriétés : validate

Vous pouvez utiliser la propriété validate pour valider les images de la plateforme et toutes les images personnalisées que vous créez, que vous ayez utilisé ou non Azure Image Builder pour les créer.

Azure Image Builder prend en charge un mode ’Source-Validation-Only’ qui peut être défini à l’aide de la propriété sourceValidationOnly. Si la propriété sourceValidationOnly est défini sur true, l’image spécifiée dans la section source sera directement validée. Aucune build distincte n’est exécutée pour générer, puis valider une image personnalisée.

La propriété inVMValidations sélectionne la liste des validateurs qui seront exécutés sur l’image. Azure Image Builder prend en charge les validateurs File, PowerShell et Shell.

La propriété continueDistributeOnFailure gère la distribution des images de sortie si la validation échoue. Par défaut, si la validation échoue et que cette propriété a la valeur false, la ou les images de sortie ne sont pas distribuées. Si la validation échoue et que cette propriété est définie sur true, les images de sortie sont toujours distribuées. Utilisez cette option avec prudence car elle peut entraîner une distribution d’images ayant échoué. Dans les deux cas (true ou false), l’exécution de l’image de bout en bout est signalée comme ayant échoué en cas d’échec de validation. Cette propriété n’a aucun impact sur la réussite ou non de la validation.

Lorsque vous utilisez validate :

  • Vous pouvez utiliser plusieurs validateurs.
  • Les validateurs sont exécutés dans l’ordre spécifié dans le modèle.
  • En cas d’échec d’un validateur, l’ensemble du composant de validation échoue et renvoie une erreur.
  • Il est recommandé de tester rigoureusement le script avant de l’utiliser dans un modèle. Le débogage du script sur votre propre machine virtuelle en sera simplifié.
  • Ne placez pas de données sensibles dans les scripts.
  • Les emplacements de script doivent être accessibles publiquement, sauf si vous utilisez MSI.

Utilisation de la propriété validate pour valider des images Windows :

{
   "properties":{
      "validate":{
         "continueDistributeOnFailure":false,
         "sourceValidationOnly":false,
         "inVMValidations":[
            {
               "type":"File",
               "destination":"string",
               "sha256Checksum":"string",
               "sourceUri":"string"
            },
            {
               "type":"PowerShell",
               "name":"test PowerShell validator inline",
               "inline":[
                  "<command to run inline>"
               ],
               "validExitCodes":"<exit code>",
               "runElevated":"<true or false>",
               "runAsSystem":"<true or false>"
            },
            {
               "type":"PowerShell",
               "name":"<name>",
               "scriptUri":"<path to script>",
               "runElevated":"<true false>",
               "sha256Checksum":"<sha256 checksum>"
            }
         ]
      }
   }
}

Propriétés inVMValidations :

  • type - PowerShell.

  • name - nom du validateur

  • scriptUri - URI du fichier de script PowerShell.

  • inline - tableau de commandes à exécuter, séparées par des virgules.

  • validExitCodes : Facultatif. Des codes valides peuvent être retournés par le script/la commande en ligne, permettant ainsi d’éviter l’échec du script/de la commande en ligne.

  • runElevated - Facultatif, booléen avec prise en charge de l’exécution de commandes et de scripts avec des autorisations élevées.

  • sha256Checksum - Valeur de la somme de contrôle sha256 du fichier. Vous la générez localement, puis Image Builder vérifie la somme de contrôle et valide.

    Pour générer la somme de contrôle sha256, utiliser une commande PowerShell Get-Hash sur Windows

Utilisation de la propriété validate pour valider des images Linux :

{
  "properties": {
    "validate": {
      "continueDistributeOnFailure": false,
      "sourceValidationOnly": false,
      "inVMValidations": [
        {
          "type": "Shell",
          "name": "<name>",
          "inline": [
            "<command to run inline>"
          ]
        },
        {
          "type": "Shell",
          "name": "<name>",
          "scriptUri": "<path to script>",
          "sha256Checksum": "<sha256 checksum>"
        },
        {
          "type": "File",
          "destination": "string",
          "sha256Checksum": "string",
          "sourceUri": "string"
        }
      ]
    }
  }
}

Propriétés inVMValidations :

  • type : shell ou fichier spécifié comme type de validation à effectuer.

  • name - nom du validateur

  • scriptUri - URI du fichier de script

  • inline - tableau de commandes à exécuter, séparées par des virgules.

  • sha256Checksum - Valeur de la somme de contrôle sha256 du fichier. Vous la générez localement, puis Image Builder vérifie la somme de contrôle et valide.

    Pour générer la somme de contrôle sha256, à l’aide d’un terminal sur Mac/Linux, exécutez la commande : sha256sum <fileName>

  • destination : destination du fichier.

  • sha256Checksum : spécifie la somme de contrôle SHA256 du fichier.

  • sourceUri : URI source du fichier.

Propriétés : vmProfile

vmSize (facultatif)

Image Builder utilise une taille de référence SKU de Standard_D1_v2 pour les images Gen1, et de Standard_D2ds_v4 pour les images Gen2. La génération est définie par l’image que vous spécifiez dans le source. Vous pouvez modifier la valeur vmSize pour ces raisons :

  • Personnalisations nécessitant davantage de mémoire, une augmentation de la capacité du processeur et la gestion de fichiers volumineux (Go)
  • Exécution de builds Windows nécessitant l’utilisation de « Standard_D2_v2 » ou d’une taille de machine virtuelle équivalente.
  • Exigence d'isolement de la machine virtuelle
  • Personnalisation d’une image qui requiert du matériel spécifique. Par exemple, pour une machine virtuelle GPU, vous avez besoin d’une taille de machine virtuelle GPU.
  • Exiger le chiffrement de bout en bout au repos de la machine virtuelle de build ; vous devez spécifier la taille de la machine virtuelle de build de prise en charge qui n’utilise pas de disques temporaires locaux.

osDiskSizeGB

Par défaut, Image Builder ne modifie pas la taille de l’image et utilise la taille de l’image source. Le cas échéant, vous pouvez seulement augmenter la taille du disque du système d’exploitation (Windows et Linux). La valeur 0 indique de conserver la taille de l’image source. Vous ne pouvez pas choisir une taille de disque du système d’exploitation inférieure à celle de l’image source.

{
  "osDiskSizeGB": 100
}

vnetConfig (facultatif)

Si vous ne spécifiez pas de propriétés de réseau virtuel, Image Builder crée son propre réseau virtuel, sa propre adresse IP publique et son propre groupe de sécurité réseau. L’adresse IP publique est utilisée par le service pour communiquer avec la machine virtuelle de build. Si vous ne souhaitez pas une adresse IP publique, ou souhaitez qu’Image Builder ait accès à vos ressources de réseau virtuel existantes, comme les serveurs de configuration (DSC, Chef, Puppet, Ansible), les partages de fichiers, etc., vous pouvez spécifier un réseau virtuel. Pour plus d’informations, consultez la documentation relative à la mise en réseau.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
  "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
  "proxyVmSize": "<vmSize>"
}

subnetId

ID de ressource d’un sous-réseau préexistant sur lequel la machine virtuelle de build et la machine virtuelle de validation est déployée.

containerInstanceSubnetId (facultatif)

ID de ressource d’un sous-réseau préexistant sur lequel Azure Container Instance (ACI) est déployé pour les builds isolées. Si ce champ n’est pas spécifié, un Réseau virtuel temporaire, ainsi que des sous-réseaux et des groupes de sécurité réseau, est déployé dans le groupe de ressources intermédiaire en plus d’autres ressources réseau (point de terminaison privé, service Private Link, Azure Load Balancer et machine virtuelle proxy) pour permettre la communication entre l’instance ACI et la machine virtuelle de build.

[Cette propriété est disponible uniquement dans les versions 2024-02-01 d’API ou plus récentes, bien que les modèles existants créés à l’aide de versions d’API antérieures puissent être mis à jour pour spécifier cette propriété.]

Ce champ ne peut être spécifié que s’il subnetId est également spécifié et doit répondre aux exigences suivantes :

  • Ce sous-réseau doit se trouver sur la même Réseau virtuel que le sous-réseau spécifié dans subnetId.
  • Ce sous-réseau ne doit pas être le même sous-réseau que celui spécifié dans subnetId.
  • Ce sous-réseau doit être délégué au service ACI afin qu’il puisse être utilisé pour déployer des ressources ACI. Vous pouvez en savoir plus sur la délégation de sous-réseau pour les services Azure ici. Les informations de délégation de sous-réseau spécifiques à ACI sont disponibles ici.
  • Ce sous-réseau doit autoriser l’accès sortant à Internet et au sous-réseau spécifié dans subnetId. Ces accès sont requis afin que l’instance ACI puisse être approvisionnée et qu’elle puisse communiquer avec la machine virtuelle de build pour effectuer des personnalisations/validations. À l’autre extrémité, le sous-réseau spécifié doit subnetId autoriser l’accès entrant à partir de ce sous-réseau. En général, les règles de sécurité par défaut des groupes de sécurité réseau Azure autorisent ces accès. Toutefois, si vous ajoutez d’autres règles de sécurité à vos groupes de sécurité réseau, les accès suivants doivent toujours être autorisés :
    1. Accès sortant à partir du sous-réseau spécifié dans containerInstanceSubnetId :
      1. Vers Internet sur le port 443 (pour l’approvisionnement de l’image conteneur).
      2. Vers Internet sur le port 445 (pour le montage du partage de fichiers à partir de Stockage Azure).
      3. Vers le sous-réseau spécifié sur subnetId le port 22 (pour ssh/Linux) et le port 5986 (pour WinRM/Windows) (pour la connexion à la machine virtuelle de build).
    2. Accès entrant au sous-réseau spécifié dans subnetId:
      1. Vers le port 22 (pour ssh/Linux) et le port 5986 (pour WinRM/Windows) à partir du sous-réseau spécifié dans containerInstanceSubnetId (pour ACI pour se connecter à la machine virtuelle de build).
  • L’identité de modèle doit avoir l’autorisation d’effectuer l’action « Microsoft.Network/virtualNetworks/subnets/join/action » sur l’étendue de ce sous-réseau. Vous pouvez en savoir plus sur les autorisations Azure pour la mise en réseau ici.

proxyVmSize (facultatif)

Taille de la machine virtuelle proxy utilisée pour passer le trafic vers la machine virtuelle de build et la machine virtuelle de validation. Ce champ ne doit pas être spécifié s’il containerInstanceSubnetId est spécifié, car aucune machine virtuelle proxy n’est déployée dans ce cas. Omettez ou spécifiez une chaîne vide pour utiliser la valeur par défaut (Standard_A1_v2).

Propriétés : autoRun

Vous pouvez utiliser la autoRun propriété pour contrôler si le processus de génération du modèle d’image doit démarrer automatiquement lors de la création du modèle. C’est un type enum avec deux valeurs possibles :

  • Activé : l’exécution automatique est activée. Votre processus de génération de modèle d’image démarre automatiquement lors de la création du modèle.
  • Désactivé : l’exécution automatique est désactivée. Vous devrez donc démarrer manuellement le processus de génération d’image une fois le modèle créé.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Remarque

Lorsque vous définissez autoRun sur « Activé », le processus de génération d’image s’exécute une fois lors de la création du modèle. Elle garantit que la build d’image initiale se produit de manière transparente. Toutefois, elle ne fournit pas de builds d’images cohérentes et en cours. Pour obtenir des builds d’images cohérentes et en cours qui s’exécutent une fois qu’un modèle d’image est mis à jour, consultez Comment utiliser des déclencheurs Azure Image Builder pour configurer une build d’image automatique.

Contrairement autoRunà , la création automatique d’images via la ressource de déclencheur Azure Image Builder garantit que les builds d’images se produisent de manière cohérente. Chaque fois qu’il y a des modifications apportées au modèle, le service Azure Image Builder déclenche automatiquement le processus de génération d’image.

Choisissez autoRun l’image immédiatement générée lors de la création du modèle. Optez pour la création automatique d’images lorsque vous avez besoin d’une cohérence continue dans les builds d’images. Tenez compte de vos besoins spécifiques et utilisez l’option appropriée en fonction de votre flux de travail.

Propriétés : managedResourceTags

Vous pouvez utiliser la managedResourceTags propriété pour appliquer des balises aux ressources créées par le service Azure Image Builder dans le groupe de ressources intermédiaire pendant la génération d’image. Pour plus d’informations sur le groupe de ressources intermédiaire, consultez Vue d’ensemble d’Azure Image Builder

"properties": {
		"managedResourceTags": {
			"tag1": "value1",
      			"tag2": "value2"
              }
}

Opérations de modèle d’image

Lancement d’un build d’image

Pour lancer un build, vous devez appeler « Run » sur la ressource de modèle d’image. Voici des exemples de commandes run :

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Run -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

Annulation d’un build d’image

Si vous exécutez un build d’image qui vous semble incorrect, en attente d’une entrée d’utilisateur ou susceptible de ne jamais aboutir, vous pouvez l’annuler.

Le build peut être annulé à tout moment. Si la phase de distribution a commencé, vous pouvez néanmoins toujours l’annuler, mais vous devez effacer toutes les images non terminées. La commande Cancel n’attend pas la fin de l’annulation. Surveillez la progression de l’annulation dans lastrunstatus.runstate à l’aide de ces commandes d’état.

Exemples de commandes cancel :

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Cancel -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Cancel

Étapes suivantes

Il existe des exemples de fichiers .json pour différents scénarios dans le GitHub de générateur d’images Azure.