az image builder

Manage and build image builder templates.

Commands

az image builder cancel

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

az image builder create

Create an image builder template.

az image builder customizer

Manage image builder template customizers.

az image builder customizer add

Add an image builder customizer to an image builder template.

az image builder customizer clear

Remove all image builder customizers from an image builder template.

az image builder customizer remove

Remove an image builder customizer from an image builder template.

az image builder delete

Delete image builder template.

az image builder list

List image builder templates.

az image builder output

Manage image builder template output distributors.

az image builder output add

Add an image builder output distributor to an image builder template.

az image builder output clear

Remove all image builder output distributors from an image builder template.

az image builder output remove

Remove an image builder output distributor from an image builder template.

az image builder run

Build an image builder template.

az image builder show

Show an image builder template.

az image builder show-runs

Show an image builder template's run outputs.

az image builder update

Update an image builder template.

az image builder wait

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

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.

az image builder create

Create an image builder template.

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

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 builder 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 \
    --identity myidentity

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 my-group --scripts $script --identity myidentity --defer

# add customizers
az image builder 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 builder 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 builder output add -n mytemplate -g my-group --is-vhd \
    --output-name my-win-image-vhd --artifact-tags "is_vhd=True" --defer

az image builder 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 builder 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.

--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/en-us/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.

--os-disk-size

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

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

--subnet

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

--subscription

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

--tags

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

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

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.

az image builder list

List image builder templates.

az image builder list [--query-examples]
                      [--resource-group]
                      [--subscription]

Optional Parameters

--query-examples

Recommend JMESPath string for you. You can copy one of the query and paste it after --query parameter within double quotation marks to see the results. You can add one or more positional keywords so that we can give suggestions based on these key words.

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

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

Show an image builder template.

az image builder show [--ids]
                      [--name]
                      [--query-examples]
                      [--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.

--query-examples

Recommend JMESPath string for you. You can copy one of the query and paste it after --query parameter within double quotation marks to see the results. You can add one or more positional keywords so that we can give suggestions based on these key words.

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

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.

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

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

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