Azure Bicep/ARM recommended API Version to use (Preview vs Stable)

Question

I am working on Azure Bicep/ARM templates, I would like to know the Safe/recommended approach to use API versions on resource providers while creating templates in a big organization where multiple teams are going to use.

If we declare a resource type and use API version, we get lot of options in terms of Preview vs stable version. As we always know that Stable version is recommended but most cases it looks way too old and previews look latest.

In the below screenshot for SQL server resource, Preview version looks latest and stable heads to 2014 which may lead to compromise on latest features

So, how can we decide on the API version which is stable/safe but cover latest features without breaking changes

resource sqlServer 'Microsoft.Sql/servers@2021-11-01-preview' = {
  name: serverName
  location: location
  tags: tags
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    version: version
    publicNetworkAccess: 'Enabled'
    administratorLogin: adminUserName
    administratorLoginPassword: administratorLoginPassword
  }
}

Answer 1

You will quickly find that when you start working with ARM templates you will need to use a lot of different API versions, in fact finding the API combination for each resource can be like navigating a labyrinth sometimes since what works for one resource type might not work for another and you need to find the combination that works for all and believe me sometimes this is far from trivial, so do not be mistaken and simply think you can stick to the same API version for all resources.

One way of doing this I found helpful is to create a resource of the same time in the Azure Portal and then download the template from there and see what API version they use, this has served me well many times.

Answer 2

Some guidance you can use...

• Use the latest non-preview apiVersion unless there is a feature you need that's only available in a newer/preview version (this will be true for SQL)
• You don't need to upgrade your apiVersion unless there's a feature you need in the new version. It doesn't hurt to revisit this every year or so to see if there are new capabilities available (SQL example again) - but aside from new features there's no reason you always need to be on the "latest"
• new apiVersions are more about functionality and schema changes than they are about "stability" - as Matt Douhan mentioned, if there is an apiVersion that's publicly available (ie public preview) its supported and considered "stable".

HTH