On any project involving Azure resources, especially if the project needs to be deployed multiple times, for say, DEV, then TEST, then UAT, then PROD, I always aim for automating as much of the process as reasonably possible, ideally all of it. Automating the process also allows you to do deployments from Continuous Deployment pipelines and know that it’ll be done the same way every time.

Azure has a heaps of tools available for automating operations but it can be confusing to get started. What tools are available? Which should I use? Where’s the documentation? I want to create resource X, what options do I need to pass? etc etc.

In this post, I’ll help to demystify the tools that are available, and try and plug some of the gaps between the “do it in the portal” tutorial docs that Microsoft like to write and the “but how do I do this with tool Y?” questions that I so often had trouble with.

I’m only going to focus on the Microsoft-provided tools, so I won’t be covering third party tools like Pulumi or Terraform in this post.

(This post has loads of links and screenshots, so link-rot will be a thing. If you find anything seriously broken or out of date, let me know @TonesAttwood)

What’s available?

• REST API
• Az CLI
• Az PowerShell
• ARM templates
• REST API client libraries

REST API

https://docs.microsoft.com/rest/api/azure/

Pretty much everything Azure is done via the REST API. All the other tooling you’ll see below is basically a convenience wrapper around Azure REST API calls.

Occasionally you might find yourself referring to the REST API docs to figure out what parameters an operation requires if the tool-specific docs aren’t detailed enough.

Since the REST API is the canonical API layer for doing Azure operations, you’ll find that the other tool options tend to be pretty similar to the REST API.

Az CLI

https://docs.microsoft.com/cli/azure/

The Az CLI is a CLI tool that gives az {resource-type} {sub-resource-type} {operation} {arguments} semantics for doing operations, so you can use your shell of choice for scripting things up.

Az CLI is cross platform and available on every major OS. You can use it in pretty much any kind of script, Bash, PowerShell, Windows Batch, etc.

Az PowerShell module

https://docs.microsoft.com/powershell/azure/

The Az PowerShell module is a set of PowerShell cmdlets for doing Azure operations with PowerShell-idiomatic names like {Verb}-Az{ResourceType} -Argument Value.

The Az PowerShell module is the current PowerShell offering. It’s compatible with PowerShell 5.1 for Windows only and PowerShell Core 6.x for all OS’s where PowerShell Core is a thing (which is all of them).

AzureRM vs Az

You’ll see older tutorials and guides online refer to the AzureRM PowerShell module. AzureRM was renamed to Az when it was rewritten to target PowerShell Core. Generally (but not always), anywhere you see a cmdlet used that’s called {Verb}-AzureRm{ResourceType}, you can replace it with {Verb}-Az{ResourceType}. For example, New-AzureRmResourceGroupDeployment becomes New-AzResourceGroupDeployment.

The short version is, don’t use AzureRM. If you’re doing new work, use Az, and if you’re maintaining existing AzureRM-based scripts, seriously consider updating to Az.

The Az introduction page has a good overview of the why what and how of Az vs AzureRM.

AzureAD

If you’ve used the AzureAD module in the past, you might find you can it ignore it now. It doesn’t support PowerShell Core, and it’s functionality is being gradually ported into the Az CLI (docs) and Az PowerShell module (docs).

Azure Resource Manager (ARM) templates

https://docs.microsoft.com/azure/azure-resource-manager/

Azure Resource Manager (ARM) templates are a different kind of beastie to Az CLI, Az PowerShell, or the REST API. ARM is a declarative ‘desired state’ approach to Azure infrastructure. You use ARM templates to declare what resources you need and how they should be configured, and let the ARM execution engine figure out what mutation operations it needs to do. If you’ve done AWS infrastructure, you’ll see that this is fundamentally similar to AWS CloudFormation.

REST API Client Libraries

I’ve put this one last, because it doesn’t necessarily fit the scripting approach to infrastructure automation, but if, for instance, Python is your thing, then just ignore me 😁

https://docs.microsoft.com/rest/api/azure/

Alongside the REST API, Microsoft also publish thin wrapper libraries for a variety of programming languages, including .NET, Java, Node.js, and Python

Which one should I use?

When you’re automating Azure infrastructure, any of the tools above will do a similar job, since they are all wrappers (with varying levels of thin-ness) around the REST API. But there’s still a few questions you can ask yourself.

As a general rule;

• For declarative templating, use ARM templates, regardless of your choice of shell or programming environment,

