Pre- and post-bundle customization steps

Danger

This is an advanced feature. Only use it if you require the functionality and are comfortable troubleshooting Azure Image Builder (AIB) behavior. Prefer implementing logic in your layer scripts. Support is limited concerning this feature.

In some cases, adding AIB customization steps can be useful during the image build process. For example, they can be used to:

• Run PowerShell scripts before or after the layer install.ps1 scripts are run.
• Ask Azure Image Builder to perform a Windows restart.
• Ask Azure Image Builder to update Windows.

Tip

Adding updates and restarts is often not necessary. The avdcli already selects the latest available Azure marketplace Windows image version, which should include important recent Windows updates. A Windows restart is already performed after layer execution finishes.

To add AIB customization steps, add customizers.pre and/or customizers.post entries to the layer’s properties.json5 file.

For example:

{
    "version": "v2.1",
    "name": "com.schoolyear.example",
    "description": "Example description",
    "author": {
        "name": "Schoolyear",
        "email": "avd@schoolyear.com"
    },
    "platform_version": "2",
    "build_parameters": {
        "exampleValue": {
            "description": "An example build parameter",
            "enum": ["option-a", "option-b", "option-c"]
        }
    },
    "customizers": {
        "pre": [
            {
                "type": "WindowsUpdate",
                "name": "ExampleWindowsUpdate"
            },
            {
                "type": "WindowsRestart",
                "name": "ExampleWindowsRestart"
            }
        ],
        "post": [
            {
                "type": "File",
                "name": "FILE_ExampleScript",
                "destination": "C:\\Example\\exampleScript.ps1",
                "sourceUri": "https://example.com/exampleScript.ps1"
            },
            {
                "type": "PowerShell",
                "name": "CONF_ApplyExample",
                "inline": ["Write-Host \"Hello, World\""],
                "system": true,
                "elevated": true
            }
        ]
    }
}

An example of this functionality in use can be found here. The schema for these customization steps is described in the Azure Image Builder documentation.

The following diagram shows the execution order of the bundle and the AIB customization steps:

%%{init: {
  "flowchart": {
    "nodeSpacing": 20,
    "rankSpacing": 24,
    "padding": 4
  }
}}%%
flowchart TD
    A["1. Retrieves bundle zip from the storage account"]
    B["2. Extracts the bundle to C:\image_bundle\"]
    C["3. Executes customizers.pre steps"]
    D["4. Executes each layer's install.ps1 script"]
    E["5. Restarts the VM"]
    F["6. Executes customizers.post steps"]
    G["7. Deletes C:\image_bundle.zip and C:\image_bundle from the VM"]
    H["8. Starts Sysprep"]

    A --> B --> C --> D --> E --> F --> G --> H