AzureRM Provider

AzureRM Provider Version v3.0

The last major release for the AzureRM provider was in February 2020. Since then we've added support for nearly 400 Resources and 100 Data Sources, bringing the total supported features to 761 Resources and 238 Data Sources at the time of writing this guide.

Considerations

Version 3.0 of the AzureRM Provider is a major release and as such includes some larger-scale changes which are outlined in this document.

When upgrading to v3.0 of the AzureRM Provider, we recommend upgrading to the latest version of Terraform Core (which can be found here) - the next major release of the AzureRM Provider (v4.0) will require Terraform 1.0 or later.

If you're using the AzureRM Backend you should also be aware that:

Version 1.1 of Terraform Core introduces support for Microsoft Graph (MSAL) authentication - although this is disabled by default and needs to be enabled using a feature flag (useMicrosoftGraph =True), otherwise Azure Active Directory (ADAL) authentication is used.
In the future version 1.2 of Terraform Core will switch to using Microsoft Graph (MSAL) authentication by default (changing the default value of the feature flag useMicrosoftGraph from false to true) - however note that this feature-flag will be removed in a future release of Terraform Core.

Pinning your Provider Version

We recommend pinning the version of each Provider you use in Terraform - you can do this using the version attribute within the requiredProviders block, either to a specific version of the AzureRM Provider, like so:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as azurerm from "./.gen/providers/azurerm";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: hashicorp/azurerm.
For a more precise conversion please use the --provider flag in convert.*/
new azurerm.provider.AzurermProvider(this, "azurerm", {
  features: [{}],
});

.. or to any 2.x release:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as azurerm from "./.gen/providers/azurerm";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: hashicorp/azurerm.
For a more precise conversion please use the --provider flag in convert.*/
new azurerm.provider.AzurermProvider(this, "azurerm", {
  features: [{}],
});

More information on how to pin the version of a Terraform Provider being used can be found on the Terraform Website.

What's available in Version 3.0 of the AzureRM Provider?

-> Note: Version 2970-2990 of the Azure Provider allow you to opt-into the Beta of these features - see the Beta guide for more information

At a high level, version 3.0 includes the following changes:

New Data Sources and Resources for App Service and Function Apps
Soft Delete Recovery/Purging for Certificates, Keys, and Secrets
Switching to Microsoft Authentication Library (MSAL)
Updates to existing behaviors for Application Gateway, API Management, Resource Groups, Storage, among others
Removal of Deprecated Fields, Data Sources, and Resources

Each of these topics is covered in more detail below.

New Resources and Data Sources for App Service

While it’s possible to provision App Services and Function Apps in Terraform today, the design and behaviour of the App Service platform has evolved over the years. These resources require some refinement.

Similar to the changes for Virtual Machines in v2.0 of the Azure Provider, we've introduced more granular resources for App Service to better represent the functionality available in Azure. This is most noticeable in the separation of some resources into Linux and Windows variants. This separation is intended to facilitate improved validation and more intuitive configuration for their differing requirements and capabilities, which could previously be unclear or confusing in the respective singular resources.

The following new Data Sources will be available:

The following new Resources will be available:

