Crear una plantilla Bicep de Azure Image Builder o JSON de ARM

  • Artículo

Se aplica a: ✔️ Máquinas virtuales Linux ✔️ Máquinas virtuales Windows ✔️ Conjuntos de escalado flexibles

Azure Image Builder usa un archivo Bicep o un archivo de plantilla JSON de ARM para pasar información al servicio Image Builder. En este artículo analizaremos las secciones de los archivos, para que pueda compilar los suyos propios. En el caso de las versiones de API más recientes, consulta la referencia sobre plantillas. Para ver ejemplos de archivos .json completos, consulte el GitHub de Azure Image Builder.

El formato básico es el siguiente:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "apiVersion": "2022-02-14",
  "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/<subnetName>",
        "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>",
        ...
      ]
    }
  }
}

Tipo y versión de API

type es el tipo de recurso, que debe ser Microsoft.VirtualMachineImages/imageTemplates. apiVersion cambiará con el tiempo a medida que cambie la API. Consulte Novedades de Azure VM Image Builder para ver todos los principales cambios de API y actualizaciones de características para el servicio Azure VM Image Builder.

"type": "Microsoft.VirtualMachineImages/imageTemplates",
"apiVersion": "2022-02-14",

Location

La ubicación es la región donde se crea la imagen personalizada. Se admiten las regiones siguientes:

  • Este de EE. UU.
  • Este de EE. UU. 2
  • Centro-Oeste de EE. UU.
  • Oeste de EE. UU.
  • Oeste de EE. UU. 2
  • Oeste de EE. UU. 3
  • Centro-sur de EE. UU.
  • Norte de Europa
  • Oeste de Europa
  • Sudeste de Asia
  • Sudeste de Australia
  • Este de Australia
  • Sur de Reino Unido
  • Oeste de Reino Unido
  • Sur de Brasil
  • Centro de Canadá
  • Centro de la India
  • Centro de EE. UU.
  • Centro de Francia
  • Centro-oeste de Alemania
  • Japón Oriental
  • Centro-Norte de EE. UU
  • Este de Noruega
  • Norte de Suiza
  • JIO de India occidental
  • Norte de Emiratos Árabes Unidos
  • Este de Asia
  • Centro de Corea del Sur
  • Norte de Sudáfrica
  • Centro de Catar
  • Arizona USGov (versión preliminar pública)
  • Virginia USGov (versión preliminar pública)
  • Norte de China 3 (versión preliminar pública)
  • Centro de Suecia
  • Centro de Polonia

Importante

Registre la característica Microsoft.VirtualMachineImages/FairfaxPublicPreview para acceder a la versión preliminar pública de Azure Image Builder en regiones de Azure Government (Arizona USGov y Virginia USGov).

Importante

Registre la característica Microsoft.VirtualMachineImages/MooncakePublicPreview para acceder a la versión preliminar pública de Azure Image Builder en la región Norte de China 3.

Para acceder a la versión preliminar pública de Azure VM Image Builder en las regiones de Azure Government (Arizona USGov y Virginia USGov), debe registrar la característica Microsoft.VirtualMachineImages/FairfaxPublicPreview. Para ello, ejecute el siguiente comando en PowerShell o en la CLI de Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

Para acceder a la versión preliminar pública de Azure VM Image Builder en la región Norte de China 3, deberás registrar la característica Microsoft.VirtualMachineImages/MooncakePublicPreview. Para ello, ejecute el siguiente comando en PowerShell o en la CLI de Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Residencia de datos

El servicio Azure VM Image Builder no almacena ni procesa los datos de los clientes fuera de las regiones que tienen requisitos estrictos de residencia de datos de una sola región cuando un cliente solicita una compilación en esa región. En caso de una interrupción del servicio en las regiones que tienen requisitos de residencia de datos, deberá crear plantillas o archivos Bicep en una región y una ubicación geográfica diferentes.

Redundancia de zona

La distribución admite la redundancia de zona, los discos duros virtuales se distribuyen de manera predeterminada a una cuenta de almacenamiento con redundancia de zona (ZRS) y la versión de Azure Compute Gallery (anteriormente conocido como Shared Image Gallery) admitirá un tipo de almacenamiento ZRS si se especifica.

Etiquetas

Las etiquetas son los pares clave-valor que puede especificar para la imagen que se genera.

Identidad

Hay dos formas de agregar identidades asignadas por el usuario que se explican a continuación.

Identidad asignada por el usuario para un recurso de plantilla de imagen de Azure Image Builder

Obligatoria: para que Image Builder tenga permisos de lectura y escritura de imágenes, así como de lectura en los scripts de Azure Storage, debe crear una identidad asignada por el usuario de Azure que tenga permisos para los recursos individuales. Para más información sobre cómo funcionan los permisos de Image Builder y los pasos pertinentes, consulte Creación de una imagen y uso de una identidad administrada asignada por el usuario para acceder a los archivos de una cuenta de almacenamiento de Azure.

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

La identidad asignada por el usuario del servicio Image Builder:

  • Solo admite una única identidad
  • No admite los nombres de dominio personalizados.

Para obtener más información, consulte ¿Qué son las identidades administradas para los recursos de Azure? Para obtener más información sobre la implementación de esta característica, consulte Configurar identidades administradas para los recursos de Azure en una máquina virtual de Azure mediante la CLI de Azure.

