az image builder

Manage and build image builder templates.

Commands

Name	Description	Type	Status
az image builder cancel	Cancel the long running image build based on the image template.	Core	GA
az image builder create	Create an image builder template.	Core	GA
az image builder customizer	Manage image builder template customizers.	Core	GA
az image builder customizer add	Add an image builder customizer to an image builder template.	Core	GA
az image builder customizer clear	Remove all image builder customizers from an image builder template.	Core	GA
az image builder customizer remove	Remove an image builder customizer from an image builder template.	Core	GA
az image builder delete	Delete image builder template.	Core	GA
az image builder error-handler	Manage image builder template error handler.	Core	GA
az image builder error-handler add	Add error handler to an existing image builder template.	Core	GA
az image builder error-handler remove	Remove error handler from an existing image builder template.	Core	GA
az image builder error-handler show	Show error handler of an existing image builder template.	Core	GA
az image builder identity	Manage identities of an image builder template.	Core	GA
az image builder identity assign	Add managed identities to an existing image builder template. Currently, only one user identity is supported.	Core	GA
az image builder identity remove	Remove managed identities from an existing image builder template.	Core	GA
az image builder identity show	Display managed identities of a image builder template.	Core	GA
az image builder list	List image builder templates.	Core	GA
az image builder optimizer	Manage image builder template optimizer.	Core	GA
az image builder optimizer add	Add optimizer to an existing image builder template.	Core	GA
az image builder optimizer remove	Remove optimizer from an existing image builder template.	Core	GA
az image builder optimizer show	Show optimizer of an existing image builder template.	Core	GA
az image builder optimizer update	Update an optimizer from an existing image builder template.	Core	GA
az image builder output	Manage image builder template output distributors.	Core	GA
az image builder output add	Add an image builder output distributor to an image builder template.	Core	GA
az image builder output clear	Remove all image builder output distributors from an image builder template.	Core	GA
az image builder output remove	Remove an image builder output distributor from an image builder template.	Core	GA
az image builder output versioning	Manage image builder template output versioner.	Core	GA
az image builder output versioning remove	Remove all versioning options on specified outputs.	Core	GA
az image builder output versioning set	Set the image builder output versioner of an image builder template.	Core	GA
az image builder output versioning show	Show versioning options on specified outputs.	Core	GA
az image builder run	Build an image builder template.	Core	GA
az image builder show	Show an image builder template.	Core	GA
az image builder show-runs	Show an image builder template's run outputs.	Core	GA
az image builder trigger	Manage image builder template trigger.	Core	GA
az image builder trigger create	Create a trigger for the specified virtual machine image template.	Core	GA
az image builder trigger delete	Delete a trigger for the specified virtual machine image template.	Core	GA
az image builder trigger list	List all triggers for the specified Image Template resource.	Core	GA
az image builder trigger show	Get the specified trigger for the specified image template resource.	Core	GA
az image builder trigger wait	Place the CLI in a waiting state until a condition is met.	Core	GA
az image builder update	Update an image builder template.	Core	GA
az image builder validator	Manage image builder template validate.	Core	GA
az image builder validator add	Add validate to an existing image builder template.	Core	GA
az image builder validator remove	Remove validate from an existing image builder template.	Core	GA
az image builder validator show	Show validate of an existing image builder template.	Core	GA
az image builder wait	Place the CLI in a waiting state until a condition of the template is met.	Core	GA

az image builder cancel

Cancel the long running image build based on the image template.

az image builder cancel [--ids]
                        [--name]
                        [--resource-group]
                        [--subscription]

Examples

Cancel an image build.

az image builder cancel -n mytemplate -g my-group

Optional Parameters

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder create

Create an image builder template.

az image builder create --name
                        --resource-group
                        [--build-timeout]
                        [--build-vm-identities]
                        [--checksum]
                        [--defer]
                        [--identity]
                        [--image-source]
                        [--image-template]
                        [--location]
                        [--managed-image-destinations]
                        [--no-wait]
                        [--os-disk-size]
                        [--proxy-vm-size]
                        [--scripts]
                        [--shared-image-destinations]
                        [--staging-resource-group]
                        [--subnet]
                        [--tags]
                        [--validator]
                        [--vm-size]
                        [--vnet]

Examples

Create an image builder template from an Ubuntu2204 image. Distribute it as a managed image and a shared image gallery image version. Specify the staging resource group id as the image template that will be used to build the image.