• For imperative scripting,

  • If you’re into PowerShell, use the Az PowerShell module
  • If you’re not into PowerShell, or if you’re using a shell that’s not PowerShell, then use Az CLI. (You can still use the Az CLI from a PowerShell shell if you don’t like using PowerShell-style cmdlets)

There are a few gotchyas though;

• These tools are all maintained by different teams, so you’ll sometimes be able to do something with one tool but not another. For example, it’s not uncommon for ARM support for a resource type to be incomplete, and you then have to use, say, PowerShell or CLI to do an operation after an ARM template deployment.
• If you’re on the bleeding edge, say, using a feature that’s still in preview, it might not be supported in your tool of choice and you’ll have to use the REST API directly (with cURL, or Invoke-WebRequest or similar).
• Beware the versions of the tools you have access to in your execution environment. For instance, if your scripts will get executed on a specific version of Windows, or where there’s only specific versions of PowerShell or the Az CLI available, you may have a limited set of tools available.

I typically mix-and-match the tools depending on the operations I need to do; I’ll use ARM templates as re-usable components from project to project, PowerShell Az module for things that you can’t do with ARM (or where the Az cmdlet is substantially easier than ARM), and occasionally use the Az CLI where it’s easier than either Az PowerShell or ARM.

Where’s the docs?

You’ll find links to the top-level page for each tool in the sections above, but that’s not usually the material you’ll refer to on a regular basis.

I find that the Azure docs do a great job at walking you through using the Azure Portal to do a task, but fall short in pointing you to the reference material you need to be able to automate it. For instance, if I’m writing an ARM template and I want to deploy a storage account, how do I know what the ARM resource block looks like or what properties I can pass?

REST API resources and operations

The REST API is probably the easiest. There’s very little else in the documentation except the resource-specific details.

https://docs.microsoft.com/rest/api/azure/

Want to do something with a specific resource type? Find it in the list and expand the node.

Want to create (or update) an Application Gateway? It’s right there. Expand the node and get all the details available for how to call it, what options there are, etc.

Az CLI resources and operations

The Az CLI is a little harder to find. If you go the front page for the CLI, it’s not obvious where the list of functions and operations are, but scroll down, it’s there.

https://docs.microsoft.com/cli/azure/

Expand the Reference node, and you’ll see all the commands and resource types. In fact, forget the front page, just bookmark the reference index page;

https://docs.microsoft.com/cli/azure/reference-index

Az PowerShell resources and operations

Like the Az CLI, the cmdlet reference for the Az PowerShell module is tucked away at the bottom of the page.

https://docs.microsoft.com/powershell/azure/

Expand the Reference node and you get the references for all the resource types. Unfortunately there’s no easy bookmarkable URL for this one, the Reference node is not a link and not bookmarkable 😑 (at least, at the time of writing this post).

Like the Az CLI and Az PowerShell module, the ARM documentation has the useful bits tucked away and hard to find, only more tucked away and harder to find.

From the main page, expand the Reference node;

• The resource provider listing is Template reference,
• The template functions you can use in your templates is Template functions, and,
• when you’re having trouble figuring out which resource provider matches to the resource type you want, Resource providers by service can help.

Amusingly, the Reference link (the reference material for the available resource providers) opens up in its own page, this one is definitely work bookmarking.

https://docs.microsoft.com/azure/templates/

The listing of template functions is often handy too.

https://docs.microsoft.com/azure/azure-resource-manager/resource-group-template-functions

All the links!

And lastly, in once handy place, the Microsoft Docs links you should bookmark;

• REST API

  • Main page (and the only one worth bookmarking) - https://docs.microsoft.com/rest/api/azure/

• Az CLI

  • Command reference - https://docs.microsoft.com/cli/azure/reference-index

• Az PowerShell module

  • Main page (the cmdlet reference isn’t its own link, just remember to look for the Reference node at the bottom of the nav) - https://docs.microsoft.com/powershell/azure/
  • AzureRM if you ever need it - https://docs.microsoft.com/powershell/azure/azurerm/overview
  • AzureAD if you ever need it - https://docs.microsoft.com/powershell/module/azuread/

• ARM templates

  • Main page - https://docs.microsoft.com/azure/azure-resource-manager/
  • Resource provider reference - https://docs.microsoft.com/azure/templates/
  • Template functions reference - https://docs.microsoft.com/azure/azure-resource-manager/resource-group-template-functions
  • Resource providers by service - https://docs.microsoft.com/azure/azure-resource-manager/azure-services-resource-providers

 

Happy Automating!