Practical guide

This practical guide details the steps for publishing a new App in your AVD Add-on. Once published, teachers will be able to select it when configuring an exam.

This guide assumes you are familiar with the Introduction page and with building Windows images in general.

1. Install or update the avdcli, the tool you need for building Exam Images.

2. Find or implement the layers you need. This includes writing non-interactive PowerShell scripts to install your applications.

3. Bundle the layers together into a “bundle”, using the avdcli tool.

4. Build the image, using the avdcli tool.

5. Configure the App in the add-on, to make it available for use.

1. Install or update avdcli

To get started with this guide, you need to download the avdcli tool. You can download the latest version from here. Renaming the binary to avdcli and add it to your PATH. The rest of this guide assumes you have the avdcli command available in your terminal.

Download avdcli

Caution

Every time you build an image, even through automation, make sure you have the latest avdcli installed. These updates include updates to the scripts used to clean up Windows, such as removing unnecessary Windows apps. As Windows changes over time, we keep updating these scripts.

Use avdcli -v to verify the tool is available in your terminal. Use avdcli update to automatically update to the latest version.

Running on macOS

The pre-built binary on the release page of avdcli is not notarized. So when you try to run it, macOS will refuse. Follow these steps to whitelist the avdcli on your machine:

1. Download the binary and rename it to avdcli.

2. Allow execution of the binary by running chmod +x avdcli.

3. Execute the downloaded avdcli from your command line or by double-clicking it. MacOS will show a popup prompting you to delete the file. Do not delete the file but dismiss the popup (“Done”).

4. Open System Preferences and navigate to Privacy & Security.

5. Scroll down to Security and click Open Anyway.

6. Execute the binary from your command line again. MacOS will show a popup, click “Open Anyway”.

2. Find or implement your layers

You need to decide which applications you want to include in the image. Then, you need to source the Layers for each of these applications. Make a list of applications you want to include in the image and make sure you have a layer ready to go for each.

You may have already implemented a layer for an application before, or your Managed Service Provider may have one already. If not, you have to implement a custom layer. Follow the Custom Layer guide to implement the layers you need for this image.

3. Bundle your layers

Once you have all the layers you need for this image, you can bundle them together.

Run the following command and add a -l parameter for each layer you want to add to the image.

avdcli bundle layers -l ./path/to/layer1 -l ./path/to/layer2

Layer parameters

Some layers may have parameters that need to be filled in during this bundling step, for which avdcli will prompt you interactively.

The most common parameter you will be prompted for is the environment. This parameter describes for which Schoolyear environment you are building this image. You can pick Production or Beta depending on the environment in which you implemented Schoolyear AVD.

Non-interactive parameters

If you are running avdcli in a non-interactive session, you can pass the -noninteractive flag. This will make the command fail if it cannot resolve a layer parameter.

To resolve the parameters non-interactively, you need to pass the path to a json file that contains the parameters. Use the -p(arameters) flag to pass the path and follow this file structure to specify the parameters:

{
  "version": "2",
  "layers": {
    "com.schoolyear.avd": {
      "environment:": {
        "value": "Production"
      }
    }
  }
}

4. Build the image

As detailed in the Introduction, you need an Image Definition to store your image in. If you are building a new version of an existing image, you can use the Image Definition you made before. However, if you are building the first version of a new image, you need to create an Image Definition in Azure.

1. Navigate to your AVD add-on in the Schoolyear Admin Dashboard and go to the Apps tab.

2. If you are creating a new App, click on the + symbol. If you want to update an existing App, open that App.

3. Click on Build a new image

4. Copy the command that starts with avdcli bundle autobuild and execute it in the same folder in which you ran the avdcli bundle layers command.

5. avdcli will ask you in which Image Definition the image should be stored. If you are building a new version of an existing image, select the correct Image Definition in the list. However, if you are building the first version of a new image, follow the link provided by avdcli to create a new one in the Azure Portal using the steps detailed below. After creating the Image Definition, restart the avdcli bundle autobuild command, and select the Image Definition you just created.

6. Monitor the progress of the Image Builder here and wait for the build to complete. If the build fails, follow this Microsoft guide to troubleshoot the problem.

Create a new Image Definition

If you are building the first version of a new image, you need to create a new Image Definition in the Image Gallery associated with your implementation. When you run the avdcli bundle autobuild command from the previous step, it will provide you with a direct link to the page where you can create one. Alternatively, you can locate the Image Gallery in the Subscription you are using and create a new Image Definition that way.

Once you have located the correct Image Gallery, follow these steps to create a new Image Definition:

1. Click Add >VM image definition.

2. Give your Image Definition a name in the VM image definition name. This is the name you select when building an image using the avdcli tool and the name you enter in the AVD add-on when specifying the Image Definition.

3. Configure a Publisher, Offer and SKU for the Image Definition. You can specify any values you want, or follow this standard:

   • Publisher: name of your organization (e.g., university-of-somewhere)
   • Offer: name of the App (e.g., ms-office)
   • SKU: type of the App (e.g., office-365-en)

4. Click Review + create and create the Image Definition

5. Configure the App

Once the image building process is complete, you can configure an App in the AVD add-on to use the image.

• Info
  • Name: This is the name visible to teachers when selecting Apps
  • Thumbnail URL (optional): URL of an image shown to teachers when selecting Apps
• Orchestration
  • Max duration: Max duration of an exam planned with this App
  • Deployment duration: The amount of time the deployment job for an exam starts when this App is selected.
• Session hosts
  • VM size: The VM size from Azure that will be used for the VM of each student
  • Image Source: Select Default unless your image is stored in a non-default Image Gallery (advanced)
  • Image Definition: The name of the Image Definition in which the image is stored. You can also specify a version of the image or use latest.
• Quota
  • Name: Select the azurevms quota you created during the implementation of this AVD add-on.
  • Value: Simply enter 2*(n + max(5, ceil(n*0.02))) + min(max(2, int(ceil(n / 10))), 10). This assumes the VM size you configured has 2 CPU cores. If you selected a different size, adjust the 2 at the start accordingly.
• Advanced
  • proxy VM size: The VM size from Azure that will be used for the Trusted Proxy VMs.

Danger

Note changing Deployment duration only applies to exams configured after you made the change. Exams for which AVD is already enabled, will continue to use the Deployment duration that was configured at the time AVD was enabled for that exam.

If you configured everything to your liking, you can click Save Changes to publish the App.