Recommendation for Reviewing/Updating API Versions

[haithamshahin333]

What's the recommended approach for knowing when to review past modules/templates and make or test an update to the API Version for a resource type?

If new features are added to a service, that's a good reason to review. Any other thoughts (for example, is there a way to know when an API Version would soon be deprecated or really needs updating)?

Appreciate the discussion and enjoying working with Bicep!

[brwilkinson]

1. Azure (ARM) api's have an extremely long life and it takes a lot of work to deprecate an api version.
   1. Azure (Classic) resources are being decommissioned over time and you will get notices/communications for removal or migrations of those API's/services.
2. You will want to stay on the same API for any particular resource type as long as feasible.
   1. If there is a new feature in a new API version, then you will want to test and update to the API version.
   2. If you have a process to test and roll out new API versions, then often it's safe to make an API version update
      1. this is API, provider specific, not one size fits all.
   3. if you deploy new resources, it's worth updating to the latest API at the initial deployment time
      1. if you are using old ARM or Bicep templates, then this may require code changes to get it to deploy successfully with the latest API. E.g. if you took some QuickStart template and just want to deploy it, then it may take some testing to get it to deploy with the latest API, again, this is provider specific. The effort should always be worth updating the templates for new resource types or environments. Obviously you have to consider backwards compatibility e.g. Green versus Brownfields, when building templates.

I think another perspective on this is looking at this from a feature perspective. One common and easy to understand feature is availability Zones or Zone redundancy. To be zone redundant, you need a supported Region, then you need a specific API version for a resource type and then you need a specific setting on the resource such as a Standard load balancer or publicip.

So then looking at that how do you migrate from Availability Sets to Availability Zones? You need to deploy net new resources in Zone redundant format, then decommission the resources e.g. VM's in an availability set. In order to do this, you can update the API version, to get the Zone capabilities, however these API's are as backwards compatible, if you want to still deploy availability sets, you can, you just need to build your templates in a conditional way to give the consumer the option to choose or to support both green/brownfields deployments, with a single set of templates, that leverage the later API version.

[brwilkinson]

Adding link to docs:
https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/best-practices#api-version

[haithamshahin333]

Thanks for this insight @brwilkinson - great overview and review of different scenarios to consider.

[StephenWeatherford]

We're porting the ARM TTK rule for this: #2470