Checklist for Toolset Updates

Initial Setup

This is a one-time process on your development machine:

1. Install PowerShell 7.x. This installs pwsh.exe.
2. Install Azure PowerShell.
   • To install:

     Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

   • To sign in:

     Connect-AzAccount

   • To check the installed versions of Azure PowerShell:

     Get-InstalledModule -Name Az -AllVersions | Select-Object -Property Name, Version

   • To update Azure PowerShell:

     Update-Module -Name Az -Scope CurrentUser

3. Install Azure CLI. Then in PowerShell, in the azure-devops directory:

   • az login

   • az account set --subscription CPP_STL_GitHub

   • Normally, you should skip this bullet point. Click to expand if the Resource Group and Storage Account for diagnostic logging need to be recreated.

     • az group create --location westus2 --name StlVmssDiagLogsRG

     • az storage account create --name stlvmssdiaglogssa --resource-group StlVmssDiagLogsRG --location westus2 --sku Standard_LRS --kind StorageV2 --access-tier Cool

   • az vmss diagnostics get-default-config --is-windows-os > vmss-config.json

   • Print your SAS token, which is a long string:

     az storage account generate-sas --account-name stlvmssdiaglogssa --expiry (Get-Date -AsUTC).AddYears(1).ToString("yyyy-MM-ddTHH:mmZ") --permissions acdlpruw --resource-types sco --services bfqt --output tsv

   • Create vmss-protected.json containing:

     {
         "storageAccountName": "stlvmssdiaglogssa",
         "storageAccountSasToken": "__SAS_TOKEN_WITH_LEADING_QUESTION_MARK__"
     }

   • As the placeholder indicates, replace it with a question mark ? followed by your SAS token. It should look like this:

     {
         "storageAccountName": "stlvmssdiaglogssa",
         "storageAccountSasToken": "?long-secret-string"
     }

Toolset Update

1. Create a new branch in your own fork.
2. Edit $/azure-devops/create-vmss.ps1 and $/azure-devops/provision-image.ps1 to make the changes/updates you want to make. Most changes will be merely updating version numbers which happens in provision-image.ps1.
   • Check Azure VM spot pricing and the internal price list.
   • To find new SKUs:

     az vm image list-skus --location westus2 --publisher MicrosoftWindowsDesktop --offer windows-11

   • To compare Windows 11 update history with the latest available version:

     Get-AzVMImage -Location westus2 -PublisherName MicrosoftWindowsDesktop -Offer windows-11 -Skus win11-21h2-ent

3. Run $/azure-devops/create-vmss.ps1. This should take approximately 25 minutes.
4. On https://dev.azure.com/vclibs/STL/_settings/agentqueues, add a new Azure virtual machine scale set pool pointing to the scale set generated in the previous step.
   • Give the pool the same name as the generated resource group to make them easy to find.
   • Give the pool a description (including the toolset version) to make it easier to distinguish different pools.
   • Choose a maximum number of 64 machines with 0 standby machines. (This leaves enough room to create one more VM for this update process. 64 VMs * 32 cores each + 1 VM with 32 cores = 2080 cores total, less than our 2624 core quota.)
   • Set the "delay before deleting excess idle agents" to 1 minute.
   • Check the checkbox that says "Grant access permission to all pipelines".
5. Update $/azure-pipelines.yml to point to the new pool.
6. Update $/README.md to mention any new toolset/dependency versions.
7. Create/update a PR from your branch to microsoft/STL. If there are substantial code review changes, delete the created pool from https://dev.azure.com/vclibs/_settings/agentpools, delete the resource group from the Azure portal, make the code review requested changes, and restart from step 3.
8. After your PR merges, delete the old unused pool from https://dev.azure.com/vclibs/_settings/agentpools, and the previous resource group from the Azure portal.

Resource Groups

1. Go to https://portal.azure.com
2. Click Subscriptions
3. Click CPP_STL_GitHub
   • If you don't see that at first:
   • Check "Show only subscriptions selected in the global subscriptions filter"
   • Click "global subscriptions filter"
   • Select CPP_STL_GitHub
4. Left column > Settings > click Resource groups