Identidad asignada por el usuario para la máquina virtual de compilación de Image Builder

Este campo solo está disponible en las versiones de la API 2021-10-01 o posteriores.

Opcional: la máquina virtual de compilación de Image Builder, que crea el servicio Image Builder en la suscripción, se usa para compilar y personalizar la imagen. Para que la máquina virtual de compilación de Image Builder tenga permisos para autenticarse con otros servicios como Azure Key Vault en la suscripción, debe crear una o varias identidades asignadas por el usuario de Azure que tengan permisos para los recursos individuales. Azure Image Builder puede asociar estas identidades asignadas por el usuario a la máquina virtual de compilación. Los scripts de personalizador que se ejecutan en la máquina virtual de compilación pueden capturar tokens para estas identidades e interactuar con otros recursos de Azure según sea necesario. Tenga en cuenta que la identidad asignada por el usuario para Azure Image Builder debe tener la asignación de roles "Operador de identidades administradas" en todas las identidades asignadas por el usuario para Azure Image Builder a fin de poder asociarlas a la máquina virtual de compilación.

Nota:

Tenga en cuenta que se pueden especificar varias identidades para la máquina virtual de compilación de Image Builder, incluida la identidad creada para el recurso de plantilla de imagen. De manera predeterminada, la identidad creada para el recurso de plantilla de imagen no se agregará automáticamente a la máquina virtual de compilación.

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

La identidad asignada por el usuario de la máquina virtual de compilación de Image Builder:

  • Admite una lista de una o varias identidades administradas asignadas por el usuario que se podrán configurar en la máquina virtual.
  • Admite escenarios entre suscripciones (la identidad se crea en una suscripción mientras que la plantilla de imagen se crea en otra suscripción del mismo inquilino).
  • No admite escenarios entre inquilinos (la identidad se crea en un inquilino mientras que la plantilla de imagen se crea en otro inquilino).

Para obtener más información, consulte:

Propiedades: buildTimeoutInMinutes

Duración máxima de espera al compilar la plantilla de imagen (incluye todas las personalizaciones, validaciones y distribuciones).

Si no especifica la propiedad o establece el valor en 0, se usa el valor predeterminado, que es de 240 minutos, o cuatro horas. El valor mínimo es de 6 minutos y el máximo es de 960 minutos, o 16 horas. Cuando se alcance el valor de tiempo de espera (independientemente de si se ha completado la compilación de la imagen), verá un error similar al siguiente:

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

En Windows, no se recomienda establecer el valor buildTimeoutInMinutes por debajo de 60 minutos. Si alcanza el tiempo de espera, revise los registros para ver si el paso de personalización está esperando algo, como una entrada de usuario. Si encuentra que necesita más tiempo para que se completen las personalizaciones, aumente el valor buildTimeoutInMinutes. No obstante, no lo establezca demasiado alto, ya que es posible que tenga que esperar a que se agote el tiempo de espera antes de ver un error.

Propiedades: personalización

Image Builder admite varios "personalizadores", que son funciones que se usan para personalizar la imagen, como la ejecución de scripts o el reinicio de los servidores.

Al usar customize:

  • Puede usar varios personalizadores.
  • Los personalizadores se ejecutan en el orden especificado en la plantilla.
  • Si se produce un error en un personalizador, todo el componente de personalización producirá un error e informará de un error.
  • Pruebe los scripts exhaustivamente antes de usarlos en una plantilla. La depuración de los scripts por sí solos es más fácil.
  • No incluya información confidencial en los scripts. Los comandos en línea se pueden ver en la definición de la plantilla de imagen. Si tiene información confidencial (como contraseñas, token de SAS, tokens de autenticación, etc.), se debe pasar a scripts en Azure Storage, ya que el acceso requiere autenticación.
  • Las ubicaciones de los scripts deben ser accesibles públicamente, a menos que esté usando MSI.

La sección customize es una matriz. Los tipos de personalizador admitidos son: File, PowerShell, Shell, WindowsRestart y 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"
  }
]

Personalizador de shell

El personalizador Shell admite la ejecución de scripts de shell en Linux. Los scripts de shell deben ser accesibles públicamente o debe haber configurado una característica MSI para que Image Builder tenga acceso a estos.

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

Propiedades de personalización:

  • type: Shell.

  • name: nombre para realizar el seguimiento de la personalización.

  • scriptUri: URI a la ubicación del archivo.

  • inline: matriz de comandos de shell, separados por comas.

  • sha256Checksum: valor de la suma de comprobación sha256 del archivo; este valor se genera de forma local y, a continuación, Image Builder realizará la suma de comprobación y la validación.

    Para generar el valor de sha256Checksum, mediante un terminal en Mac o Linux ejecute sha256sum <fileName>

Nota:

Los comandos en línea se almacenan como parte de la definición de la plantilla de imagen; puede verlos al volcar la definición de la imagen. Si tiene comandos o valores confidenciales (como contraseñas, token de SAS, tokens de autenticación, etc.), se recomienda moverlos a scripts y utilizar una identidad de usuario para autenticarse en Azure Storage.

Privilegios de superusuario

Prefijo de los comandos con sudo para ejecutarlos con privilegios de superusuario. Puede agregar los comandos a scripts o usar sus comandos alineados, por ejemplo:

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

Ejemplo de un script mediante sudo al que puede hacer referencia mediante scriptUri:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

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

