The apiVersion of a resource is used to determine the configurable properties and values for the resource. Setting it as a parameter or variable is not recommended, as it can lead to unexpected behaviors and deployment failures.

Why is this an issue?

In Azure, different API versions of a resource can have different properties and values.

Using a variable or parameter for the apiVersion for a resource is not an optimal way to always stay up to date with the latest version. This can lead to unexpected behaviors like deployment failures, when the API version you set for a resource doesn’t match the properties in your template.

How to fix it in ARM Templates

To avoid these issues, it is recommended to set the apiVersion to a hard-coded value for the resource type.

When creating a new template, we suggest you use the latest API version for a resource type.

To determine which version to use, you can refer to the template reference of the official documentation linked below. Make sure to choose a version that supports all the features you need.

When your template works as expected, we recommend you continue using the same API version. Using the same API version means you don’t have to worry about breaking changes that might be introduced in later versions.

Code examples

Noncompliant code example

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "parameters": {
    "customApiVersion": {
      "type": "string"
    }
  },
  "resources": [
    {
      "apiVersion": "[parameters('customApiVersion')]",
      "type": "Microsoft.Compute/virtualMachines",
      "name": "nonCompliantResource",
      "location": "[resourceGroup().location]"
    }
  ]
}

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "variables": {
    "customApiVersion": "[first(providers(‘Microsoft.Compute’,’virtualMachines’).apiVersions)]"
  },
  "resources": [
    {
      "apiVersion": "[variables('customApiVersion')]",
      "type": "Microsoft.Compute/virtualMachines",
      "name": "nonCompliantResource",
      "location": "[resourceGroup().location]"
    }
  ]
}

Compliant solution

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "resources": [
    {
      "apiVersion": "2023-09-01",
      "type": "Microsoft.Compute/virtualMachines",
      "name": "compliantResource",
      "location": "[resourceGroup().location]"
    }
  ]
}

Resources

Documentation