Image Layer reference

The avdcli works by combining multiple Image Layers into an Image Package and then building an image from that. These layers are meant to be reusable and combinable, allowing admins to mix them into the images they want.

Each layer is stored in its own directory and should have the following files and folders:

properties.json(5): Required, the Image Layer properties file.
build_steps.json(5): Optional, steps to execute during the image building.
resources/: Optional, a directory of resources required during the image build process.

Both .json and .json5 files are supported. .json5 files have the advantage of allowing inline comments and being less strict with formatting.

`properties.json`

Each layer should have a properties.json or properties.json5 file. The file can have the following properties:

{
  whitelistedHosts: {
    // Use this property to whitelist HTTP(S) connections that 3rd-party application may need to function
    // This is commonly used for internet-facing license servers
    //
    // The key should have the structure of "host:port" and may include wildcards ("*")
    // The value is ignored
    "catalogartifact.azureedge.net:443": {},
    "*.hip.live.com:443": {},
  },
  imageTemplate: {
    // The ImageTemplate object in the Azure Image Builder API
    // You can set any property of this object.
    // You "can" configure build steps in this object. However, you should use the `build_steps.json` file for that.
    // https://learn.microsoft.com/en-us/rest/api/imagebuilder/virtual-machine-image-templates/create-or-update

    // In this example, we set the source image of the image builder
    // This is usually not required for 3rd-party application layers, but Azure already has an image for Office
    // The public office365 layer uses this property, so it does not need to install Office itself
    properties: {
      source: {
        type: "PlatformImage",
        publisher: "microsoftwindowsdesktop",
        version: "latest",
        sku: "win10-22h2-avd-m365-g2",
        offer: "office-365"
      }
    },

    // You can use parameters in this file
    // See the avdcli reference documentation for more information.
    location: "[[[param:location]]]"
  },
  placeholderProperties: {
    // These keys may be used for templating.
    // See the avdcli reference documentation for more information.
    "key": "value"
  },
  internalServices: {
    // These keys may be used to specify Private Link Service IDs.
    // For each specified service ID a Private Endpoint will be created
    // in the services subnet that is going to be connected to the Service.
    // This is used to allow sessionhosts to connect to internal services.
    // For more information read the `Internal Services` section of this guide.
    "key": "value"
  },
}

`build_steps.json`

The build_steps.json(5) file is where you configure all the customization steps that are executed during the image building process. The schema for these customization steps is described in the Azure Image Builder documentation.

The build_steps.json file is divided into three sections to give you some control over the order of execution when combined with other layers.

{
  // if you need to execute steps before any `default` steps are executed
  pre: [],
  // the default place to put your building steps
  default: [
    {
      name: "Run Example",
      type: "PowerShell",
      inline: [
        "C:\\imagebuild_resources\\example\\example.ps1"
      ],
      runAsSystem: true,
      runElevated: true
    },
    {
      "name": "Windows Reboot",
      "type": "WindowsRestart"
    }
  ],
  // if you need to execute steps after all `default` steps are executed
  post: []
}

`resources/`

This folder contains all files you may need during the image building process. This folder is zipped-up and uploaded to the image building machine before any of the build steps are executed. The resources.zip is extracted to C:\imagebuild_resources. So if you put a file in layer/resources/subdir/file.txt, this file will be available during the image build process at C:\imagebuild_resources\subdir\file.txt.

The C:\imagebuild_resources folder is removed at the end of the image building process. If you want to keep some files available during the exam, you must copy them to another path during the image build process.

The resources folder is merged with that of all the other layers, so it is common practice to use a subdirectory with the name of the layer. For example, the layer rstudio would put its installation script in resources/rstudio/install.ps1.

Common resources structure

The resources folder is widely used to share scripts between layers. The most prominent usage of this is the default_layers/scripts_setup layer. This layer configures the image to execute some scripts at specific times during the start-up process of an exam. Other layers can configure their script for execution by placing them in specific subfolders of the resources folder.

This is such a common use-case that the avdcli will automatically create these folders with some example scripts when you use avdcli new to create a new layer.

Folder	Triggered
`resources/sessionhost_setup_scripts`	During the deployment of each sessionhost.
`resources/session_scripts`	When a student logs in. Executed as the `SYSTEM` user.
`resources/user_scripts`	When a student logs in. Executed as the student’s user.

The session scripts and user scripts are executed with the following parameters:

Parameter	Value
`uid`	SID of the Windows user logging in
`gid`	SID of the Windows user logging in
`username`	Username of the Windows user logging in
`homedir`	The absolute path to the home directory of the user
`provider`	Hardcoded to `avd`
`environment`	Name of the Schoolyear environment, such as `prod` or `beta`

You can use these parameters in your PowerShell scripts as such:

Param ($username, $homedir)

Write-Host "Welcome $username, your homedirectory is $homedir"