Personalizador de reinicio de Windows

El personalizador WindowsRestart le permite reiniciar una máquina virtual de Windows y esperar a que la máquina virtual vuelva a conectarse; este personalizador le permite instalar software que requiere un reinicio.

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

Propiedades de personalización:

  • Type: WindowsRestart.
  • restartCommand: comando para ejecutar el reinicio (opcional). El valor predeterminado es 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand: comando para comprobar si el reinicio se realizó correctamente (opcional).
  • restartTimeout: se ha agotado el tiempo de espera del reinicio especificado como una cadena de magnitud y unidad. Por ejemplo, 5m (5 minutos) o 2h (2 horas). El valor predeterminado es: 5m.

Nota:

No hay ningún personalizador de reinicio de Linux.

Personalizador de PowerShell

El personalizador PowerShell admite la ejecución de scripts de PowerShell y comandos alineados en Windows; los scripts deben estar accesibles públicamente para que IB pueda acceder a ellos.

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

Propiedades de personalización:

  • type: PowerShell.

  • scriptUri: URI a la ubicación del archivo de script de PowerShell.

  • inline: comandos alineados que se ejecutarán, separados por comas.

  • validExitCodes: códigos válidos opcionales que se pueden devolver desde el script o el comando alineado. La propiedad evita los errores notificados del script o el comando alineado.

  • runElevated: opcional, booleano, admite la ejecución de comandos y scripts con permisos elevados.

  • runAsSystem: opcional, booleano, determina si el script de PowerShell debe ejecutarse como usuario del sistema.

  • sha256Checksum : genere la suma de comprobación SHA256 del archivo localmente, actualice el valor de suma de comprobación a minúsculas e Image Builder validará la suma de comprobación durante la implementación de la plantilla de imagen.

    Para generar el sha256Checksum, use el cmdlet Get-FileHash en PowerShell.

Personalizador de archivos

El personalizador File permite a Image Builder descargar un archivo desde un repositorio de GitHub o Azure Storage. El personalizador admite Linux y Windows. Si tiene una canalización de compilación de imagen basada en artefactos de compilación, puede configurar el personalizador de archivos para que se descargue desde el recurso compartido de la compilación y mover los artefactos a la imagen.

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

Propiedades del personalizador de archivos:

  • sourceUri: un punto de conexión de almacenamiento accesible, que puede tratarse de GitHub o Azure Storage. Solo puede descargar un archivo, no un directorio completo. Si necesita descargar un directorio, utilice un archivo comprimido y, a continuación, descomprímalo mediante los personalizadores de Shell o PowerShell.

    Nota

    Si sourceUri es una cuenta de Azure Storage, independientemente de si el blob está marcado como público, deberá conceder los permisos de identidad de usuario administrado para el acceso de lectura en el blob. Consulte este ejemplo para establecer los permisos de almacenamiento.

  • destination: la ruta de acceso completa y el nombre de archivo de destino. Todas las rutas de acceso y los subdirectorios a los que se hace referencia deben existir; use los personalizadores de Shell o PowerShell para configurarlos con antelación. Puede usar los personalizadores de script para crear la ruta de acceso.

Los directorios de Windows y las rutas de acceso de Linux admiten este personalizador, aunque hay algunas diferencias:

  • Linux: la única ruta de acceso en la que el generador de imágenes puede escribir es /tmp.
  • Windows: no hay ninguna restricción en la ruta de acceso, pero esta debe existir.

Si se produce un error al intentar descargar el archivo o al colocarlo en un directorio concreto, ocurre un error en el paso de personalización que se registrará en customization.log.

Nota:

El personalizador de archivos solo es adecuado para descargas de archivos pequeños, < 20 MB. Para descargas de archivos más grandes, use un script o un comando insertado y, a continuación, use código para descargar archivos, como, por ejemplo, wget o curl de Linux, Windows o Invoke-WebRequest. Para los archivos que están en Azure Storage, asegúrese de asignar una identidad con permisos para ver ese archivo en la máquina virtual de compilación siguiendo la documentación siguiente: Identidad asignada por el usuario para la máquina virtual de compilación de Image Builder. Cualquier archivo que no esté almacenado en Azure debe ser accesible públicamente para que Azure Image Builder pueda descargarlo.

  • sha256Checksum : genere la suma de comprobación SHA256 del archivo localmente, actualice el valor de suma de comprobación a minúsculas e Image Builder validará la suma de comprobación durante la implementación de la plantilla de imagen.

    Para generar el sha256Checksum, use el cmdlet Get-FileHash en PowerShell.

Personalizador de Windows Update

El personalizador WindowsUpdate se basa en el aprovisionador de Windows Update de la comunidad para Packer, que es un proyecto de código abierto que mantiene la comunidad de Packer. Microsoft comprueba y valida el aprovisionamiento con el servicio Image Builder, y permite investigar problemas con él, así como trabajar para resolver problemas, pero Microsoft no admite oficialmente el proyecto de código abierto. Para obtener documentación detallada y ayuda con el aprovisionamiento de Windows Update, vea el repositorio del proyecto.

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

Propiedades del personalizador:

  • type: WindowsUpdate.
  • searchCriteria: (opcional) define qué tipo de actualizaciones se instalan (como las recomendadas o las importantes); BrowseOnly=0 e IsInstalled=0 (recomendado) son los valores predeterminados.
  • filters: (opcional) permite especificar un filtro para incluir o excluir actualizaciones.
  • updateLimit: (opcional) define el número de actualizaciones que se pueden instalar, el valor predeterminado es 1000.

