az image template

Manage and build image builder templates.

Commands

az image template create Create an image builder template.
az image template customizer Manage image builder template customizers.
az image template customizer add Add an image builder customizer to an image builder template.
az image template customizer clear Remove all image builder customizers from an image builder template.
az image template customizer remove Remove an image builder customizer from an image builder template.
az image template delete Delete image builder template.
az image template list List image builder templates.
az image template output Manage image builder template output distributors.
az image template output add Add an image builder output distributor to an image builder template.
az image template output clear Remove all image builder output distributors from an image builder template.
az image template output remove Remove an image builder output distributor from an image builder template.
az image template run Build an image builder template.
az image template show Show an image builder template.
az image template show-runs Show an image builder template's run outputs.
az image template update Update an image builder template.
az image template wait Place the CLI in a waiting state until a condition of the template is met.

az image template create

Create an image builder template.

az image template create --name
--resource-group
[--build-timeout]
[--checksum]
[--defer]
[--image-source]
[--location]
[--managed-image-destinations]
[--no-wait]
[--scripts]
[--shared-image-destinations]
[--subscription]
[--tags]

Examples

Create an image builder template from an UbuntuLTS 18.04 image. Distribute it as a managed image and a shared image gallery image version

scripts="https://my-script-url.net/customize_script.sh"
imagesource="Canonical:UbuntuServer:18.04-LTS:18.04.201903060"

az image template create --image-source $imagesource -n mytemplate -g my-group \
    --scripts $scripts --managed-image-destinations image_1=westus \
    --shared-image-destinations my_shared_gallery/linux_image_def=westus,brazilsouth

[Advanced] Create an image template with multiple customizers and distributors using the CLI's object cache via --defer. Supports features such as: customizer and output names, powershell exit codes, inline scripts, windows restart, file customizers, artifact tags and vhd output distributors.

script="https://my-script-url.com/customize_script.ps1"
imagesource="MicrosoftWindowsServer:WindowsServer:2019-Datacenter:2019.0.20190214"

# create and update template object in local cli cache. Defers put request to ARM
# Cache object ttl set via az configure.
az image template create --image-source $imagesource -n mytemplate \
    -g my-group --scripts $script --defer

# add customizers
az image template customizer add -n mytemplate -g my-group  \
    --customizer-name my-pwsh-script --exit-codes 0 1 --inline-script \
    "mkdir c:\buildActions" "echo Azure-Image-Builder-Was-Here \
     > c:\buildActions\Output.txt" --type powershell --defer

az image template customizer add -n mytemplate -g my-group \
    --customizer-name my-file-customizer --type file \
    --file-source "https://my-file-source.net/file.txt"  \
    --dest-path "c:\buildArtifacts\file.txt" --defer

# add distributors
az image template output add -n mytemplate -g my-group --is-vhd \
    --output-name my-win-image-vhd --artifact-tags "is_vhd=True" --defer

az image template output add -n mytemplate -g my-group \
    --output-name my-win-image-managed --managed-image winImage \
    --managed-image-location eastus \
    --artifact-tags "is_vhd=False" --defer

# Stop deferring put request to ARM. Create the template from the object cache.
# Cache object will be deleted.
az image template update -n mytemplate -g my-group

Required Parameters

--name -n

The name of the image template.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--build-timeout

The Maximum duration to wait while building the image template, in minutes. Default is 60.

--checksum

The SHA256 checksum of the Red Hat ISO image.

--defer

Temporarily store the object in the local cache instead of sending to Azure. Use az cache commands to view/clear.

--image-source -i

The base image to customize. Must be a valid platform image URN, platform image alias, Red Hat ISO image URI, managed image name/ID, or shared image version ID.

value from: az vm image list, az vm image show
--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--managed-image-destinations

Managed image output distributor information. Space-separated list of key-value pairs. E.g "image_1=westus2 image_2=westus". Each key is the name or resource ID of the managed image to be created. Each value is the location of the image.

--no-wait

Do not wait for the long-running operation to finish.

--scripts

Space-separated list of shell or powershell scripts to customize the image with. Each script must be a publicly accessible URL. Infers type of script from file extension ('.sh' or'.ps1') or from source type. More more customizer options and flexibility, see: 'az image template customizer add'.

--shared-image-destinations

