In the last days, I dealt a lot with GitHub Actions to find out, how it can be used to deploy Azure ARM templates to the cloud. My last „evolution“ step now – I was working on this because of the very valuable hint of a collegue – is able to deploy ARM templates to all 4 available scope levels:

• Tenant level
• Management Group level
• Subscription level
• Resource Group level

And it also could be used, even when you don’t use GitHub Actions! But let’s start from the beginning…

A brief history of evolution

In my first appraoch, I have used a simple PowerShell script (based on a Script by Sarah Lean, https://gist.github.com/weeyin83/81e7a7bf3caf3d0bce787db5d562b47e) to just deploy something to Azure using GitHub Actions. This is fast & simple, but not very flexible.

My second approach took me to the new Azure PowerShell Action, where you can just run PowerShell code from within the GitHub Action:

https://github.com/HaikoHertes/ActionsDemo/blob/master/.github/workflows/DeployARMtoAzure.yml

So I used some small code to deploy an ARM template with its parameters file that both reside in an GitHub repo. This is even more easy to use, but still not very flexible, especially, when it comes to multiple ARM templates.

You can still find the code and stuff here:
https://github.com/HaikoHertes/ActionsDemo

Next step was to deploy just a bunch of Templates with their parameters from a repository to become more flexible. Here I wrote a PowerShell script that does the main work:
https://github.com/HaikoHertes/ActionsDemo.v2/blob/master/DeployARMtoAzure.ps1
This script is then just called from within the GitHub Action:

https://github.com/HaikoHertes/ActionsDemo.v2/blob/master/.github/workflows/DeployARMtoAzure.yml#L27

This allready does a good job, so you can fetch everything from here:
https://github.com/HaikoHertes/ActionsDemo.v2

The final solution

But then, a colleague of mine gave me an hint on some new options to not just deploy to Resource Group level, but to higher levels as well. And so I spent a day to investigate and re-write my PowerShell script. And now I can offer a script, that does the job! Let me show you…

You can pick up the script from here:
https://github.com/HaikoHertes/ActionsDemo.v3/blob/master/DeployARMtoAzure.ps1

How the script works

As it is a little more complex, I want to explain what it does and how it works. The script is divided into 5 major parts:

• Setting the variables and defining the functions
• Deploying to Tenant level
• Deploying to Management Group level
• Deploying to Subscription level
• Deploying to Resource Group level

If there are no templates for one of these levels or if their folder does not exist, it will just be skipped.

The script expects a defined folder structure:

The names of folders and files can be adjusted in the PowerShell Script:

After all the variables are set, two functions are declared: GetLocation and GetScop. They are made to fetch the location / region from a given directory’s location file or return the default location and to fetch the scope of the deployment either from a scope file or the folder name. Both functions will be used in the later deployments. All files allow the usage of comments that start with the hashtag symbol ‚#‘.

The 4 major parts for the different deployment levels are mostly very similar just with slight differences, thats why I just explain how any of them works.

They first grab all JSON files, that are not in the naming format *parameters.json in any subdirectory (so you can organize your templates by topic or something else and group them into folders). If an order file is given, it will fetch the sorting order from the file (allowing sorting by foldername and filename (default) or filename-only) or just sort by the default order. That way, you can define a deployment order by using proper names for your templates.

Now it will run through the list of templates, getting the scope and location of that templates folder, fetching the tags if any given and then trigger the deployment with any of these Cmdlets, whatever is sufficient for the scope / level:

• New-AzTenantDeployment
• New-AzManagementGroupDeployment
• New-AzSubscriptionDeployment
• New-AzResourceGroupDeployment

For a given template ABC.json , it allways expects a ABC.parameters.json file next to the template with the parameters. If no parameters are needed, just provide an empty file.

At the end, all templates in all of the 4 levels are deployed

How to use the script

The script was made to be used with GitHub Actions:

Here it is just called after repo checkout and Azure login. You can get the stuff from here:
https://github.com/HaikoHertes/ActionsDemo.v3/blob/master/.github/workflows/DeployARMtoAzure.yml
https://github.com/HaikoHertes/ActionsDemo.v3

It expects the ARM templates in a subfolder „arm“ within the same repo where the GitHub Action resides.

Be aware that as of today, you need to use ubuntu-20.04 and AzPS 4.1.0 (This is needed for the latest version of the deployment Cmdlets above, and AzPS 4.1.0 is only included in the ubuntu-20.04 container image used by GitHub Actions.

The other option would be to use the script without GitHub Actions and even without any repository. You could just run it locally with a given local folder structure containing the templates and other files. You would just need to add something like

Connect-AzAccount

to do the login. Be aware that you still need Az PS Module version 4.1.0 or higher, which you can install with

Install-Module -Name Az -AllowClobber -MinimumVersion 4.1.0

Setting the proper rights on Azure

To be able to deploy to Azure, you need a user with proper rights. Especially when using GitHub Actions, it is not recommended to use a regular named user, but service principals. In my video (German language, but it shows eveything on english UI) on YouTube, you can see how to do this:

You will need something like this:

az ad sp create-for-rbac –name „github“ –role contributor –scopes /subscriptions/YOUR_SUB_ID –sdk-auth

To be able to deploy to Tenant level, you will need the proper rights on root level. Some types of template also need owner rights, especially wheny you want to deploy role assignments or such. Either adjust the above command or (especially, when the user allready exists), extend the rights with somthing like this:

az role assignment create –role „Owner“ –assignee „[USERID]“ –scope „/“

About the different files that can be used

There is several files that can be used to control how the script works:

arm/DefaultLocation.txt

This file defines the default location for any deployment, that needs a location to be set outside the ARM template. It also includes a list of all available location names. Treat this file as mandatory.

arm/ANY_LEVEL/order.txt

This file defines the sorting order and therefor the deployment order within that given level. There is two options:

• SortByFolderName = Sorting by foldernames and then by filenames (default)
• SortByFileName = Folder names are ignored, sorting just by templates filenames

The file is optional; if no order is given through a file, the default order will be by foldername first and then by templates filename.

scope.txt next to any template JSON

By default, the deployment scope (i.e. Subscription ID) is fetched from the templates folder ANY_DEPLOYMENT. If needed (i.e. when you want to deploy multiple folders as seperate groups, but into the same scop), you can provide a scope.txt file instead. In here, give ID or name of the scope, both would work.

tags.txt next to any template JSON

You can provide a tags.txt file with the content like

KEY = VALUE

pairs to set tags right on the deployment.

location.txt next to any template JSON

Next to a template file, you can provide a location.txt file that will set the location for the deployment, if needed. If the template itself sets a location, then templates location will be used. If neither template nor location.txt provide a location, but one is needed, the defaultLocation will be used.

(The names are given as they would be with the parameters I provide with my script; they can be changed)

Copyright / legal notice

Copyright 2020 Haiko Hertes

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the „Software“), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED „AS IS“, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Nun kam von einem meiner geschätzten Kollegen zu Recht die Frage, wie man denn in dieser (ersten, im Video gezeigten) Variante mehrere ARM Templates bereitstellen kann. Und dazu möchte ich hier die passende Antwort liefern…

Eine Variante wäre sicherlich, in diesem Skript

https://github.com/HaikoHertes/ActionsDemo/blob/master/.github/workflows/DeployARMtoAzure.yml#L23

mehrfach das „az deployment group create“ aufzurufen – aber dann müssten man wissen, wie viele Templates es sind und das Skript würde auch schnell sehr lang.

Als aus meiner Sicht bessere Lösung habe ich ein PowerShell Skript geschrieben, dass in der Verzeichnisstruktur des Repositories einen Ordner „arm\“ erwartet und darin Unterordner mit den Namen der gewünschten Resource Groups. Diese werden falls nötig vom Skript angelegt. Außerdem sucht das Skript Templates im Format XYZ.json und dazugehörige Parameter-Files im Format XYZ.parameters.json. Diese Templates werden nun alphabetisch geordnet mittels ARM bereitgestellt – egal, wie viele es sind. Dabei werden aus einer Datei „tags.txt“ falls gewünscht die Tages im Format

Tag = Wert

geladen und bei der Bereitstellung der RGs und Ressourcen mit angewendet. Die zu verwendende Location (nur eine pro RG ist erlaubt, aber das entspricht weitgehend dem üblichen Vorgehen) wird ebenfalls aus einer TXT-Datei location.txt gelesen.

Im GitHub Repo müssen zwei Secrets hinterlegt werden:

Einmal ein Secret für die Credentials (wie man die anlegt zeige ich im Video ab 20:27) und einmal die Subscription ID der zu verwendenden Subscription. Ergo ist ein Repo pro Subscription nötig…

Das PowerShell Script selbst könnt ihr hier herunterladen:

https://github.com/HaikoHertes/ActionsDemo.v2/blob/master/DeployARMtoAzure.ps1

Alternativ könnt ihr gleich mein ganzes Demo Repo auf GitHub clonen:

https://github.com/HaikoHertes/ActionsDemo.v2 bzw
https://github.com/HaikoHertes/ActionsDemo.v2.git

Wichtig: Damit mit -Tag bzw. -Tags auch die tags gleich mit bereitgestellt werden können braucht man das Az Modul in Version 4.1.0 und das wiederum ist derzeit nur im Ubuntu-20.04 Image auf GitHub enthalten. Siehe dazu auch hier:

https://github.com/marketplace/actions/azure-powershell-action
https://github.com/actions/virtual-environments/blob/master/images/linux/Ubuntu2004-README.md
https://github.com/actions/virtual-environments/tree/master/images