Nota

Se puede producir un error en el personalizador de Windows Update si hay algún reinicio de Windows pendiente, o bien si hay instalaciones de aplicaciones que todavía se están ejecutando. Normalmente, verá este error en el archivo customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. Le recomendamos encarecidamente que considere la posibilidad de agregar un reinicio de Windows o permitir a las aplicaciones el tiempo suficiente para completar sus instalaciones mediante los comandos sleep o wait en los comandos o scripts insertados antes de ejecutar Windows Update.

Generalize

De manera predeterminada, Azure Image Builder también ejecutará código de deprovision al final de cada fase de personalización de la imagen con el fin de generalizarla. La generalización es un proceso en el que la imagen se configura para que pueda volver a usarse para crear varias máquinas virtuales. Para las máquinas virtuales de Windows, Azure Image Builder utiliza Sysprep. En el caso de Linux, Azure Image Builder ejecuta waagent -deprovision.

Es posible que los comandos que utiliza Image Builder para la generalización no sean adecuados para todas las situaciones, por lo que Azure Image Builder permite personalizar este comando si es necesario.

Si está migrando una personalización existente y usa comandos de Sysprep o waagent diferentes, puede usar los comandos genéricos de Image Builder y, si la creación de la máquina virtual produce un error, puede usar sus propios comandos de Sysprep o waagent.

Si Azure Image Builder crea una imagen personalizada de Windows correctamente y usted crea una máquina virtual a partir de ella, pero la creación produce un error o no se realiza correctamente, debe revisar la documentación de Sysprep de Windows Server o presentar una solicitud de soporte técnico al equipo de soporte técnico de los servicios de atención al cliente de Sysprep de Windows Server, que podrá solucionar los problemas y orientarlo en la utilización correcta de Sysprep.

Comando de Sysprep predeterminado

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 ...'

Comando de desaprovisionamiento de Linux predeterminado

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

Reemplazo de los comandos

Para reemplazar los comandos, use los aprovisionadores de scripts de PowerShell o Shell para crear los archivos de comandos con el nombre de archivo exacto y colóquelos en los directorios correctos:

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

Image Builder lee estos comandos, que se escriben en los registros de AIB, customization.log. Consulte la solución de problemas sobre cómo recopilar registros.

Propiedades: errorHandling

La propiedad errorHandling permite configurar cómo se controlan los errores durante la creación de imágenes.

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

La propiedad errorHandling permite configurar cómo se controlan los errores durante la creación de imágenes. Tiene dos propiedades:

  • onCustomizerError: especifica la acción que se debe realizar cuando se produce un error durante la fase del personalizador de la creación de imágenes.
  • onValidationError: especifica la acción que se debe realizar cuando se produce un error durante la validación de la plantilla de imagen.

La propiedad errorHandling también tiene dos valores posibles para controlar errores durante la creación de imágenes:

  • cleanup: garantiza que los recursos temporales creados por Packer se limpien incluso si Packer o una de las personalizaciones o validaciones detectan un error. Esto mantiene la compatibilidad con versiones anteriores con el comportamiento existente.
  • abort: en caso de que Packer encuentre un error, el servicio Azure Image Builder (AIB) omite la limpieza de recursos temporales. Como propietario de la plantilla de AIB, es responsable de limpiar estos recursos de su suscripción. Estos recursos pueden contener información útil, como registros y archivos que se han quedado en una máquina virtual temporal, lo que puede ayudar a investigar el error detectado por Packer.

Propiedades: distribución

Azure Image Builder admite tres destinos de distribución:

  • ManagedImage: imagen administrada
  • sharedImage: Azure Compute Gallery.
  • VHD: disco duro virtual en una cuenta de almacenamiento.

Puede distribuir una imagen a ambos tipos de destino en la misma configuración.

Nota:

El comando sysprep predeterminado de AIB no incluye "/mode:vm"; sin embargo, puede que esta propiedad sea necesaria al crear imágenes que vayan a tener instalado el rol de HyperV. Si necesita agregar este argumento de comando, debe invalidar el comando sysprep.

Dado que puede tener más de un destino al que distribuir, Image Builder mantiene un estado para cada destino de distribución al que puede accederse consultando el runOutputName. El runOutputName es un objeto que puede consultar después de la distribución para obtener información acerca de esa distribución. Por ejemplo, puede consultar la ubicación del disco duro virtual o las regiones a las que se ha replicado la versión de la imagen o donde se ha creado la versión de la imagen de SIG. Se trata de una propiedad de cada destino de distribución. El runOutputName debe ser único para cada destino de distribución. Este es un ejemplo para consultar una distribución de 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=2021-10-01

Salida:

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

Distribución: managedImage

La imagen de salida es un recurso de imagen administrada.

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

Propiedades de la distribución:

  • type: ManagedImage
  • imageId: id. de recurso de la imagen de destino, formato esperado: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location: ubicación de la imagen administrada.
  • runOutputName: nombre único para identificar la distribución.
  • artifactTags: etiquetas de clave-valor opcionales especificadas por el usuario.

Nota

El grupo de recursos de destino debe existir. Si quiere que la imagen se distribuya a otra región, aumentará el tiempo de implementación.

