Understanding the Structure of an Azure JSON File

json-hero
In this post, I will introduce you to the syntax of an Azure JSON (JavaScript Object Notation) file, a template that you can use to quickly deploy a repeatable solution in Microsoft Azure.

JSON Templates

Azure Resource Manager (ARM) enables operators, developers, and administrators to quickly deploy “infrastructure as code” to Microsoft Azure; this means that you can describe a deployment (IaaS and/or PaaS) of an Azure solution and push that template out. The template effectively becomes a cookie cutter, giving you the exact same (with some pre-defined changes, which I’ll get to later) deployment every time. So if I need to deploy the same solution to lots of small businesses, or deploy test, dev, and production systems, a JSON template enables me to do that with minimal effort – either a few mouse clicks or running a small PowerShell script, either of which only take seconds, while I go off and do something else.

Not only am I saving time that I can reuse elsewhere but I’m also getting the same error-free result every time I deploy the template, but JSON allows for greater control (I like naming virtual machine NICs after the virtual machine that uses the NIC) and the deployment is faster than what I can do by hand or even by using PowerShell!

Basic Structure of a JSON File

At first glimpse (have a look in Automation in any Azure resource group where you’ve deployed resources) a JSON file looks scary to us IT pros; it’s like XML (I was rebuked by a developer once for saying that) … it’s all braces, brackets, indentation, and commas. But there is a structure, and the basics of that structure are simple enough to grasp and illustrate the power of JSON.
The following excerpt is a simple blank example of a JSON file:

{
"$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {},
"Variables": {},
"resources": []
}

The syntax and content structure of a JSON file is controlled by a schema which is defined by the $schema variable.
There are 3 sections within a JSON file:

  • Parameters
  • Variables
  • Resources

JSON Parameters

When you deploy anything via the Azure Portal, you are asked a bunch of questions. These are parameters that are used to feed customer requirements into a deployment, such as the name of a virtual machine, spec/size, the username and password, the network address of a virtual network, and so on.
We use parameters to ask for configuration data to customize the deployment. The below simple example shows how we can ask for a username and password for one or more virtual machines that a template will deploy:

"parameters":
    {
        "ServerAdminName":
            {
            "defaultValue": “myadmin”,
            "type": "string"
            },
        "ServerPassword":
            {
            "defaultValue": null,
            "type": "securestring"
            }
    },

When a template with the above is deployed, two fields (ServerAdminName and ServerPassword) will appear and request data entry to configure the deployment.
Note how the {} delimited definition of ServerAdminName is followed by a comma; this comma designates that another parameter will follow. The last parameter will not have a trailing comma.
Later, these parameters can be used to configure resources that are being deployed. An example reference would look like this:

"[parameters('ServerAdminName')]"

The other thing to note in the parameters is that you can supply a default value; think of this as a suggested configuration that can be overridden when deployed. The above examples allow a person to enter any value; you might want to limit choice and you can do this by creating a drop-down list box, as the following parameter example does, by limiting the spec/size of VM that can be chosen in a deployment:

        "ServerSKU":
            {
            "type": "string",
            "defaultValue": "Standard_A1_v2",
            "allowedValues":
                [
                "Standard_A1_v2",
                "Standard_A2_v2",
                "Standard_A4_v2"
                ]
            },

 

JSON Variables

When I first started to work with JSON files, I was amazed at how an exported template from a manual deployment turned every configuration into a parameter. You can hard-code these values in the Resources section, but that means that a change will require lots of edits. I prefer to write the value once in a central point (in Variables) and reuse the variable name, which infers the value.

The below example shows two variables being defined; once again, commas are used to separate the variables and the last variable doesn’t have a trailing comma.

    "variables":
        {
        "nsg_name": "nsg-deployment-sn01",
        "lb_pip_name": "pip-depoyment-lb"
        },

You can use a variable later in the JSON as follows:

"[variables(nsg_name)]"

Resources

This section is where all the magic happens, and where you will do most of your work. Here is where you describe your storage accounts, networks, NICs, virtual machines, load balancers, and so forth. Parameters and variables are used to customize each deployment. Each type of resource is described using the Microsoft Azure JSON schema (see above).
If you speak JSON (or want to), then you can spend the next few years figuring out the schema and write resources by hand. Personally, I prefer an old technique that scripters have perfected over the years: copy, paste, tweak, and take sole credit for the work!
I figure out resource syntax using the following two methods:

  • Deploy by hand: I’ll deploy a solution or a piece of one in a resource group using the Azure Portal and then export the JSON. I can find the resource and reuse the piece of JSON that describes it, with a little tweaking to use more variables and fewer parameters.
  • Look at other templates: There is a repository of community templates out there that you can find using a search engine, and there is a curated set of Azure Quickstart Templates on GitHub, which can be more easily searched and browsed on the Microsoft Azure site.

Return on Investment

I was quite skeptical about the value of JSON to IT pros, especially those of us working in the small-to-midsized enterprise (SME) space, but I’ve been won over. JSON is saving me countless hours of work and will soon allow my customers to avail of pre-configured solutions that they can deploy in minutes instead of hours/days … and I work in the sub-500 user market.

Yes, it will take you time to learn how to use JSON, but the return on investment will be better, more controlled, faster, and more consistent deployments that anyone can deploy without understanding the contents.