Azure Resource Templates Best Practices

This document outlines the considerations and recommendations for Lab Authors who wish to use Microsoft Azure Resource Templates as part of a Cloud Slice deployment. No guidance is a substitute for thorough testing, and all templates should be fully tested before release and on a regular basis during the life of the lab they support. Azure frequently changes, and changes may have a negative impact on existing, especially older, templates, which may require updates to remain current and valid.

Preparing a Resource Template for Deployment in Cloud Slice

A cloud slice lab may contain one or more resource groups. Each resource group can consist of one or more Resource Template  deployed concurrently. A cloud slice will contain one user account, but may contain multiple user accounts. User accounts can be assigned access to resource groups based on the build-in roles of Contributor, Owner, and Reader.

The recommended process for building and testing an Resource Template for inclusion in Skillable Studio is as follows.

1. Log into your Azure Subscription and create a new RG.

2. Create and configure the resources that you want deployed for students within your RG.

3. Once you have your resources the way you want, use Azure to view/export the script. Take note of any messages related to resources/config that are not applied to the RG -- these will require either manual updates to the Resource Template or a PowerShell script run as part of a Life Cycle Action when the lab launches.

4. Save both the Resource Template script and the parameters to disk.

5. Test deployment of your Resource Template into a new RG in the same subscription, in the region where you want the resources deployed, from outside of Azure, using a user account that only has Contributor access to that RG (no subscription level access). This can be done using PowerShell or the Azure CLI.

6. Once you confirm your Resource Template deploys successfully, delete the RG and its contents.

7. Modify your Resource Template so that any resources requiring unique names (either unique across a subscription or globally unique) are appropriately randomized so that no matter how many students launch the lab, their deployments will all succeed. This requires using Resource Template functions and/or replacement tokens in the Resource Template. Refer to details in the Recommendations and Best Practices section, below, for guidance on name randomization.

8. Test deployment of your updated Resource Template, into a new, empty RG in the same fashion that you did in 6. Ensure that all resources are created in the same region as your RG. Once it is working, delete the RG and its contents.

9. Either copy your template directly into a new Skillable Studio Cloud Resource Template or save it into an external repository (GitHub, etc.) and copy the link into the new Skillable Studio Cloud Resource Template. If you save it externally you will need a link that allows anyone to access the raw template file (possible even in GitHub private repos).

10. Reference the Skillable Studio Cloud Resource Template in your Cloud Slice lab.

11. Launch the lab, and make sure everything from the template is deployed the way you want. If not, return to step 8, resolve your config issues, then continue with steps 9, 10, etc.

12. Now launch the lab twice, as two separate users, and make sure that both labs launch successfully. This verifies that resource naming is properly configured. This must be done in a Cloud Subscription Pool containing a single subscription. If the first launch succeeds but you get errors on deployment of the second launch, they are most likely due to name conflicts. Return to step 8 and resolve those, then continue with steps 9, 10, etc. Otherwise, if both launches succeeded, then your template is properly configured.

Valid Resource Template

Any valid Azure Resource Template can be used as the basis for a Cloud Slice, provide it meets the following criteria.

1. Supports Resource Group Only Deployment – Cloud slice users do not have subscription level access. A supported Resource Template must deploy in its entirety in a single resource group and have no dependencies outside the resource group.

2. Does not depend on other templates – All templates are deployed concurrently. Deployment is not ordered or sequenced. For a lab to be considered deployed, all templates must successfully deploy. Any dependent resources should be contained within a single template.

3. Ensure only relative reference ID's are included – Templates generated from deployed Azure resources can contain fixed references to resources in subscriptions. These must be removed or generalized prior to deployment to ensure the template does not contain dependencies on objects that may not exist in the subscription targeted for deployment.

Recommendations and Best Practices

1. Create a single resource group in Azure and then use the automation script to preview the Resource Template for the resource group. Export and modify as needed using the procedure outlined above.

2. Avoid referencing templates from public repositories that you do not control. These templates may change without notice and break your lab.

3. Replace all references to a specific region with [resourcegroup().location]. This enables you to control the region of your deployment with the cloud slice configuration, instead of the template and allows the same template to be used in multiple regions at the same time.

4. For any object requiring a unique name, use "[concat(',uniquestring(resourceGroup().name)]" where  is some value relevant to your lab, such as Linux Lab.

5. Do not hard-code usernames and passwords in the template, instead use template parameters such as adminUsername and adminPassword to enable credentials to be set at lab design time, and allow different labs using the same template.

6. To assign random passwords, use the @lab.CloudPortalCredential().Password replacement token in the adminPassword parameter. If a resource such as a VM or a database requires a longer password, pad the Cloud Credential Password with additional characters, for example: "[concat('p5wD', parameters('adminPassword')]". Another option is to combine replacement tokens such as @lab.LabInstance.Id and @lab.CloudPortalCredential().Password. This will prevent two users doing the same lab from having access to each other's resources.

7. For user accessible names such as DNS names of resources, or other public names, include a template parameter for the name instead of generating a unique string. When the template is attached to a lab, use a lab replacement tokens such as the @lab.LabInstance.Id combined with @lab.User.FirstName to create user friendly names that can be also inserted into the lab document using the same replacement token.

8. If the template is generated from a deployed Azure resource group, remove all embedded comments to improve readability of the template.

9. If the lab template deploys virtual machines, the sizing of the virtual machine should be captured in a template parameter. This enables sizing information to be easily changed if the deployment region changes, and the currently configured size is not available in the new region.

10. For Linux VM's, use password authentication, by setting disablePasswordAuthentication to false in the Linux Configuration section under OSProfile in your Resource Template. For example, once properly configured your OSProfile section may look something like this:

    "osProfile": {
      "computerName": "[parameters('vmName')]",
      "adminUsername": "[parameters('adminUsername')]",
      "adminPassword": "[parameters('adminPassword']",
      "linuxConfiguration": {
        "disablePasswordAuthentication": false
      },
      "secrets": []
    },
    

11. Avoid the use of the parameter type "securestring" during development as it hides the passed parameter value when troubleshooting. If warranted, change "string" to "securestring" once deployment is tested and verified.

Storage Options for Resource Template

Templates can be stored natively in Skillable Studio, or can be stored on an external document repository such as GitHub. If templates are stored on an external repository, that repository must support anonymous access for Skillable Studio to read the template correctly.

Resource Template Load Testing

If your template will be used for a high volume of concurrent users such as large events or conferences, please contact us at https://skill.info/support for assistance. if you are not already working with Skillable event staff.

Please be prepared with the following items for successful load testing:

1. A "Launch" template.

   1. This is the template users will have at lab launch. This is necessary to ensure labs will launch successfully at scale and users will be able to enter the environment.

   2. Not all environments will launch with a template, if users are intended to start with no resources please outline this and continue to the next item.

2. A "Completed" template.

   1. This is a template of what users will have by the end of the lab. This is necessary to ensure proper scaling is configured on the subscriptions and that users will not experience issues throughout the lab.

3. A list of "Additional Resources".

   1. This is a list of any components created in the lab that cannot be deployed via Resource Template. This will not be a common thing, but may come up from time to time.

   This is some text url more text

   this is some text url more text