Distribución: sharedImage

Azure Compute Gallery es un nuevo servicio de administración de imágenes que permite administrar la replicación de las regiones de la imagen, el control de versiones y el uso compartido de imágenes personalizadas. Azure Image Builder admite la distribución con este servicio, por lo que puede distribuir imágenes a regiones admitidas por las instancias de Azure Compute Gallery.

Una instancia de Azure Compute Gallery consta de:

  • Galería: contenedor de varias imágenes. Una galería se implementa en una región.
  • Definiciones de imagen: una agrupación conceptual de las imágenes.
  • Versiones de las imágenes: un tipo de imagen usado para implementar una máquina virtual o un conjunto de escalado. Las versiones de las imágenes se pueden replicar a otras regiones en las que deban implementarse máquinas virtuales.

Antes de poder realizar la distribución a la galería, debe crear una galería y una definición de imagen; para ello, consulte Creación de una galería.

Nota:

El id. de la versión de la imagen debe ser distinto o diferente de cualquier versión de imagen que se encuentra en la instancia existente de Azure Compute Gallery.

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

El siguiente JSON es un ejemplo de cómo usar el campo replicationRegions para distribuirlo a Azure Compute Gallery.

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

Nota:

replicationRegions está en desuso para las distribuciones de la galería tal como se actualiza la propiedad targetRegions. Para obtener más información, consulte targetRegions.

Distribuir: targetRegions

El siguiente JSON es un ejemplo de cómo usar el campo targetRegions para distribuirlo a 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"
             }
          ]
       },
    ]

Propiedades de distribución de las galerías:

  • tipo: sharedImage

  • galleryImageId: identificador de la instancia de Azure Compute Gallery, que puede especificarse en dos formatos:

    • Control de versiones automático: Image Builder genera un número de versión monotónico, que resulta útil cuando quiere seguir compilando imágenes a partir de la misma plantilla. El formato es: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Control de versiones explícito: puede pasar el número de versión que quiera que Image Builder use. El formato es: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>.

  • runOutputName: nombre único para identificar la distribución.

  • artifactTags: etiquetas de clave-valor opcionales especificadas por el usuario.

  • replicationRegions: matriz de regiones para la replicación. Una de las regiones debe ser la región en la que está implementada la galería. Añadir regiones implica un aumento del tiempo de compilación, ya que esta no se completa hasta que la replicación se haya completado. Este campo está en desuso a partir de la versión de API 2022-07-01, use targetRegions al distribuir un tipo "SharedImage".

  • targetRegions: matriz de regiones para replicar. Se acaba de introducir como parte de la API 2022-07-01 y solo se aplica al tipo de distribución SharedImage.

  • excludeFromLatest (opcional): le permite marcar la versión de la imagen que haya creado para que no se use como última versión en la definición de la galería; el valor predeterminado es "false".

  • storageAccountType (opcional): AIB admite la especificación de estos tipos de almacenamiento para la versión de la imagen que se va a crear:

    • "Standard_LRS"
    • "Standard_ZRS","

Nota:

Si la plantilla de imagen y la definición image definition a la que se hace referencia no están en la misma ubicación, se necesitará tiempo adicional para crear las imágenes. En la actualidad, Image Builder no tiene un parámetro location para el recurso de versión de la imagen, este se toma de su propiedad image definition primaria. Por ejemplo, si una definición de imagen está en la región westus y quiere que la versión de la imagen se replique en eastus, se copia un blob en westus, se crea un recurso de versión de imagen a partir de él en westus y, después, se replica en eastus. Para evitar el tiempo de replicación adicional, asegúrese de que la definición image definition y la plantilla de imagen se encuentren en la misma ubicación.

control de versiones

La propiedad de control de versiones es solo para el tipo de distribución sharedImage. Es una enumeración con dos valores posibles:

  • latest: nuevo esquema que aumenta estrictamente por diseño
  • source: esquema basado en el número de versión de la imagen de origen.

El esquema de numeración de versiones predeterminado es latest. El esquema más reciente tiene una propiedad adicional, "principal", que especifica la versión principal con la que se va a generar la versión más reciente.

Nota:

La lógica de generación de versiones existente para la distribución sharedImage está en desuso. Se proporcionan dos nuevas opciones: el aumento monotónico de las versiones que siempre son la versión más reciente de una galería y las versiones generadas en función del número de versión de la imagen de origen. La enumeración que especifica el esquema de generación de versiones permite una expansión en el futuro con esquemas de generación de versiones adicionales.

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

Propiedades de control de versiones:

  • scheme: genera un nuevo número de versión para la distribución. Hay dos posibles valores: Latest y Source.
  • principal: especifica la versión principal con la que se va a generar la versión más reciente. Solo es aplicable cuando scheme tiene el valor Latest. Por ejemplo, en una galería con las versiones siguientes publicadas: 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
    • Con el valor principal no establecido o establecido en 2, el esquema Latest genera la versión 2.1.1
    • Con el valor principal establecido en 1, el esquema más reciente genera la versión 1.2.1
    • Con el valor principal establecido en 0, el esquema más reciente genera la versión 0.1.3

Distribución: VHD

Puede generar un disco duro virtual. A continuación, puede copiar el disco duro virtual y usarlo para publicar en Azure MarketPlace o usarlo con Azure Stack.

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

SO compatible: Windows y Linux