azurerm_app_service_source_control
New Resource to apply Source Control configuration to Web and Function Apps (for use with Linux and Windows based versions)
azurerm_app_service_source_control_slot
New Resource to apply Source Control configuration to Web and Function App Slots (for use with Linux and Windows based versions)
azurerm_function_app_active_slot
Supersedes azurermAppServiceActiveSlot for both Linux and Windows based Function Apps.
azurerm_function_app_hybrid_connection
Supersedes azurermAppServiceHybridConnection for Hybrid Connections on Linux and Windows based Web Apps
azurerm_linux_function_app
Supersedes azurermFunctionApp for Linux based Function Apps
azurerm_linux_function_app_slot
Supersedes azurermFunctionAppSlot for Deployment Slots on Linux based Function Apps
azurerm_linux_web_app
Supersedes azurermAppService for Linux based Web Apps
azurerm_linux_web_app_slot
Supersedes azurermAppServiceSlot for Deployment Slots on Linux based Web Apps
azurerm_service_plan
Supersedes azurermAppServicePlan
azurerm_source_control_token
Supersedes azurermAppServiceSourceControlToken
azurerm_web_app_active_slot
Supersedes azurermAppServiceActiveSlot for both Linux and Windows based Web Apps.
azurerm_web_app_hybrid_connection
Supersedes azurermAppServiceHybridConnection for Hybrid Connections on Linux and Windows based Web Apps
azurerm_windows_function_app
Supersedes azurermFunctionApp for Windows based Function Apps.
azurerm_windows_function_app_slot
Supersedes azurermFunctionAppSlot for Deployment Slots on Windows based Function Apps
azurerm_windows_web_app
Supersedes azurermAppService for Windows based Web Apps.
azurerm_windows_web_app_slot
Supersedes azurermAppServiceSlot for Deployment Slots on Windows based Web Apps

Migrating to New & Renamed Resources

When migrating to the new version of deprecated resources the schema may be different than what currently exists in state. Therefore, it is recommended to first update your terraform configuration with the new resource, use terraformStateRm, and then terraformImport.

A guide on how to do this can be found in the Migrating from Deprecated Resources Guide and a tutorial for terraformImport can be found here

Soft Delete for Key Vault

Previously, soft delete has only been available for a Key Vault resource as a whole. Now, you’ll be able to soft delete the nested items within a Key Vault: certificates, keys, and secrets.

This can be configured in the features block like so:

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as azurerm from "./.gen/providers/azurerm";
/*The following providers are missing schema information and might need manual adjustments to synthesize correctly: azurerm.
For a more precise conversion please use the --provider flag in convert.*/
new azurerm.provider.AzurermProvider(this, "azurerm", {
  features: [
    {
      key_vault: [
        {
          purge_soft_delete_on_destroy: true,
          purge_soft_deleted_certificates_on_destroy: true,
          purge_soft_deleted_keys_on_destroy: true,
          purge_soft_deleted_secrets_on_destroy: true,
          recover_soft_deleted_certificates: true,
          recover_soft_deleted_key_vaults: true,
          recover_soft_deleted_keys: true,
          recover_soft_deleted_secrets: true,
        },
      ],
    },
  ],
});

The default value is true for each of the above feature flags, and they can be toggled off by explicitly setting them to false. For more information, please refer to the Features Block documentation.

Switching to MSAL

Authentication to APIs such as Resource Manager was previously performed using the ADAL library which yielded legacy v1 authentication tokens. In version 3.0 of the provider we've moved to use v2 tokens. In practice this change will not yield any noticeable behavioral differences.

Behavioural updates

All Resources: The Resource ID will now be validated at import time to ensure the correct resource is being imported, and return the expected format upon a mismatch. This ensures that, for example, a Virtual Machine ID is specified rather than the VM Extension ID (which is nested under a Virtual Machine ID).

Resources with a minTlsVersion field: The default minimum TLS version will be 12.

Resources supporting Availability Zones (containing a zones field):

Zones will be made behaviourally consistent across the Provider, that means:

Where a resource has to be provisioned within a single Zone, the field will be renamed zone (to indicate that only a single Zone can be specified).
Where a resource can be provisioned across multiple Zones, the field will be named zones.
Zones are no longer Computed - this means that if you wish Azure to assign an Availability Zone for this resource automatically, you must use ignoreChanges on the zone/zones field.

When the resource can be provisioned across multiple Zones, the following behaviours apply:

To provision the resource without any Zones (zoneless) - omit the zones field.
To provision the resource in a single Zone, specify one zone for the zones field (e.g. zones = ["1"])
To provision the resource across multiple Zones (Zone Redundant), specify all of Availability Zones for the zones field (e.g. zones = ["1", "2", "3"])

