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. 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 Schoolyear 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": "v2",
  "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 Secure Apps Console 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. If you did not create the standard office image from the initial implementation, you need to grant yourself the Storage Blob Data Contributor role for the image building storage account. To add the role: navigate to the Azure portal, find the image building storage account in the image building resource group. Use the Access Control (IAM) tab to add a role assignment, to assign yourself the role: Storage Blob Data Contributor.

5. Back in the Schoolyear add-on screen, 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.

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

7. 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: Resources are deployed in Azure prior to each exam (e.g. student VMs). This is the amount of time you estimate Azure to pessimistically take to deploy these resources. (While this is dependent on the region, the minimum of 1 hour is a good starting point for exams under 300 students.)
  • Buffer window: The amount of time you want to reserve to respond to any deployment failures. This should be at least 2,5 times the deployment time.

Diagram of reservation time of the app (Deployment time + Buffer window):

    gantt

    dateFormat  HH:mm
    axisFormat %H:%M
    todayMarker off
    tickInterval 60minute


    section Deployment Time
    Deployment time           :a1, 05:30, 1h

    section Buffer Window
    Buffer window          :a2, after a1, 2.5h

    section Exam
    Exam Start           :milestone, a3, 09:00, 0h

• 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, int(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 VM 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 durationand Buffer window 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.