Parámetros de distribución de VHD:

  • tipo: VHD.
  • runOutputName: nombre único para identificar la distribución.
  • etiquetas: etiquetas de par clave-valor opcionales especificadas por el usuario.

Azure Image Builder no permite al usuario especificar una ubicación de la cuenta de almacenamiento, pero puede consultar el estado de runOutputs para obtener la ubicación.

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

Nota:

Una vez creado el disco duro virtual, cópielo en una ubicación distinta tan pronto como sea posible. El disco duro virtual se almacena en una cuenta de almacenamiento del grupo de recursos temporal creado al enviar la plantilla de imagen al servicio Azure Image Builder. Si elimina la plantilla de imagen, perderá el disco duro virtual.

El siguiente JSON distribuye la imagen como un disco duro virtual a una cuenta de almacenamiento personalizada.

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

Propiedades de la distribución de VHD:

uri: URI opcional de Azure Storage para el blob de VHD distribuido. Omita usar el valor predeterminado (cadena vacía), porque en ese caso el disco duro virtual se publicaría en la cuenta de almacenamiento del grupo de recursos de almacenamiento provisional.

Propiedades: optimizar

La propiedad optimize se puede habilitar al crear una imagen de máquina virtual y permite que la optimización de la máquina virtual mejore el tiempo de creación de la imagen.

"optimize": {
      "vmboot": {
        "state": "Enabled"
      }
    }
  • vmboot: una configuración relacionada con el proceso de arranque de la máquina virtual (VM), que se usa para controlar las optimizaciones que pueden mejorar el tiempo de arranque u otros aspectos de rendimiento.
  • state: el estado de la característica de optimización de arranque dentro de vmboot, con el valor Enabled que indica que la característica está activada para mejorar el tiempo de creación de la imagen.

Para más información, consulte Optimización de máquinas virtuales para imágenes de galería con Azure VM Image Builder.

Propiedades: origen

La sección source contiene información acerca de la imagen de origen que usará Image Builder. Azure Image Builder solo admite imágenes generalizadas como imágenes de origen, pero no se admiten imágenes especializadas.

La API requiere una propiedad SourceType que define el origen de la compilación de imagen. Actualmente hay tres tipos:

  • PlatformImage: indicado para los casos en que la imagen de origen es una imagen de Marketplace.
  • ManagedImage: úsela cuando empiece desde una imagen administrada normal.
  • SharedImageVersion: empléela cuando se usa como origen una versión de la imagen en una instancia de Azure Compute Gallery.

Nota:

Al usar imágenes personalizadas de Windows existentes, puede ejecutar el comando Sysprep hasta tres veces en una sola imagen de Windows 7 o Windows Server 2008 R2, o 1001 veces en una sola imagen de Windows para versiones posteriores. Para obtener más información, consulte la documentación de sysprep.

Origen de PlatformImage

El generador de imágenes de Azure admite Windows Server y el cliente, así como las imágenes de Azure Marketplace de Linux. Consulte Información sobre Azure Image Builder para ver la lista completa.

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

Aquí, las propiedades son las mismas que se utilizan para crear máquinas virtuales. Mediante la CLI de Azure, ejecute lo siguiente para obtener las propiedades:

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

Puede usar el valor latest en la versión; la versión se evalúa cuando se produce la compilación de la imagen, no cuando se envía la plantilla. Si usa esta funcionalidad con el destino de Azure Compute Gallery, puede evitar volver a enviar la plantilla y ejecutar de nuevo la compilación de la imagen a intervalos, por lo que las imágenes se vuelven a crear a partir de las imágenes más recientes.

Compatibilidad con la información de un plan de Marketplace

También puede especificar la información del plan, por ejemplo:

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

Origen de ManagedImage

Establece la imagen de origen como una imagen administrada existente de una máquina virtual o un disco duro virtual generalizados.

Nota

La imagen administrada de origen debe ser de un sistema operativo compatible y debe residir en las mismas suscripción y región que la plantilla de Azure Image Builder.

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

imageId debe ser el valor de ResourceId de la imagen administrada. Use az image list para enumerar las imágenes disponibles.

Origen de SharedImageVersion

Establece la imagen de origen como una versión de la imagen existente de una instancia de Azure Compute Gallery.

Nota

La versión de la imagen compartida de origen debe ser de un sistema operativo compatible y debe residir en la misma región que la plantilla de Azure Image Builder. Si no es así, replique la versión de la imagen en la región de la plantilla de Image Builder.

