Introduction

When launching a new Azure Canary, your Canary Console generates a multi-line script for you to run. That script may look intimidating if you've not used the Azure CLI previously, so in this page we walk through the script line-by-line to explain what's happening.

Our script condenses this Azure help page into a series of commands. You can find more information on our Azure Canaries at this page, and if you've trying to resolve issues with this script we've got a troubleshooting page.

A quick refresher: before generating the script you were prompted for the Azure Resource Group Name, whether the Resource Group was new (or not), the new VM's name, and the region in which you want to launch the VM.

In our example below, these values are used:

MyResourceGroup (Resource Group Name)
Resource group does not exist
MyNewVM (New VM name)
East US (Region)

Azure-CLI

The script is designed to be run from a Linux shell which has azure-cli installed. The easiest approach is to rely on the Azure Cloud Shell's Linux interface. However you can also install the Azure CLI locally on a Linux machine. Our deployment script includes a link to the installation document for azure-cli, in the event you want to install it locally.

Would a PowerShell equivalent would be useful to you? Use the Green "?" on this page let us know!

Script sections

Create the Resource Group

If you answered "No" to whether the Resource Group existed, then a three lines are included to create a new Resource Group (with the name you chose), and assign the service principal created when you authorised the Canary App to use the Resource Group.

#
# Create the new Resource Group "MyResourceGroup".
#
az group create -l eastus -n MyResourceGroup
spObjId=$(az ad sp list --display-name 'ThinkstCanary-bigcorp.com' --query '[0].objectId' -o tsv)
az role assignment create --role Contributor -g MyResourceGroup --assignee-principal-type ServicePrincipal --assignee-object-id $spObjId

The first line creates the new Resource Group, MyResourceGroup. The second line grabs an identifier for the App's service principal, and the final line assigns the Contributor role to the Canary App for MyResourceGroup.

Login to the Shared Image Gallery

Cross-tenant sharing of VM Images on Azure relies on Shared Image Galleries combined with Apps. To access the images in the gallery, you login to both your own tenant and Thinkst's tenant, and grab access tokens in each tenant.

#
# Set up access to the Shared Image Gallery MyResourceGroup.
#
az account clear
az login --service-principal -u '7cedbf32-6a62-4604-aa31-4e7427463b11' -p 'b5984213-3e2c-41f3-817e-0d8154ea3a03' --tenant '2327d195-c08d-47ad-a7e5-f6e8c520dfd1'
az account get-access-token
az login --service-principal -u '7cedbf32-6a62-4604-aa31-4e7427463b11' -p 'b5984213-3e2c-41f3-817e-0d8154ea3a03' --tenant '68ca42a1-1d3b-4a1d-98c5-96235bd72a5c'
az account get-access-token

The first line clears anything current logins. The second line logs into the Thinkst tenant use the Canary App's credentials, and pulls an access token on the next line. The forth line logs into your own tenant using the Canary App's credentials, and pulls a new access token from your tenant.

Your Azure CLI now has access tokens for both your tenant and the Thinkst tenant.

Deploy the new VM

Lastly, you deploy the new VM from the CLI too.

Note: The Azure Portal web interface does not support deploying cross-tenant images, you need to use the CLI.

#
# Launch the new VM.
#
az vm create \
   --resource-group MyResourceGroup \
   --name MyNewVM \
   --image /subscriptions/079ea245-1cdc-41a0-b0bd-10e74648e6d6/resourceGroups/ThinkstCanary-bigcorp.com/providers/Microsoft.Compute/galleries/ThinkstCanary_bigcorp.com/images/AzureCanary-2.2.9-586e2e9 \
   --admin-username notused \
   --generate-ssh-keys \
   --location eastus

This line deploys the new VM with your chosen name into the Resource Group you provided, in the region you've chosen. The image path is generated for you, and points to a Shared Image Gallery managed by Thinkst.

The admin username is a required parameter in the Azure CLI but Canary will not make use of it. We insert "notused" as a placeholder. Similarly, we tell the tool to generate SSH keys, but these are not used by the Canary VM.

Wrapping up

This page explained the details of the Azure Canary launch script. If you'd like to know more about our Azure Canaries, find more information here.

Search

Explaining the Azure Canary launch script