Upgrade to Version 2 of the Pulumi Azure Native Provider

Azure, Pulumi, Infrastructure as Code

Pulumi recently announced the beta release of their Azure Native provider. This provider allows the creation of Azure infrastructure using Pulumi, with the native part meaning that this is auto-generated from the Azure APIs, rather than hand-crafted like some of the Terraform-based providers. Upgrading to v2 should be a fairly easy process, there are no huge tasks to undertake, but there are some things to be aware of, which we will look at in this article.

The v2 Azure Native provider is currently in beta, with GA expected later this year. Ensure you do not use it for production workloads unless you accept the risk of using a beta provider

Why Upgrade?

Before upgrading, it’s worth being aware of what has changed and why this is a major release. The main changes in this release are:

  • Reduction in the size of the provider
  • Refresh default module versions
  • Expansion of coverage to include even more resources
  • Resolved issues with case inconsistency across some resources
  • Simplified User Assigned Managed Identity Inputs

Most of these are self-explanatory, but let’s dive into a couple, as these are relevant to the upgrade process, and this is around API versions.

Understanding API Versions

All of the Azure APIs have a concept of API versions, this allows Microsoft to introduce new features, or remove old ones, without breaking backward compatibility. You need to use the appropriate API version which contains the properties that you need on your resource. If you’ve ever used ARM or Bicep you will be familiar with them as they are part of the resource declaration, for example:

resource stg 'Microsoft.Storage/storageAccounts@2022-09-01' = {
  name: 'sto445'
  location: 'westeurope'
  ...

This example uses API version 2022-09-01, which is the latest one for Azure storage.

With Pulumi, you don’t have to specify an API version, and if you don’t then behind the scenes a default version is used. So the same storage account in Pulumi would look like this:

   var storageAccount = new AzureNative.Storage.StorageAccount("storageAccount", new()
    {
        AccountName = "sto4445",
        Location = "westeurope"
        ...

However, the default version that Pulumi selects isn’t always the latest one currently available. It will generally be the latest one at the time the last major version of the Pulumi was released. For storage, the default is the 2021-02-01 API version. Given that the v1 version was released some time ago, the default version is often a way behind the latest. This is not a big issue, as it is possible to specify the API version to use with Pulumi, and this can be the latest one. For example:

   var storageAccount = new AzureNative.Storage.v2022-09-01.StorageAccount("storageAccount", new()
    {
        AccountName = "sto4445",
        Location = "westeurope"
        ...

As you can see, we can specify the API version in the type, and this will be used in our deployment, but we do have to call it out specifically if the default version is not what we want.

Updates to API Versions

All of this leads us to the updates that impact these API versions, and that will have an impact when you upgrade.

First, the provider has been made smaller, and one way this has been done is by reducing the amount of API versions using two methods:

  1. Removing deprecated API versions
  2. Merging forward-compatible API versions

The removal of deprecated APIs shouldn’t have much impact, as these generally shouldn’t be used. But the second option might impact you. This process removes any API versions where there is a newer API version that is directly compatible with the old one, so you can use the new API version without having to make any changes to your code. If you use the default API versions then this won’t affect you, however, if you are using specific versions in your code, and these versions have been removed in favour of the forward-compatible later version, you will see errors in your code and you will need to change to using the newer API version.

Secondly, the default versions have been updated to now be the latest API versions at the release of the v2 provider. This means that if you are using the default version, you may find they are broken when you upgrade the provider because there are new mandatory properties that you are not providing, changes in the names or values of properties, or properties that don’t exist any more.

Upgrading to v2

So now you are aware of the possible issues, we can work through the upgrade process.

The first thing is to upgrade to the latest version of the v1 provider to resolve any issues with deprecated versions. At the time of writing, this was v1.103.0. You can upgrade this in the package manager for your chosen language. For C# this is using Nuget:

<PackageReference Include="Pulumi.AzureNative" Version="1.103.0" />

Once you have successfully moved to the latest v1 version, you can then move to v2 by changing the same package reference to the latest v2 version. This is currently v2.0.0-beta.1

<PackageReference Include="Pulumi.AzureNative" Version="v2.0.0-beta.1" />

Whilst this is still in beta you may need to allow pre-release packages in your package manager.

Now you have v2 installed you can compile (if needed) and see where you are getting errors which you need to resolve. These will be one of:

  • When using a specific API version, the API version you specify no longer exists and needs to be changed to a later, forward-compatible one
  • When using the default API version, there are properties on the resource that have changed or been removed, or new properties that are mandatory
  • User Assigned Managed Identity assignments need to be updated to use the new syntax

Once you fix all these errors you can run a pulumi preview and look at the diff to see what changes are going to be made to the resources given the new API versions. Generally, these should all be minor changes, but make sure you review them and confirm they are not doing something you don’t want.

Once your preview completes, run a pulumi up to complete the upgrade process.