"source": {
  "type": "SharedImageVersion",
  "imageVersionID": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId: id. de recurso de plantilla de ARM de la versión de la imagen. Cuando el nombre de la versión de la imagen es "latest", la versión se evalúa cuando tiene lugar la compilación de la imagen. El imageVersionId debe ser el ResourceId de la versión de la imagen. Use lista de versiones de imagen con firma de Azure para obtener una lista de las versiones de imagen.

El siguiente JSON establece la imagen de origen como una imagen almacenada en una galería compartida directa.

Nota:

La galería compartida directa se encuentra actualmente en versión preliminar.

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

El siguiente JSON establece la imagen de origen como la versión más reciente de una imagen almacenada en Azure Compute Gallery.

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

Propiedades de SharedImageVersion:

imageVersionId: id. de recurso de plantilla de ARM de la versión de la imagen. Cuando el nombre de la versión de la imagen sea "latest", la versión se evalúa en el momento en el que tenga lugar la compilación de la imagen.

Propiedades: stagingResourceGroup

La propiedad stagingResourceGroup contiene información sobre el grupo de recursos de almacenamiento provisional que el servicio Image Builder crea para su uso durante el proceso de compilación de imágenes. stagingResourceGroup es una propiedad opcional para cualquier persona que quiera tener más control sobre el grupo de recursos creado por Image Builder durante el proceso de compilación de imágenes. Puede crear su propio grupo de recursos y especificarlo en la stagingResourceGroup sección o hacer que Image Builder cree uno en su nombre.

Importante

El grupo de recursos de preparación especificado no puede estar asociado a otra plantilla de imágenes, debe estar vacío (sin recursos en su interior), en la misma región que la plantilla de imágenes y tener RBAC de "Colaborador" o "Propietario" aplicado a la identidad asignada al recurso de plantilla de imágenes de Azure Image Builder.

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

Escenarios de creación de plantillas

  • La propiedad stagingResourceGroup se deja vacío

    Si la propiedad stagingResourceGroup no se especifica o se especifica con una cadena vacía, el servicio Image Builder creará un grupo de recursos de almacenamiento provisional con la convención de nombre predeterminada "IT_***". El grupo de recursos de almacenamiento provisional tiene aplicadas las etiquetas predeterminadas: createdBy, imageTemplateName, imageTemplateResourceGroupName. Además, el RBAC predeterminado se aplica a la identidad asignada al recurso de plantilla de Azure Image Builder, "Colaborador".

  • La propiedad stagingResourceGroup se especifica con un grupo de recursos que existe

    Si la propiedad stagingResourceGroup se especifica con un grupo de recursos que existe, el servicio Image Builder lo comprueba para asegurarse de que el grupo de recursos no está asociado con otra plantilla de imagen, está vacío (sin recursos dentro), se encuentra en la misma región que la plantilla de imagen y tiene el RBAC "Colaborador" o "Propietario" aplicado a la identidad asignada al recurso de plantilla de imagen de Azure Image Builder. Si no se cumple alguno de los requisitos mencionados anteriormente, se produce un error. El grupo de recursos de almacenamiento provisional tiene agregadas las siguientes etiquetas: usedBy, imageTemplateName, imageTemplateResourceGroupName. No se eliminan las etiquetas preexistentes.

Importante

Tendrá que asignar el rol de colaborador al grupo de recursos para la entidad de servicio correspondiente a la aplicación de primera entidad de Azure Image Builder al intentar especificar un grupo de recursos y una red virtual preexistentes al servicio Azure Image Builder con una imagen de origen de Windows. Para obtener instrucciones del portal y el comando de la CLI sobre cómo asignar el rol de colaborador al grupo de recursos, consulte la siguiente documentación Solución de problemas de Azure VM Image Builder: error de autorización al crear disco

  • La propiedad stagingResourceGroup se especifica con un grupo de recursos que no existe

    Si la propiedad stagingResourceGroup se especifica con un grupo de recursos que no existe, el servicio Image Builder crea un grupo de recursos de almacenamiento provisional con el nombre que se proporciona en la propiedad stagingResourceGroup. Se producirá un error si el nombre especificado no cumple los requisitos de nomenclatura de Azure para los grupos de recursos. El grupo de recursos de almacenamiento provisional tiene aplicadas las etiquetas predeterminadas: createdBy, imageTemplateName, imageTemplateResourceGroupName. De forma predeterminada, la identidad asignada al recurso de plantilla de imagen de Azure Image Builder tiene aplicado el control de acceso basado en rol "Colaborador" en el grupo de recursos.

Eliminación de plantillas

Cualquier grupo de recursos de almacenamiento provisional creado por el servicio Image Builder se eliminará una vez eliminada la plantilla de imagen. La eliminación incluye los grupos de recursos de almacenamiento provisional especificados en la propiedad stagingResourceGroup, pero que no existían antes de la compilación de la imagen.

Si Image Builder no creó el grupo de recursos de almacenamiento provisional, pero creó recursos dentro del grupo de recursos, esos recursos se eliminarán después de eliminar la plantilla de imagen siempre y cuando el servicio Image Builder tenga los permisos o el rol adecuados necesarios para eliminar recursos.

Propiedades: validar

Puede usar la validate propiedad para validar las imágenes de la plataforma y las imágenes personalizadas que cree independientemente de si ha usado Azure Image Builder para crearlas.

Azure Image Builder admite un modo «Solo validación de origen» que se puede establecer mediante la propiedad sourceValidationOnly. Si la propiedad sourceValidationOnly se establece en true, la imagen especificada en la sección source se validará directamente. No se ejecutará ninguna compilación independiente para generar y, a continuación, validar una imagen personalizada.

La propiedad inVMValidations toma una lista de validadores que se realizarán en la imagen. Azure Image Builder admite validadores de Archivo, PowerShell y Shell.

La propiedad continueDistributeOnFailure es responsable de si las imágenes de salida se distribuirán si se produce un error en la validación. De manera predeterminada, si se produce un error en la validación y esta propiedad se establece en false, las imágenes de salida no se distribuirán. Si se produce un error en la validación y esta propiedad se establece en true, la(s) imagen(es) de salida se seguirá(n) distribuyendo. Use esta opción con precaución, ya que puede dar lugar a que las imágenes con errores se distribuyan para su uso. En cualquier caso (true o false), la ejecución de la imagen de un extremo a otro se notificará como un error en caso de error de validación. Esta propiedad no tiene ningún efecto en si la validación se realiza correctamente o no.

Al usar validate:

  • Puede usar varios validadores.
  • Los validadores se ejecutan en el orden especificado en la plantilla.
  • Si un validador falla, todo el componente de validación fallará e informará de un error.
  • Es recomendable que pruebe exhaustivamente el script antes de usarlo en una plantilla. Será más fácil depurar el script en su propia máquina virtual.
  • No incluya información confidencial en los scripts.
  • Las ubicaciones de los scripts deben ser accesibles públicamente, a menos que esté usando MSI.

Uso de la propiedad validate para validar imágenes de 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>"
            }
         ]
      }
   }
}

