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
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.
The name of the image template.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
The name of the image template.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Optional Parameters
The Maximum duration to wait while building the image template, in minutes. Default is 60.
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.
The SHA256 checksum of the Red Hat ISO image.
Temporarily store the object in the local cache instead of sending to Azure. Use az cache
commands to view/clear.
List of user assigned identities (name or ID, space delimited) of the image template.
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.
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. Values from: az account list-locations
. You can configure the default location using az configure --defaults location=<location>
.
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.
Do not wait for the long-running operation to finish.
Size of the OS disk in GB. Omit or specify 0 to use Azure's default OS disk 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).
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 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.
The staging resource group id in the same subscription as the image template that will be used to build the image.
Name or ID of subnet to deploy the build virtual machine.
Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.
The type of validation you want to use on the Image. For example, "Shell" can be shell validation.
Size of the virtual machine used to build, customize and capture images. Omit or specify empty string to use the default (Standard_D1_v2).
Name of VNET to deploy the build virtual machine. You should only specify it when subnet is a name.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
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.
The name of the image template.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
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.
The name of the image template.
Do not wait for the long-running operation to finish.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
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.
The name of the image template.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
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.
The name of the image template.
Name of the image builder run output.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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 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>
.
Temporarily store the object in the local cache instead of sending to Azure. Use az cache
commands to view/clear.
When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.
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.
The name of the image template.
Remove a property or an element from a list. Example: --remove property.list <indexToRemove>
OR --remove propertyToRemove
.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
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
Wait until created with 'provisioningState' at 'Succeeded'.
Wait until the condition satisfies a custom JMESPath query. E.g. provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running'].
Wait until deleted.
Wait until the resource exists.
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.
Polling interval in seconds.
The name of the image template.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Maximum wait in seconds.
Wait until updated with provisioningState at 'Succeeded'.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.