How do I keep resource API versions up to date on existing ARM template?

1. "What is the best practice to maintain resource API versions in a template?"

You shouldn't need to update the api-version field for a resource unless you are utilizing a new feature that is not covered by the previous api-version.

Mainly, if it works, don't fix it.

The purpose of the embedded api-version fields in an ARM template is to ensure that template continues to function as desired at any point in time.

I have seen some templates with a Variable for the api-version. I'm not a fan of that approach. It makes it too easy to change an api-version where updating that version may invalidate the schema and cause any number of errors.

2. "Where do I learn about the changes introduced in each API version?"

It is in a very raw form but you can see the Swagger specs for the resource providers in this GitHub repo.

GitHub: azure/azure-rest-api-specs and GitHub: azure/azure-resource-manager-schemas

Azure SDKs, ARM templates, and even some portal UI takes this repo as a Swagger source for auto-generation.

For the latest ARM version feature you can use this docs sub-site which is also generated from the spec.

ARM Template Resource Definitions

3. What will Azure do if I change an API version on a resource that is already provisioned using the older API version?

If you change the api-version and execute a change, the Azure resource manager API may respond with object schema errors if you have not updated the resource configuration to the new version.

You can run a Validate call to get those errors without making any changes.

Again, unless you are using a new feature or configuration in a new api version, there really is no reason to update the api-version of a template resource.

Based on the other responses I have drafted the following best practice document for my team for Resource Manager API Versions.

Azure Resource Manager API Version Guidelines

1. Use latest API version possible for new resources added to a template. Use article Resource providers and types as a guide on how to get the latest API version for a resource type.

2. Do not change API version of a provisioned resource for the purpose of keeping up to date with the API version. General principle - if it works, don't fix it.

3. Change API version of a provisioned resource only if advised so by Microsoft Azure or if newer API version will enable new feature to be utilized.

4. Do not use template variable for the API version. API versions must be defined as text in a template.

Actually there is a way to always use the latest API Version. I do not recommend it but you can use:

[providers('<provider>','<type>').apiVersions[0]]

Here is a working example with a storage account:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "name": "uniquename",
            "apiVersion": "[providers('Microsoft.Storage','storageAccounts').apiVersions[0]]",
            "location": "West Europe",
            "sku": {
                "name": "Standard_LRS"
            },
            "kind": "Storage",
            "properties": {}
        }
    ]
}

I would prefer to use the most latest version when writing the ARM template and check for newer version when I encounter errors or I have to use some new features. I wrote two articles about how to determine latest API version for a resource provider and how to find outdated Azure ARM templates.

1. There are none, because it makes no sense (read further)
2. I'm not aware of such a place, most likely it doesn't exist at all
3. Nothing, unless something changed in the resource definition.

Generally, you should not care about the API version as long as you are using an API version that can handle your request (API versions can have different functionality) in a proper fashion.

the PM of the ARM Templates said: API Version's don't matter and don't have to be consistent with each other (so you can use different API Versions for all resources in the same template, and equal API versions doesn't mean that resources will work better with together or something like that). (not exact quote, but you get the idea)

Even if you look at the rest api reference at best it will point out which api version its describing (at best). sometimes it won't do even that... so its a black box, don't bother with that.

The only time api version matters - things you want to do are not available with your api version and you need to use a proper one (not necessary latest, sometimes older versions got what you need, like managed disks were\are 2016-04-30-preview or something like that)