Resources with a (Managed) identity block: The presence of an identity block means a Managed Identity should be assigned to this Resource - and the omission of an identity block (or a null value) means that no Managed Identity should be assigned to this Resource.

Application Gateway: The behavior of the nested items will be changed to Sets instead of Lists where required, meaning that the order of these items no longer matters. Note that if you're referencing these nested items within your Terraform Configuration, then this may require some code changes.

API Management: Terraform will now remove the Default API and Products for API Management when creating a new API Management instance, which is consistent with the behavior for other Terraform Providers.

Firewall: The behavior of the nested items will be changed to List instead of Sets where required, meaning that the order of these items now matters. Note that if you're referencing these nested items within your Terraform Configuration, then this may require some code changes.

Log Analytics: The tags field has been removed from various resources.

Resource Groups: Terraform will now check for Resources nested within a Resource Group prior to deletion of the resource group. If any items are found, an error will be raised. This behavior is configurable in the features block, but was previously disabled by default. In 3.0, this behavior will be enabled by default.

Recovery Services: The tags field has been removed from various resources.

Storage: The field allowBlobPublicAccess will be renamed to allowNestedItemsToBePublic to resolve confusion about what this field does. This field specifies whether items within the Storage Account (such as Containers and Blobs) can opt-in to being made public (for example at the Container or Blob level) - and not that all resources within this Storage Account are public by default.

Other Individual Resources:

azurermDatabaseMigrationService - The provider will now delete this resource even if it still contains running tasks.
azurermIothub - When creating a new azurermIothub resource, a Fallback Route will be enabled by default.
azurermMssqlDatabase - The new field transparentDataEncryptionEnabled will be set to true and can not be disabled on servers with SKUs other than ones starting with dw.
azurermStorageShare - The quota property is now required instead of defaulting to 5120 GB.

Removal of Deprecated Fields, Data Sources and Resources

Since version 3.0 is a major version - we intend to take this opportunity to remove deprecated Fields, Resources, and Data Sources.

Below we'll cover each of the Data Sources and Resources which will be affected by the 3.0 upgrade.

Data Source: `azurermAppService`

The azurermAppService data source has been superseded by the azurermLinuxWebApp and azurermWindowsWebApp data sources. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

Data Source: `azurermAppServicePlan`

The azurermAppServicePlan data source has been superseded by the azurermServicePlan data source. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

Data Source: `azurermBackupPolicyFileShare`

The field tags will be removed since the API no longer supports these on this resource.

Data Source: `azurermBackupPolicyVm`

The field tags will be removed since the API no longer supports these on this resource.

Data Source: `azurermBatchPool`

The deprecated field startTaskEnvironment will be removed in favour of the startTaskCommonEnvironmentProperties properties.

The deprecated field startTaskMaxTaskRetryCount will be removed in favour of the startTaskTaskRetryMaximum property.

Data Source: `azurermContainerRegistry`

The deprecated field storageAccountId has been removed as it is no longer recognized by the API nor functional.

Data Source: `azurermCosmosdbAccount`

The field capabilities will no longer accept the value enableAnalyticalStorage.

The deprecated field primaryMasterKey will be removed in favour of the primaryKey property.

The deprecated field secondaryMasterKey will be removed in favour of the secondaryKey property.

The deprecated field primaryReadonlyMasterKey will be removed in favour of the primaryReadonlyKey property.

The deprecated field secondaryReadonlyMasterKey will be removed in favour of the secondaryReadonlyKey property.

Data Source: `azurermDataLakeStore`

Data Lake Gen1 is deprecated and new accounts can no longer be provisioned - as such this deprecated Data Source has been removed from the Azure Provider.

Data Source: `azurermDataShareDatasetDataLakeGen1`

