Upgrade Guide for Azure Native v2 to v3
About
The Pulumi Azure Native Provider v3 is now available. To upgrade to v3 and take advantage of the smaller SDKs and other improvements, there are a few changes you may need to make depending on your Pulumi programs.
Upgrade Steps
Prerequisites
We recommend upgrading to the latest version of the v2 provider as a prerequisite to the v3 upgrade. This will enable you to resolve any pre-existing deprecated versions or resource structure changes.
Review your program for warnings on missing imports or deprecated resources. If your program uses any explicit API versions where the import contains the API version, you will need to update these since explicit API versions are no longer included in the SDK. It’s recommended to migrate to the default version, if possible, or you can generate a local SDK for the desired API version as described in the version guide.
Upgrade Dependencies
In your Pulumi program, upgrade the package to point to the latest v3.x version.
- JavaScript/TypeScript:
@pulumi/azure-native
- Python:
pulumi-azure-native
- Go:
github.com/pulumi/pulumi-azure-native/sdk/go/azure
- .NET:
Pulumi.AzureNative
- Java:
com.pulumi.azurenative
-"@pulumi/azure-native": "^2.0.0",
- "resolved": "https://registry.npmjs.org/@pulumi/azure-native/-/azure-native-2.89.3.tgz",
+"@pulumi/azure-native": "v3.0.0",
+ "resolved": "https://registry.npmjs.org/@pulumi/azure-native/-/azure-native-3.0.0.tgz",
- pulumi_azure_native==v2.89.3
+ pulumi_azure_native==v3.0.0
- <PackageReference Include="Pulumi.AzureNative" Version="2.89.3"
+ <PackageReference Include="Pulumi.AzureNative" Version="3.0.0"
In go.mod:
- github.com/pulumi/pulumi-azure-native-sdk/storage v2.89.3
+ github.com/pulumi/pulumi-azure-native-sdk/v3/storage v3.0.0
Go programs will also need all imports updated to include v3
in the path.
import (
- "github.com/pulumi/pulumi-azure-native-sdk/resources/v2"
- "github.com/pulumi/pulumi-azure-native-sdk/storage/v2"
+ "github.com/pulumi/pulumi-azure-native-sdk/resources/v3"
+ "github.com/pulumi/pulumi-azure-native-sdk/storage/v3"
)
Review Pulumi Diff
After updating all imports to reflect v3 included Azure API versions, run pulumi preview
and review the output.
Pending Changes on Default Versions
You may see pending changes when using the default version as the shape of the resource may have changed. You can choose to accept the changes, update your program to modify the resource properties to mitigate changes, or choose an API version which is compatible with the older version of the resource.
A full list of default version changes can be found in the resource versions table.
To continue using the previous Azure API version of a resource:
- Check the resource documentation in your IDE or our registry API docs which identifies the previous version for each resource. For example:
Uses Azure REST API version 2024-10-01. In version 2.x of the Azure Native provider, it used API version 2023-05-01.
- Generate and use the local SDK for the previous version of the resource as described in the version guide.
New module structure and naming aligned closer to Azure SDKs
The Azure specification sometimes contains related but distinct services in one namespace. For example, Microsoft.Network
contains DNS
, DnsResolver
, Frontdoor
, Network
, PrivateDns
, and TrafficManager
.
The Azure SDKs reflect this so that these different network-related services are logically grouped instead of mixed up in one Network
namespace. In v3 of this provider, we have aligned several modules to match the Azure SDK layout. The changes are:
Cache
is split intoRedis
andRedisEnterprise
which also reflects the current names of the services.Devices
is split intoDeviceProvisioningServices
andIotHub
.DocumentDB
is not split but renamed toCosmosDB
to reflect the current naming of the service.Insights
is split intoApplicationInsights
andMonitor
.Network
is split intoDns
,DnsResolver
,Frontdoor
,Network
,PrivateDns
, andTrafficManager
.
You’ll need to update your code to use the new module names. The resources in these modules have been aliased to support this migration with no replacements of existing resources.
De-duplication of conflicting resources and types
The Azure specification sometimes uses the same name for different resources in the same module. For example, CosmosDB.FirewallRule
can refer to both regular and MongoDB (Microsoft.DocumentDB/mongoClusters
) instances. In v3, we have de-duplicated these to FirewallRule
and MongoClusterFirewallRule
. The complete list of changes are:
- In
CosmosDB
,FirewallRule
was split intoFirewallRule
andMongoClusterFirewallRule
. - In
HDInsight
,Cluster
was split intoCluster
andClusterPoolCluster
. - In
HybridContainerService
,HybridIdentityMetadatum
was split intoHybridIdentityMetadata
andClusterInstanceHybridIdentityMetadatum
. - In
NetApp
, resources relating to Capacity Pools are prefixed withCapacityPool
, splittingBackup
intoBackup
andCapacityPoolBackup
.
You’ll need to update your code to use the new names. The resources in these modules have been aliased to support this migration with no replacements of existing resources.
Propagating forceNew
from referenced types
Tracked by #3006, this change extended the replaceOnChanges
parameter to be propagated from referenced types. This improves the correctness of the provider by correctly replacing resources when sub-properties of the resource that are annotated with replaceOnChanges
are updated.
You can set the environment variable PULUMI_FORCE_NEW_FROM_SUBTYPES
to false
to disable this behavior if you observe unnecessary recreation of resources. Please file an issue in that case since that would be unexpected.
Improved flattening of resource shapes
Tracked by #3195, this change improved the correctness of the provider by avoiding to flatten nested properties, even when requested by the Azure API specification, when it would lead to the overwriting of properties.
For instance, the network:NetworkVirtualApplianceConnection
resource has a property called Properties
which has in turn, slightly simplified, two properties: Name
and TunnelIdentifier
.
NetworkVirtualApplianceConnection:
Name
Properties:
Name
TunnelIdentifier
Properties
is annotated in the API spec to be flattened into the outer NetworkVirtualApplianceConnection
. That’s what v2 of the provider does, with the result being:
NetworkVirtualApplianceConnection:
Name
TunnelIdentifier
Since NetworkVirtualApplianceConnection
already has a Name
property, the two Name
s are in conflict. In v3, the provider does not flatten Properties
due to this conflict and the result is:
NetworkVirtualApplianceConnection:
Name
Properties:
Name
TunnelIdentifier
All affected resources are listed below:
azure-native:authorization:AccessReviewHistoryDefinitionById
azure-native:authorization:AccessReviewScheduleDefinitionById
azure-native:authorization:ScopeAccessReviewHistoryDefinitionById
azure-native:authorization:ScopeAccessReviewScheduleDefinitionById
azure-native:devhub:Workflow
azure-native:education:Lab
azure-native:network:P2sVpnServerConfiguration
azure-native:network:VpnServerConfiguration
azure-native:security:DefenderForStorage
azure-native:vmwarecloudsimple:DedicatedCloudNode
MySQL and PostgreSQL Server and Flexible Server
Tracked by #2753, this change cleanly separates the different PostgreSQL offerings from Azure: Flexible Servers, Server Groups V2, and the deprecated Single Server offering.
- import * as mysqldb from "@pulumi/azure-native/dbformysql"
+ import * as mysqldb from "@pulumi/azure-native/dbformysql/v20171201"
- import * as postgresqldb from "@pulumi/azure-native/dbforpostgresql"
+ import * as postgresqldb from "@pulumi/azure-native/dbforpostgresql/v20171201"
- from pulumi_azure_native import dbformysql
+ from pulumi_azure_native.dbformysql import v20171201 as dbformysql
- from pulumi_azure_native import dbforpostgresql
+ from pulumi_azure_native.dbforpostgresql import v20171201 as dbforpostgresql
- using MySQLDB = Pulumi.AzureNative.DBforMySQL;
+ using MySQLDB = Pulumi.AzureNative.DBforMySQL.V20171201;
- using PostgreSQLDB = Pulumi.AzureNative.DBforPostgreSQL;
+ using PostgreSQLDB = Pulumi.AzureNative.DBforPostgreSQL.V20171201;
- import mysqldb "github.com/pulumi/pulumi-azure-native-sdk/dbformysql"
+ import mysqldb "github.com/pulumi/pulumi-azure-native-sdk/dbformysql/v2/v20200601"
- import postgresqldb "github.com/pulumi/pulumi-azure-native-sdk/dbforpostgresql"
+ import postgresqldb "github.com/pulumi/pulumi-azure-native-sdk/dbforpostgresql/v2/20171201"
- type: azure-native:dbformysql:Server
+ type: azure-native:dbformysql/v20171201:Server
- type: azure-native:dbforpostgresql:Server
+ type: azure-native:dbforpostgresql/v20171201:Server
Removed __inputs
from state
This change is completely transparent to users, except for those who have custom code or scripts working with Pulumi stack state. In v2 and older, the provider added a field __inputs
to the state of each resources which tracked the inputs of the resource at the time of its creation. This is not necessary anymore since the Pulumi engine now supports sending the old inputs.
Contributing
If you experience any unexpected issues during your migration or would like to contribute to our codebase, please visit our respository to open an issue or submit a pull request.