Starting with the Template
Level - Beginner
What will this article cover?
ARM Template basics, references and definitions
Basic ARM Template that will deploy a resource group
GITHUB reference to the Template
Part 2 will cover the deployment with Azure DevOps
Software Requirements
Visual Studio Code: Visual Studio Code is free to use and comes with a wealth of tools and extensions to help you create phenomenal templates.
Visual Studio Extensions
JSON Formatter(this option is already part of Visual Studio Code)
When starting with ARM templates it can be overwhelming. When I first starting working with Templates, I had no idea where to begin. I was confused about the syntax. I was unsure about all the functionality available when assembling a template. The point of this post is to be a simple and straight forward approach to a very basic template that will deploy the basic object in Azure; the Resource Group.
What is an ARM Template? Here is a simple explanation by Microsoft.
"The template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. "
What is a Resource Group? Here is the current definition from Microsoft.
"A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. You decide how you want to allocate resources to resource groups based on what makes the most sense for your organization. Generally, add resources that share the same lifecycle to the same resource group so you can easily deploy, update, and delete them as a group.
The resource group stores metadata about the resources. Therefore, when you specify a location for the resource group, you are specifying where that metadata is stored. For compliance reasons, you may need to ensure that your data is stored in a particular region."
Below is the basic flow we will follow.
From the JSON ARM Template -> Azure Devops -> Azure Resource Manger in Azure.
We will be discussing the JSON ARM Template.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "",
"apiProfile": "",
"parameters": { },
"variables": { },
"functions": [ ],
"resources": [ ],
"outputs": { }
}Our final template can be found here. Also see the finished Template below. This will be the template we will use in our deployment. But we will use the rest of this article to define each section of our final template.
We will break this template down into a discussion further down in the article. However, this is final view of our Template; very simple and straight to the point.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"ResourceGroupName": {
"type": "string",
"metadata": {
"description": "The Resource Group Name."
}
},
"Location": {
"type": "string",
"metadata": {
"description": "The Location for the Resource Group."
}
}
},
"variables": {},
"resources":
[
{
"name": "[parameters('ResourceGroupName')]",
"type": "Microsoft.Resources/resourceGroups",
"apiVersion": "2018-05-01",
"location": "[parameters('Location')]",
"properties": {},
"tags": {}
}
],
"outputs": {}
}We will be covering each one of the elements below:
"$schema": "contentVersion": "", "apiProfile": "", "parameters": { }, "variables": { }, "functions": [ ], "resources": [ ], "outputs": { }
$schema:
The thing that I find very interesting about this first line of the template is a URL to a schema file that is used in validation.
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"Our ARM Template Extension Azure Resource Manager Tools uses the deploymentTemplate.json file to validate our template structure and syntax as we create our deployment template. To see a formatted version of the JSON file visit my repository link here. At the time of this writing the schema api version is 2019-04-01.
contentVersion:
The next line of the file is the contentVersion and can be used by you or your team to control versioning of your templates to insure proper usage within your organization.
"contentVersion": "Your Versioning"parameters:
"parameters": {
"ResourceGroupName": {
"type": "string",
"metadata": {
"description": "The Resource Group Name."
}
},
"Location": {
"type": "string",
"metadata": {
"description": "The Location for the Resource Group."
}
}
}The parameters element in an ARM Template is not required. But I can't imagine having a reusable template without having some parameters. Even in our most simple example we are using two parameters, as you can see above. The parameters section is flexible and you can define many types of parameters to be passed and used in your ARM Templates.
Our Parameters and the relationship they have to the schema.
ResourceGroupName: This is our specific parameter name. You will define your own naming convention to name your Parameters.
Type: this is the type of the parameter we are expecting. In our instance, it we are expecting a string.
Metadata: This is a very useful element of the Parameter Schema because it provides you information about the Parameter.
In our example we are using two parameters that we have defined (ResourceGroupName, and Location).
variables:
"variables": {}The variables elemet in an ARM Template are not required either. But this will allow you to provide a centralized place for reusable values that you may use with your template. We are not using variables in this Template. You can find more information here.
functions:
"functions": [ ]The functions element in an ARM Template is not required either. You can also call this User Defined Functions. Functions are handy to use when you need to perform some logical operations in your template. However, there are limitations of the User Defined Functions. We are not using this element in our Template. You can find more information here.
resources:
This is the important element of interest in our example. Let's break it down to make it more understandable.
"resources":
//Notice the resources element body is an array []
[
//our one and only resource, array element 0
{
//The name is our choice and will be a parameter that we will
//pass into our template when we setup our
//deployment in Azure DevOps
"name": "[parameters('ResourceGroupName')]",
//This is an important part, the Type. The Type is a definition
//found here. More on this below
"type": "Microsoft.Resources/resourceGroups",
//The apiVersion is the version of Type we mentioned above
//Again, more on this below
"apiVersion": "2018-05-01",
//The location is another parameter we will pass in but it can
//only be from a list of pre-defined values. Our US values are
//at this site - US List of Locations.
"location": "[parameters('Location')]",
//The properties element is used to set specific properties
//of the current element. In our example the current element
//is a Resource Group definition. We will not be setting any
//Resource Group specific properties at this time
"properties": {},
//The tags element is also handy for grouping Azure Resources
//but we will not be defining any tags in this example
"tags": {}
}
]The Resources Element in an ARM Template is what we are going to use to define the Resources that we are going deploy. We are going to be deploying a Resource Group which is a type. Keep in mind, that we are deploying a specific type called Resource Group. Do not get this confused with the Resources Element. The Resources Element is used to deploy many different types. The Resource Group is just one of those types that can be deployed. You can find more information about the Resource Element here.
Keeping it simple, we are going to define one Resource in our Resources Element. Notice that the resource's element body is an array [], we only have one array element at this point. But as you can see many Resources can be defined in an ARM Template. Again, we are keeping this simple and only defining one.
So what is a Type?
Simply put, a Type represents an Object that you are using in your Template during the deployment phase. It can be confusing, especially when trying to determine the Types available to you for use in your Templates. You can look here for Microsoft's explanation. However, I like to just keep it simple.
// our array of resources with only one item to be deployed
// Our Resource Group
[
{
"name": "[parameters('ResourceGroupName')]",
"type": "Microsoft.Resources/resourceGroups",
"apiVersion": "2018-05-01",
"location": "[parameters('Location')]",
"properties": {},
"tags": {}
}
]
Remember, in our example we have defined our type for our deployment to be a Resource Group. Also remember, we only have one Resource Array element in our array (See Above). But notice the type definition in our one and only Resource array element. The type looks like a path. This can be confusing for .NET Developers because we are so used to using Dot Notation for our Namespaces and Types. Just note that types are defined this way as they are used in REST API calls. This can be confusing for those just starting ARM.
"type": "Microsoft.Resources/resourceGroups"Another important thing to notice is the apiVersion . For every type you use, there is a corresponding version number. This is important because of schema and functionality differences you may encounter between versions of Types and the APIs.
"apiVersion": "2018-05-01"When going to the Microsoft Reference for any type you are using, you can select API versions from a list as shown below. This can help you to chose the most appropriate API version for your current project. But note, new API versions do not always mean that all functionality is available or even better. Many times, using a new API version can cause problems for other segments of your Template. But that is beyond our scope of discussion. Just remember, newer does not always equate to better. In our example, we are using the older version of the API version 2018-05-01.
Finally we are at last element of discussion.
outputs:
"outputs": {}Outputs are not required, but are handy as well. When you need values returned from an ARM Template deployment, you will do this through the use of the outputs element. We do not have any outputs in this example. Again, we are keeping it simple, but if you want more information you can go here.
Part 2 of our discussion will be using this Template with an Azure DevOps account and a simple Release Pipeline.
Helpful Links
Yorumlar