Data Lake Gen1 is deprecated and new accounts can no longer be provisioned - as such this deprecated Data Source has been removed from the Azure Provider.

Data Source: `azurermFunctionApp`

The azurermFunctionApp data source has been superseded by the azurermLinuxFunctionApp and azurermWindowsFunctionApp data sources. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

Data Source: `azurermFunctionAppHostKeys`

The deprecated field masterKey will be removed in favour of the primaryKey property.

Data Source: `azurermKeyVault`

The deprecated field softDeleteEnabled will be removed since the Azure API always returns true.

Data Source: `azurermKubernetesCluster`

The deprecated block addonProfile will be removed in favour of the azurePolicyEnabled, httpApplicationRoutingEnabled and openServiceMeshEnabled properties and the ingressApplicationGateway, keyVaultSecretsProvider and omsAgent blocks.

The field availabilityZones will be removed in favour of zones to be consistent across the Provider.

The field userAssignedIdentityIds within the identity block will be renamed to identityIds to be consistent across the Provider - see the dedicated issue on how Identity is changing in 3.0 for more information.

The deprecated block roleBasedAccessControl will be removed in favour of the roleBasedAccessControlEnabled property and the azureActiveDirectoryRoleBasedAccessControl block.

Data Source: `azurermKubernetesClusterNodePool`

The field availabilityZones will be removed in favour of zones to be consistent across the Provider.

Data Source: `azurermLbRule`

The deprecated field resourceGroupName will be removed since it can be inferred from the loadbalancerId.

Data Source: `azurermLogAnalyticsWorkspace`

The deprecated field portalUrl will be removed since it no longer exists in the Azure API.

Data Source: `azurermManagementGroup`

The deprecated field groupId will be removed in favour of the name property.

Data Source: `azurermMssqlServer`

The field userAssignedIdentityIds within the identity block will be renamed to identityIds to be consistent across the Provider - see the dedicated issue on how Identity is changing in 3.0 for more information.

Data Source: `azurermNetappVolume`

The deprecated field dataProtectionReplicationReplicationSchedule will be removed as it no longer exists in the Azure API. The property dataProtectionReplicationReplicationFrequency can be used instead.

Data Source: `azurermPublicIps`

The deprecated field attached will be removed in favour of the attachmentStatus property.

Data Source: `azurermPolicyDefinition`

The deprecated field managementGroupId will be removed in favour of the managementGroupName property.

Data Source: `azurermPostgresqlFlexibleServer`

The deprecated field cmkEnabled will be removed since it no longer exists in the Azure API.

-> NOTE: This guide is a Work In Progress and as such Fields, Resources and Data Sources may be added to this guide until version 3.0 of the AzureRM Provider is released.

Resource: `azurermApiManagementCustomDomain`

The deprecated proxy block will be removed in favour of the gateway block.

Resource: `azurermApiManagementDiagnostic`

The deprecated field enabled will be removed since it no longer exists in the Azure API.

Resource: `azurermApiManagementApiOperation`

The deprecated field responseRepresentationSample will be removed in favour of the property responseRepresentationExample.

The deprecated field requestRepresentationSample will be removed in favour of the property requestRepresentationExample.

Resource: `azurermApiManagementProperty`

The azurermApiManagementProperty resource will be removed in favour of the azurermApiManagementNamedValue resource.

Resource: `azurermApiManagement`

The deprecated field securityEnabledTripleDesCiphers will be removed in favour of the securityTripleDesCiphersEnabled property.

Resource: `azurermApplicationGateway`

The field probeMatchStatusCode will become Required.

Resource: `azurermAppService`

The azurermAppService resource has been superseded by the azurermLinuxWebApp and azurermWindowsWebApp resources. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

The identity block will be made consistent across the Provider - see the dedicated issue on how Identity is changing in 3.0 for more information.

The field siteConfigRemoteDebuggingVersion will no longer accept the values vs2012, vs2013 and vs2015.