inVMValidations propiedades:

  • type: PowerShell.

  • nombre: nombre del validador

  • scriptUri: URI a la ubicación del archivo de script de PowerShell.

  • inline: conjunto de comandos alineados que se ejecutarán, separados por comas.

  • validExitCodes: opcional, códigos válidos que pueden devolverse desde el comando de script o alineado; esto evitará que se informe de un error del comando de script o alineado.

  • runElevated: opcional, booleano, admite la ejecución de comandos y scripts con permisos elevados.

  • sha256Checksum: valor de la suma de comprobación sha256 del archivo, se genera de forma local y, a continuación, Image Builder realizará la suma de comprobación y la validación.

    Para generar el valor de sha256Checksum, con PowerShell en Windows utilice Get-hash

Cómo usar la propiedad validate para validar imágenes de 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"
        }
      ]
    }
  }
}

inVMValidations propiedades:

  • type: Shell o archivo especificados como el tipo de validación que se va a realizar.

  • nombre: nombre del validador

  • scriptUri - URI del archivo de script

  • inline: conjunto de comandos alineados que se ejecutarán, separados por comas.

  • sha256Checksum: valor de la suma de comprobación sha256 del archivo, se genera de forma local y, a continuación, Image Builder realizará la suma de comprobación y la validación.

    Para generar el valor de sha256Checksum, mediante un terminal en Mac o Linux ejecute sha256sum <fileName>

  • destination: destino del archivo.

  • sha256Checksum: especifica la suma de comprobación SHA256 del archivo.

  • sourceUri: el URI de origen del archivo.

Propiedades: vmProfile

vmSize (opcional)

Image Builder usa un tamaño de SKU predeterminado de Standard_D1_v2 para imágenes de Gen1 y de Standard_D2ds_v4 para imágenes de Gen2. La generación se define mediante la imagen que especifique en la propiedad source. Puede invalidar vmSize por estos motivos:

  • Realizar personalizaciones que requieran mayor memoria, CPU y control de archivos grandes (GB).
  • Al ejecutar compilaciones de Windows, debe usar "Standard_D2_v2" o un tamaño de máquina virtual equivalente.
  • Requerir aislamiento de máquina virtual.
  • Personalice una imagen que requiera hardware específico. Por ejemplo, para una máquina virtual de GPU, necesita un tamaño de máquina virtual de GPU.
  • Requerir cifrado de un extremo a otro en el resto de la máquina virtual de compilación; debe especificar el tamaño de máquina virtual de compilación compatible que no usa discos temporales locales.

osDiskSizeGB

De manera predeterminada, el generador de imágenes no cambiará el tamaño de la imagen, sino que usa el tamaño de la imagen de origen. Opcionalmente, solo puede aumentar el tamaño del disco del sistema operativo (Win y Linux), y un valor de 0 significa que se aplica el mismo tamaño de la imagen de origen. No se puede reducir el tamaño del disco del sistema operativo a un tamaño inferior al de la imagen de origen.

{
  "osDiskSizeGB": 100
}

vnetConfig (opcional)

Si no especifica ninguna propiedad de la red virtual, Image Builder crea la suya propia, la dirección IP pública y el grupo de seguridad de red (NSG). La dirección IP pública se usa para que el servicio se comunique con la máquina virtual de compilación. Si no quiere tener una dirección IP pública o desea que Image Builder tenga acceso a los recursos de red virtual existentes, por ejemplo, servidores de configuración (DSC, Chef, Puppet, Ansible) o recursos compartidos de archivos, puede especificar una red virtual. Para obtener más información, consulte la documentación de redes.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
}

Operaciones de plantilla de imagen

Inicio de una compilación de imagen

Para iniciar una compilación, debe invocar el comando "run" en el recurso de plantilla de imagen; estos son ejemplos de comandos run:

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

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

Cancelación de una compilación de imagen

Si va a ejecutar una compilación de imagen que cree que es incorrecta y está en espera de la entrada de usuario, o si cree que no se completará correctamente, puede cancelar la compilación.

La compilación se puede cancelar en cualquier momento. Si se ha iniciado la fase de distribución, aún puede cancelar la operación, pero deberá cerrar todas las imágenes que no se hayan completado. El comando de cancelación no espera a que se complete la cancelación, así que debe supervisar el valor de lastrunstatus.runstate para cancelar el progreso, mediante estos comandos de estado.

Ejemplos de comandos cancel:

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

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

Pasos siguientes

Encontrará archivos .json de ejemplo para diferentes escenarios en el GitHub de Azure Image Builder.