Exam Orchestrator

The picture below shows a general overview of the lifecycle of an exam in Schoolyear AVD. Schoolyear AVD will call Azure-provided APIs in your Azure tenant to perform these orchestration actions in your Azure Tenant.

Architecture Overview

Start deployment

A configurable number of minutes before the start of an exam that requires AVD, the deployment starts. This preparation time can be configured per exam environment and is called the “Deployment Duration”. Once the deployment has started, the exam configuration cannot be edited anymore. New exams must be scheduled further into the future than it takes to deploy the exam. For example, if the configured Deployment Duration is 2 hours, an exam must be scheduled at least 2 hours in advance.

The following actions are performed during deployment:

A new Resource Group is created in the configured Azure Subscription and location
The main deployment is started within that Resource Group using a configurable Template Spec hosted in your Azure Tenant. This deployment takes care of creating the necessary resources (Application group is also among those resources). At the end of the main deployment a link to another deployment template is returned as output. We call this returned deployment template individual vm deployment template and it will be used to deploy all the Virtual Machines necessary for the exam.
We concurrently start deploying individual Virtual Machines using the returned deployment template from the previous step. During this time the orchestrator periodically checks for the status of each Virtual Machines’ deployment and if it detects a failure it retries the deployment. We do this to add fault tolerance in our deployments and have higher success rates.
Update the display name of the Application Group to be something unique per exam. This step is necessary for the Schoolyear Client to be able to differentiate the SY exam Application Group from other, unrelated Application Groups present in your Azure environment and to be able to auto-click it during the SessionHost connection for a smoother experience.
Check that enough Sessionhosts are available in the newly deployed Hostpool.

These actions may be performed multiple times in case a deployment job is restarted. The actions must therefore be idempotent. The creation of the Resource Group is idempotent by default. However, you must take extra care in development of the Template Spec.

If any of the actions fail or time out, the deployment job is retried 2 times, after which it is considered failed (3 tries in total).

Resource Group & Deployment

A new Resource Group is created in the Subscription that you configure. This Resource Group will be named syexam-<<examID>>, where examID is the ID in Schoolyear’s system.

Within this Resource Group, a deployment is started using a Template Spec that is hosted in your Azure Tenant. The parameters that are provided to this Template Spec are described in the Template API section of this Chapter.

Main deployment template

The main deployment template is responsible for deploying only those resources necessary for the infrastructure the Session Hosts are going to need in order to be deployed and function.

The actual deployment of the Virtual Machines is handled in a separate deployment template which is returned by the main template. By separating the deployment of individual Virtual Machines from the main template we reduce the risk of a single bad deployment affecting the whole exam deployment. It is far more likely that a deployment will experience issues during the Virtual Machine deployement than any other step. Therefore, by retrying individual Virtual Machine deployments we make our whole exam deployment more robust to failures.

The main deployment template returns a couple of outputs that are necessary and used by the Schoolyear Backend to successfully deploy individual Virtual Machines and retry their deployments in case of failure.

vmNamePrefix: This is used by the Schoolyear Backend to prefix the name of individual machines. All Virtual Machines will be in the form of vmNamePrefix-index
vmCreationTemplateUri: This is the link to the individual virtual machine deployment template
vmCreationTemplateCommonInputParameters: These are common parameters that are passed to the individual virtual machine deployement template and remain the same no matter which Virtual Machine is being deployed
vmCreationResourceUrls: This is an array of formatted strings containing the Azure Resource IDs of individual Virtual Machine resources. We use this array in the Schoolyear Backend to delete the resources in case of a failed individual deployment. This way we ensure that all retries are from a clean slate and have a higher change of success. For example the resource id of the actual Azure Virtual Machine would be: https://management.azure.com/subscriptions/${subscription().subscriptionId}/resourceGroups/${resourceGroup().id}/providers/Microsoft.Compute/virtualMachines/{{vmName}}?api-version=2021-04-01. The {{vmName}} will be replaced by the Schoolyear Backend by the actual vmName and is the only formatted string that will be replaced. At the time of writing this guide, we only create a Virtual Machine and the attached Network Interface, if you want to modify the Virtual Machine deployment template to deploy extra resources you should also update the list of deletion URLs to allow the Schoolyear Backend properly handle deployment retries.

Individual Virtual Machine deployment template

The link to this template is returned to the orchestrator by the main deployment template. And is solely responsible for deploying individual Virtual Machines and any resources needed by the Virtual Machine to be acceessible. It accepts a number of parameters as input. Most of the parameters do not change for individual Virtual Machines and are therefore grouped together in a single object parameter named commonInputParameters. It also accepts a single vmName parameter which changes depending on which Virtual Machine is being deployed. You will only ever need to modify these parameters yourself if you want to customize the deployment process.

Check Sessionhost availability

After the deployment of the Template Spec finishes, Schoolyear AVD will monitor the amount of Sessionhosts that are marked as “Available” in the newly deployed Hostpool.

A configurable minimum of Sessionhosts must be registered as “Available” in the hostpool within 120 minutes of the deployment succeeding. If not, the deployment is considered failed.

Once the minimum number of available Sessionhosts is reached, the deployment succeeds and the monitoring of available Sessionhosts stops.

This minimum is configured by an output of the Template Spec which is described in the Template API section of this Chapter.

Student begins exam

Up to 30 minutes before the start time of an exam, students may start Schoolyear Safe Exam Workspace (SEW) to prepare for their exam.

In the loading screen of SEW, they will be presented with a prompt to log into their Microsoft account. After logging in, student accounts are granted 2 essential role assignments that allow the student to login and use the Sessionhost.

Granted role assignments:

To provide Azure some time to propagate these role assignments, the student needs to wait a few seconds before they can continue their onboarding process.

Once the exam start time passes, the student is shown a fullscreen view of the AVD Web Client.

Deletion

At the exam end timestamp, the deletion job will start.

It will execute the following delete steps:

Delete “Extra Resources” outputted by the Template Spec during deployment
Delete Resource Group: thereby deleting all resources in it

These steps may fail individually, but do not prevent the other steps from being executed. However, if any of these steps fail, the deletion is considered a failure.

Deletion jobs are retried 2 times for a total of 3 attempts.

Deleting Extra Resources

The Template Spec may output a list of Resource URIs during deployment of resources outside the exam’s Resource Group that need to be deleted at the end of the exam.

These resources are deleted by calling the DELETE HTTP method on their Resource URI. This HTTP request is retried once for a total of two attempts.

The HTTP request is performed using the same authentication as for all other requests made by the Exam Orchestrator.

Deleting the Resource Group

The Resource Group is delete by name with the following types configured to be force-deleted:

Microsoft.Compute/virtualMachines
Microsoft.Compute/virtualMachineScaleSets