Resource: `azurermAppServiceActiveSlot`

The azurermAppServiceActiveSlot resource has been superseded by the azurermWebAppActiveSlot and azurermFunctionAppActiveSlot resources. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider."

Resource: `azurermAppServiceCertificate`

The deprecated field hostingEnvironmentProfileId will be removed in favour of the appServicePlanId property.

Resource: `azurermAppServiceEnvironment`

The deprecated field userWhitelistedIpRanges will be removed in favour of the allowedUserIpCidrs property.

Resource: `azurermAppServicePlan`

The azurermAppServicePlan resource has been superseded by the azurermServicePlan resource. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

Resource: `azurermAppServiceHybridConnection`

The azurermAppServiceHybridConnection resource has been superseded by the azurermFunctionAppHybridConnection and azurermWebAppHybridConnection resources. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

Resource: `azurermAppServiceSlot`

The azurermAppServiceSlot resource has been superseded by the azurermLinuxWebAppSlot and azurermWindowsWebAppSlot resources. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

The identity block will be made consistent across the Provider - see the dedicated issue on how Identity is changing in 3.0 for more information.

The field siteConfigRemoteDebuggingVersion will no longer accept the values vs2012, vs2013 and vs2015.

Resource: `azurermAppServiceSourceControlToken`

The azurermAppServiceSourceControlToken resource has been superseded by the azurermSourceControlToken resource. Whilst this resource will continue to be available in the 2.x and 3.x releases it is feature-frozen for compatibility purposes, will no longer receive any updates and will be removed in a future major release of the Azure Provider.

Resource: `azurermAutomationSchedule`

The default value for the field timezone will be changed from utc to etc/utc.

Resource: `azurermBackupPolicyFileShare`

The deprecated field tags will be removed since it is no longer supported by the Azure API.

Resource: `azurermBackupPolicyVm`

The deprecated field tags will be removed since it is no longer supported by the Azure API.

Resource: `azurermBackupProtectedVm`

The deprecated field tags will be removed since it is no longer supported by the Azure API.

Resource: `azurermBatchPool`

The deprecated field environment will be removed in favour of the commonEnvironmentProperties properties.

The deprecated field maxTaskRetryCount will be removed in favour of the taskRetryMaximum property.

Resource: `azurermCdnEndpoint`

The hostName field is being renamed to fqdn to better reflect the information held in that field.

Resource: `azurermCognitiveAccount`

The deprecated field networkAclsVirtualNetworkSubnetIds will be removed in favour of the networkAclsVirtualNetworkRules property.

The deprecated field outboundNetworkAccessRestrited will be removed in favour of the outboundNetworkAccessRestricted property.

Resource: `azurermContainerRegistry`

The field sku is now Required and no longer defaults to classic.

The field sku can no longer be set to classic as Classic Container Registries are no longer supported by Azure.

The deprecated field georeplicationLocations will be removed in favour of the georeplications property.

The deprecated field storageAccountId will be removed since it is no longer recognized by the Azure API.

Resource: `azurermConsumptionBudgetSubscription`

The field subscriptionId will only accept subscription resource IDs instead of subscription IDs.

Resource: `azurermCostManagementExportResourceGroup`

The azurermCostManagementExportResourceGroup resource will be removed in favour of the azurermResourceGroupCostManagementExport resource.

Resource: `azurermCosmosdbAccount`

The field capabilities will no longer accept the value enableAnalyticalStorage.

The deprecated field geolocationPrefix will be removed since it is no longer supported by the Azure API.

The deprecated field primaryMasterKey will be removed in favour of the primaryKey property.

The deprecated field secondaryMasterKey will be removed in favour of the secondaryKey property.

The deprecated field primaryReadonlyMasterKey will be removed in favour of the primaryReadonlyKey property.

The deprecated field secondaryReadonlyMasterKey will be removed in favour of the secondaryReadonlyKey property.