Shared image gallery (sig) output distributor information. Space-separated list of key-value pairs. E.g "my_gallery_1/image_def_1=eastus,westus my_gallery_2/image_def_2=uksouth,canadaeast,francesouth." Each key is the sig image definition ID or sig gallery name and sig image definition delimited by a "/". Each value is a comma-delimited list of replica locations.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--tags

Space-separated tags in 'key[=value]' format. Use "" to clear existing tags.

az image template delete

Delete image builder template.

az image template delete [--ids]
[--name]
[--resource-group]
[--subscription]

Optional Parameters

--ids

One or more resource IDs (space-delimited). If provided, no other 'Resource Id' arguments should be specified.

--name -n

The name of the image template.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az image template list

List image builder templates.

az image template list [--resource-group]
[--subscription]

Optional Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az image template run

Build an image builder template.

az image template run [--ids]
[--name]
[--no-wait]
[--resource-group]
[--subscription]

Examples

Start a template build run and then wait for it to finish.

az image template run -n mytemplate -g my-group --no-wait

az image template wait -n mytemplate -g aibmdi \
    --custom "lastRunStatus.runState!='running'"

az image template show -n mytemplate -g my-group

Optional Parameters

--ids

One or more resource IDs (space-delimited). If provided, no other 'Resource Id' arguments should be specified.

--name -n

The name of the image template.

--no-wait

Do not wait for the long-running operation to finish.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az image template show

Show an image builder template.

az image template show [--ids]
[--name]
[--resource-group]
[--subscription]

Examples

Show an image builder template (autogenerated)

az image template show --name mytemplate --resource-group my-group

Optional Parameters

--ids

One or more resource IDs (space-delimited). If provided, no other 'Resource Id' arguments should be specified.

--name -n

The name of the image template.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az image template show-runs

Show an image builder template's run outputs.

az image template show-runs [--ids]
[--name]
[--output-name]
[--resource-group]
[--subscription]

Examples

Run a template build run and then view its run outputs.

az image template run -n mytemplate -g my-group --no-wait

az image template wait -n mytemplate -g aibmdi \
    --custom "lastRunStatus.runState!='running'"

az image template show-runs -n mytemplate -g my-group

Optional Parameters

--ids

One or more resource IDs (space-delimited). If provided, no other 'Resource Id' arguments should be specified.

--name -n

The name of the image template.

--output-name

Name of the image builder run output.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az image template update

Update an image builder template.

az image template update [--add]
[--defer]
[--force-string]
[--ids]
[--name]
[--remove]
[--resource-group]
[--set]
[--subscription]

Examples

Create a template resource from a template object in the cli cache.

# create and write template object to local cli cache
az image template create --image-source {image_source} -n mytemplate -g my-group \
    --scripts {script} --managed-image-destinations image_1=westus --defer

# add customizers and outputs to local cache template object via az image template output / customizer add
# one can also update cache object properties through generic update options, such as: --set
az image template output add -n mytemplate -g my-group --output-name my-win-image-managed \
    --artifact-tags "is_vhd=False"  --managed-image winImage --managed-image-location eastus --defer

# send template create request to azure to create template resource
az image template update -n mytemplate -g my-group

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

--defer

Temporarily store the object in the local cache instead of sending to Azure. Use az cache commands to view/clear.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

--ids

One or more resource IDs (space-delimited). If provided, no other 'Resource Id' arguments should be specified.

--name -n

The name of the image template.

--remove

Remove a property or an element from a list. Example: --remove property.list OR --remove propertyToRemove.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az image template wait

Place the CLI in a waiting state until a condition of the template is met.

az image template wait [--created]
[--custom]
[--deleted]
[--exists]
[--ids]
[--interval]
[--name]
[--resource-group]
[--subscription]
[--timeout]
[--updated]

Examples

Start a template build run and then wait for it to finish.

az image template run -n mytemplate -g my-group --no-wait

az image template wait -n mytemplate -g aibmdi \
    --custom "lastRunStatus.runState!='running'"

az image template show -n mytemplate -g my-group

Optional Parameters

--created

Wait until created with 'provisioningState' at 'Succeeded'.

--custom

Wait until the condition satisfies a custom JMESPath query. E.g. provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running'].

--deleted

Wait until deleted.

--exists

Wait until the resource exists.

--ids

One or more resource IDs (space-delimited). If provided, no other 'Resource Id' arguments should be specified.

--interval

Polling interval in seconds.

default value: 30
--name -n

The name of the image template.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--timeout

Maximum wait in seconds.

default value: 3600
--updated

Wait until updated with provisioningState at 'Succeeded'.