scripts="https://my-script-url.net/customize_script.sh"
imagesource="Canonical:0001-com-ubuntu-server-jammy:22_04-lts-gen2:latest"

az image builder create --image-source $imagesource -n myTemplate -g myGroup \
    --scripts $scripts --managed-image-destinations image_1=westus \
    --shared-image-destinations my_shared_gallery/linux_image_def=westus,brazilsouth \
    --identity myIdentity --staging-resource-group myStagingResourceGroup

Create an image builder template using an image template file.

az image builder create -g my-group -n myTemplate --image-template filename

[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 builder create --image-source $imagesource -n myTemplate \
    -g myGroup --scripts $script --identity myIdentity --defer

# add customizers
az image builder customizer add -n myTemplate -g myGroup  \
    --customizer-name myPwshScript --exit-codes 0 1 --inline-script \
    "mkdir c:\buildActions" "echo Azure-Image-Builder-Was-Here \
     > c:\buildActions\Output.txt" --type powershell --defer

az image builder customizer add -n myTemplate -g myGroup \
    --customizer-name myFileCustomizer --type file \
    --file-source "https://my-file-source.net/file.txt"  \
    --dest-path "c:\buildArtifacts\file.txt" --defer

# add distributors
az image builder output add -n myTemplate -g myGroup --is-vhd \
    --output-name myWinImageVhd --artifact-tags "is_vhd=True" --defer

az image builder output add -n myTemplate -g myGroup \
    --output-name myWinImageManaged --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 builder update -n myTemplate -g myGroup

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.

--build-vm-identities

Optional configuration of the virtual network to use to deploy the build virtual machine in. Omit if no specific virtual network needs to be used.

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

--identity

List of user assigned identities (name or ID, space delimited) of the image template.

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

--image-template

Local path or URL to an image template file. When using --image-template, all other parameters are ignored except -g and -n. Reference: https://docs.microsoft.com/azure/virtual-machines/linux/image-builder-json.

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

default value: False

--os-disk-size

Size of the OS disk in GB. Omit or specify 0 to use Azure's default OS disk size.

--proxy-vm-size

Size of the virtual machine used to build, customize and capture images (Standard_D1_v2 for Gen1 images and Standard_D2ds_v4 for Gen2 images).

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

--staging-resource-group

The staging resource group id in the same subscription as the image template that will be used to build the image.

--subnet

Name or ID of subnet to deploy the build virtual machine.

--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--validator

The type of validation you want to use on the Image. For example, "Shell" can be shell validation.

--vm-size

Size of the virtual machine used to build, customize and capture images. Omit or specify empty string to use the default (Standard_D1_v2).

--vnet

Name of VNET to deploy the build virtual machine. You should only specify it when subnet is a name.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder delete

Delete image builder template.

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

Examples

Delete image builder template. (autogenerated)

az image builder delete --name MyImageTemplate --resource-group MyResourceGroup

Optional Parameters

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder list

List image builder templates.

az image builder list [--resource-group]

Optional Parameters

--resource-group -g

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder run

Build an image builder template.

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

Examples

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

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

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

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

Optional Parameters

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

--name -n

The name of the image template.

--no-wait

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

default value: False

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder show

Show an image builder template.

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

Examples

Show an image builder template (autogenerated)

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

Optional Parameters

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder show-runs

Show an image builder template's run outputs.

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

Examples

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

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

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

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

Optional Parameters

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder update

Update an image builder template.

Updating an image builder templates is currently unsupported. This command can be used in conjunction with --defer to update an image template object within the CLI cache. Without --defer it retrieves the specified image template from the cache and sends a request to Azure to create the image template.

az image builder 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. See "az image builder create / output add / customizer add --help" and "az cache -h" for more information

# create and write template object to local cli cache
az image builder create --image-source {image_source} -n mytemplate -g my-group \
    --scripts {script} --managed-image-destinations image_1=westus --identity myidentity --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 builder 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 builder 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>.

default value: []

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

default value: False

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

--name -n

The name of the image template.

--remove

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

default value: []

--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=<value>.

default value: []

--subscription

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

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az image builder wait

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

az image builder 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 builder run -n mytemplate -g my-group --no-wait

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

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

Optional Parameters

--created

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

default value: False

--custom

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

--deleted

Wait until deleted.

default value: False

--exists

Wait until the resource exists.

default value: False

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

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

default value: False

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc

default value: json

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

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

--verbose

Increase logging verbosity. Use --debug for full debug logs.