Best practices
We want to take a quick look at some best practices to optimize ARM templates. But first, let's start by understanding what some of our template limits are.
Overall, the template can only be a maximum of 4 MB, and each parameter file is limited to 64 KB. You can only have 256 parameters, with 256 variables, containing 800 resources, 64 output values, and 24,576 characters in a template expression. As we've discussed, you can exceed some of these limits by using nested templates if your template gets too big, but Microsoft recommends that you use linked templates to help avoid these limits. In the following sections, we discuss some best practices for each component within an ARM template.
Parameters
The ARM template system within Azure DevOps resolves parameter values before deployment operations and allows you to reuse the template for different environments. It is essential to point out that each parameter must have a set data type value. You can find a list of these data types at https://docs.microsoft.com/azure/azure-resource-manager/templates/template-syntax#data-types.
Best practices
Microsoft recommends the following best practices for parameters:
- It's best to minimize the use of parameters. As we pointed out at the beginning of the chapter, you should use variables for properties and only use parameters for the things you need to input.
- It is recommended that you use camel casing for parameter names.
- It is also recommended that you describe each parameter, so when other developers use the template they know what the parameters are.
- Ensure that you use parameters for those settings that may change when the environment changes, such as capacity or app service names.
- Ensure you name your parameters to make them easily identifiable.
- Provide default values for parameters; this involves providing the smallest virtual machine skew size so non-production environments use smaller resources and other developers that use the template have a basic starting point.
- If you need to specify optional parameters, avoid using empty strings as the default value and instead use a literal value. This helps to provide a naming structure for users of the template.
- Try to use allowed values as little as possible, as these may change over time and can become difficult to update in your scripts.
- Always use parameters for usernames and passwords or secrets to be set for each environment and not hardcoded in the template. You should also use a secure string for all passwords and secrets.
- When you need to set a location for the resource you're deploying, set the default value to
resourcegroup().locationso the location value is set correctly within the resource group.
As you can see, parameters are very useful in the ARM template process because they allow us to be flexible with the environments we're trying to deploy. Remember to keep these templates as simple as possible with the applications or microservices you're trying to deploy.
Variables
Variables are also resolved before starting the deployment, and the resource manager replaces the variable with its determined value. Variables are useful in deriving complex naming within your template and allow you to only pass in the required parameters.
An example of this is an organization that uses a customer ID and depends on this for its naming convention to keep all deployed resources in Azure unique to that customer ID. In this case, you would create the customer ID as a parameter and then develop variables to generate names using your naming standard. You can find a list of acceptable data types for variables at https://docs.microsoft.com/azure/azure-resource-manager/templates/template-syntax#data-types.
Best practices
Microsoft recommends the following best practices for variables:
- Remember to remove unused variables and files as they can be confusing.
- Use camel casing for your variable names.
- Use variables for values that you need more than once within your template.
- Variable names must be unique.
- For repeatable patterns of JSON objects, use the copy loop in variables.
Resources
The resources section of the ARM templates is reserved for resources that will be deployed or updated. ARM templates generally help derive the desired state of the resources within Azure. When changing Azure infrastructure, it is always a good practice to change your template first and then re-run it to change your Azure resources. All too often, organizations make changes on the portal but forget to change their ARM template, and then the next time they deploy these resources, they are deployed into the wrong state.
Best practices
Microsoft recommends the following best practices for resources:
- Add comments to your resources so that others know their purpose.
- Remember that there are quite a few resources that require unique names, so never hardcode your resource names.
- When you add a password to a custom script extension, use the
CommandToExecuteproperty in the protected settings of Azure Resource Manager.
We now have a fundamental understanding of the elements within an ARM template. Our next focus will be identity and access control once your resources have been deployed.
