layout | page_title | sidebar_current | description |
---|---|---|---|
azurerm |
Azure Resource Manager: 2.0 Upgrade Guide |
docs-azurerm-guide-2.0-upgrade |
Azure Resource Manager: 2.0 Upgrade Guide |
Terraform initially shipped support for the AzureRM Provider back in December 2015.
Since then we've added support for 191 Resources, 58 Data Sources and have launched a couple of related Providers in the form of the Azure Active Directory Provider and the Azure Stack Provider.
Version 2.0 of the AzureRM Provider is a major release and as such includes some larger-scale changes which are outlined in this document.
-> NOTE: This guide is a Work In Progress and additional information may be added to this guide until version 2.0 of the AzureRM Provider is released.
We recommend pinning the version of each Provider you use in Terraform - you can do this using the version
attribute in the provider
block, either to a specific version of the AzureRM Provider, like so:
provider "azurerm" {
version = "=1.34.0"
}
.. or to any 1.x release:
provider "azurerm" {
version = "~> 1.x"
}
More information on how to pin the version of a Terraform Provider being used can be found on the Terraform Website.
Once version 2.0 of the AzureRM Provider is released - you can then upgrade to it by updating the version specified in the Provider block, like so:
provider "azurerm" {
version = "=2.0.0"
}
At a high level, we're intending for version 2.0 to include the following changes:
- Changes when importing existing resources - when bringing Resources provisioned outside of Terraform under Terraform's control, these resources will now be required to be imported.
- Custom Timeouts will be available on Resources - this will allow you to specify a custom timeout for provisioning the resource in your Terraform Configuration using the
timeouts
block. - New resources for Virtual Machines and Virtual Machine Scale Sets.
- Removing Fields, Data Sources and Resources which have been deprecated.
Each of these topics is covered in more detail below, however please note that this guide is a Work In Progress until version 2.0 of the AzureRM Provider is released and thus things may be added/changed as necessary.
Terraform allows for existing resources which have been created outside of Terraform to be Imported into Terraform's State. Once a resource is imported into the state, it's possible for Terraform to track changes and manage this resource. The Azure Provider allows Importing existing resources into the state (using terraform import
) for (almost) every resource.
Version 2.0 of the Azure Provider aims to solve an issue where it's possible to unintentionally import resources into the state by running terraform apply
. To explain this further, the majority of Azure's APIs are Upserts - which means that a resource will be updated if it exists, otherwise it'll be created.
Where the unique identifier for (most) Azure resources is the name
(rather than for example an aws_instance
where AWS will generate a different unique identifier) - it's possible that users may have unintentionally imported existing resources into Terraform (and made changes to the resource) when running terraform apply
when using the same unique identifier as an existing resource.
Whilst this may allow resources to work in some cases, it leads to hard-to-diagnose bugs in others (which could have been caught during terraform plan
).
In order to match the behaviour of other Terraform Providers version 2.0 of the AzureRM Provider will require that existing resources are imported into the state prior to use. This means that Terraform will be checking for the presence of an existing resource prior to creating it - and will return an error similar to below:
A resource with the ID /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/group1 already exists - to be managed via Terraform this resource needs to be imported into the State. Please see the resource documentation for `azurerm_resource_group` for more information.
Information on how to import a given Resource can be found in the documentation for that Resource - for example here's how to here's how to import a Resource Group in Terraform.
You can opt into this behaviour in version 1.22 of the AzureRM Provider by setting the Environment Variable ARM_PROVIDER_STRICT
to true
.
Resources can optionally support a timeouts
block - which allows users to specify a Custom Timeout for resource creation/deletion as part of the Terraform Configuration.
Prior to version 2.0 the Azure Provider has a default value set for resource timeouts for an hour - which cannot be overridden. This works for the most-part but there are certain scenarios where it'd be helpful to override this.
This is useful for resources which can take a long time to delete - for example deleting the azurerm_resource_group
resource will delete any resources within it, which can take time. Within Terraform your Terraform Configuration this could be represented like so:
resource "azurerm_resource_group" "test" {
name = "example-resource-group"
location = "West Europe"
timeouts {
create = "10m"
delete = "30m"
}
}
We intend to support the timeouts
block in version 2.0 of the Azure Provider - which will allow timeouts to be specified on resources (as shown above). This feature request is being tracked here and will form part of the 2.0 release of the AzureRM Provider.
We originally shipped support for the azurerm_virtual_machine
and azurerm_virtual_machine_scale_set
resources back in March 2016.
Over time new features have been added to these resources by Azure, such as Managed Disks and Managed Service Identity which these resources support. Since these resources first launched Azure's also changed the behaviour of some fields, so that it's now possible to update them where this wasn't previously possible - for example the Custom Data for a Virtual Machine.
We've spent some time thinking about how we can accommodate these changes and about how we can improve the user experience of both resources.
In particular we've wanted to be able to give better validation during terraform plan
, rather than bailing out with an Azure API error during terraform apply
, however this isn't possible with the current resource structure since they're very generic. The validation requirements also vary substantially based on the fields provided, for example the name
field for a Virtual Machine can be up to 63 characters for a Linux Virtual Machine but only allows 15 characters for a Windows Virtual Machine.
As such after spending some time reading through bug reports and thinking/prototyping some potential solutions to this - we believe the best path forward here is to split these resources out, so that we would have:
- a Linux Virtual Machine Resource (working name:
azurerm_linux_virtual_machine
) - a Windows Virtual Machine Resource (working name:
azurerm_windows_virtual_machine
) - updating the Data Disk Attachment Resource to support Unmanaged Disks
- a Linux Virtual Machine Scale Set Resource (working name:
azurerm_linux_virtual_machine_scale_set
) - a Windows Virtual Machine Scale Set Resource (working name:
azurerm_windows_virtual_machine_scale_set
) - a separate resource for Virtual Machine Scale Set Extensions (working name
azurerm_virtual_machine_scale_set_extension
)
Please Note: all of the resources mentioned above currently do not exist but will form part of the 2.0 release.
Whilst we're aware that this isn't ideal since users will eventually have to update their code/import an existing resource - we believe this approach gives us a good footing for the future. In particular this allows us to re-consider the schema design so that we can both support these new use-cases, fix some bugs and improve the user experience with these resources.
The existing azurerm_virtual_machine
and azurerm_virtual_machine_scale_set
resources would continue to be available throughout the 2.x
releases - but over time we'd end up deprecating these in favour of the new resources.
The Azure Provider was first launched in December 2015 - over the years the Provider has accumulated fields which have been deprecated (either by Azure because they're no longer used or because we've created an external resource to use instead).
Since version 2.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 2.0 upgrade.
-> NOTE: This guide is a Work In Progress and as such Fields, Resources and Data Sources may be added to this guide until version 2.0 of the AzureRM Provider is released.
The AzureAD Data Sources and Resources have been moved to the new AzureAD Provider, as such this Data Source will be removed in v2.0 of the AzureRM Provider.
A guide on how to migrate to using the new Provider can be found here.
The AzureAD Data Sources and Resources have been moved to the new AzureAD Provider, as such this Data Source will be removed in v2.0 of the AzureRM Provider.
A guide on how to migrate to using the new Provider can be found here.
The deprecated field sku
will be removed in favour of the sku_name
property.
The deprecated fields service_principal_object_id
and service_principal_application_id
will be removed. They have been replaced with the object_id
and client_id
respectively.
The deprecated field zone_type
will be removed. Private DNS Zones are now a separate resource in both Azure and Terraform.
The deprecated field dns_prefix
within the agent_pool_profile
block will be removed.
The deprecated field internal_fqdn
will be removed.
Azure Scheduler is being retired in favour of Logic Apps (more information can be found here) - as such this Data Source will be removed.
The deprecated field address_space
will be removed.
The deprecated field sku
will be removed in favour of the sku_name
property.
The deprecated field disable_backend_ssl30
will be removed in favour of the enable_backend_ssl30
property.
The deprecated field disable_backend_tls10
will be removed in favour of the enable_backend_tls10
property.
The deprecated field disable_backend_tls11
will be removed in favour of the enable_backend_tls11
property.
The deprecated field disable_frontend_ssl30
will be removed in favour of the enable_frontend_ssl30
property.
The deprecated field disable_frontend_tls10
will be removed in favour of the enable_frontend_tls10
property.
The deprecated field disable_frontend_tls11
will be removed in favour of the enable_frontend_tls11
property.
The deprecated field disable_triple_des_chipers
will be removed in favour of the enable_triple_des_ciphers
property.
The deprecated field disable_triple_des_ciphers
will be removed in favour of the enable_triple_des_ciphers
property.
The fields in the properties
block (app_service_environment_id
, reserved
and per_site_scaling
) have been moved to the top level - as such the properties
block will be removed.
The deprecated fqdn_list
field in the backend_address_pool
block will be removed in favour of the fqdns
field, which is available from v1.22 of the AzureRM Provider.
The deprecated ip_address_list
field in the backend_address_pool
block will be removed in favour of the ip_addresses
field, which is available from v1.22 of the AzureRM Provider.
The deprecated account_name
field will be removed. This has been deprecated in favour of the automation_account_name
field.
The AzureAD Data Sources and Resources have been moved to the new AzureAD Provider, as such this Resource will be removed in v2.0 of the AzureRM Provider.
A guide on how to migrate to using the new Provider can be found here.
The AzureAD Data Sources and Resources have been moved to the new AzureAD Provider, as such this Resource will be removed.
A guide on how to migrate to using the new Provider can be found here.
The AzureAD Data Sources and Resources have been moved to the new AzureAD Provider, as such this Resource will be removed.
A guide on how to migrate to using the new Provider can be found here.
The azurerm_connection_monitor
resource will be deprecated in favour of a new resources azurerm_network_connection_monitor
.
The deprecated port
and protocol
fields in the container
block will be removed. These fields have been moved into the ports
block within the ports
field.
The deprecated command
field in the container
block will be removed. This has been replaced by the commands
field in the container
block.
The deprecated storage_account
block will be removed. This has been replaced by the storage_account_id
field and is only applicable to Classic
Container Registries.
Azure Container Service (ACS) is being Deprecated in favour of Azure Kubernetes Service (AKS) (more information can be found here), in preparation the resource will be removed.
The deprecated failover_policy
block will be removed. This has been replaced by the geo_location
block.
The azurerm_ddos_protection_planr
resource will be deprecated in favour of a new resources azurerm_network_ddos_protection_plan
.
The preference
field in the record
block will change from a String to an Integer to better reflect the API.
The deprecated record
field will be removed. This has been replaced by the records
field which accepts multiple values.
The deprecated zone_type
field will be removed. This has been replaced by the azurerm_private_dns_zone
resource.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated internal_public_ip_address_id
field in the ip_configuration
block will be removed. This field has been replaced by the public_ip_address_id
field in the ip_configuration
block.
The deprecated dns_prefix
field in the agent_pool_profile
block will be removed. This field has been removed by Azure and is no longer used.
The deprecated fqdn
field in the agent_pool_profile
block will be removed. This has been replaced by the top-level field fqdn
.
The service_principal
will be changing from a Set to a List, which will allow Terraform to better detect when the values have changed locally and as such can detect when this needs to be recreated.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The resource_id
field has been moved from the linked_service_properties
block to the top-level.
The linked_service_properties
block will be removed, since it's no longer required.
This resource has been renamed to azurerm_log_analytics_linked_service
which is available from v1.22 of the AzureRM Provider - instructions on how to migrate are available in this guide. As such this resource will be removed.
The deprecated elastic_pool_properties
block will be removed. The fields inside this block have been moved to the top-level.
The application_gateway_backend_address_pools_ids
field in the ip_configuration
block will been removed. This has been replaced by the azurerm_network_interface_application_gateway_backend_address_pool_association
resource.
The application_security_group_ids
field in the ip_configuration
block will been removed. This has been replaced by the azurerm_network_interface_application_security_group_association
resource.
The load_balancer_backend_address_pools_ids
field in the ip_configuration
block will been removed. This has been replaced by the azurerm_network_interface_backend_address_pool_association
resource.
The load_balancer_inbound_nat_rules_ids
field in the ip_configuration
block will been removed. This has been replaced by the azurerm_network_interface_nat_rule_association
resource.
The azurerm_packet_capture
resource will be deprecated in favour of a new resources azurerm_network_packet_capture
.
The deprecated public_ip_address_allocation
field will be removed. This field has been replaced by allocation_method
.
Azure Scheduler is being retired in favour of Logic Apps (more information can be found here) - as such this Resource will be removed in v2.0 of the AzureRM Provider.
Azure Scheduler is being retired in favour of Logic Apps (more information can be found here) - as such this Resource will be removed in v2.0 of the AzureRM Provider.
The deprecated location
field will be removed, since this is no longer used.
The deprecated enable_batched_operations
field will be removed, since this is no longer used.
The deprecated support_ordering
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated dead_lettering_on_filter_evaluation_exceptions
field will be removed, since this is no longer used.
The deprecated location
field will be removed, since this is no longer used.
The deprecated enable_filtering_messages_before_publishing
field will be removed, since this is no longer used.
The deprecated account_type
field will be removed. This has been split into the fields account_tier
and account_replication_type
.
The deprecated attempts
field will be removed, since Terraform now handles retries automatically.
The deprecated resource_group_name
field will be removed, since this is no longer used.
The deprecated resource_group_name
field will be removed, since this is no longer used.
The deprecated properties
block will be removed.
The deprecated resource_group_name
field will be removed, since this is no longer used.
The deprecated resource_group_name
field will be removed, since this is no longer used.
The deprecated resource_group_name
field will be removed, since this is no longer used.
The deprecated field network_security_group_id
will be removed. This has been replaced by the azurerm_subnet_network_security_group_association
resource.
The deprecated field route_table_id
will be removed. This has been replaced by the azurerm_subnet_route_table_association
resource.
The azurerm_virtual_machine
resource will be deprecated in favour of two new resources: azurerm_linux_virtual_machine
and azurerm_windows_virtual_machine
.
Splitting the Virtual Machine resource in two allows us to both provide finer-grain validation for this resource and update the schema.
The existing azurerm_virtual_machine
Resource will continue to be available in it's current form, however it will eventually be deprecated and we recommend using the new resources going forward.
The azurerm_virtual_machine_scale_set
resource will be deprecated in favour of two new resources: azurerm_linux_virtual_machine_scale_set
and azurerm_windows_virtual_machine_scale_set
.
Splitting the Virtual Machine Scale Set resource in two allows us to both provide finer-grain validation for this resource and update the schema.
The existing azurerm_virtual_machine_scale_set
Resource will continue to be available in it's current form, however it will eventually be deprecated and we recommend using the new resources going forward.
The deprecated field linked_service_properties
will be removed. This has been replaced by the resource_id
resource.
The deprecated field linked_service_properties
will be removed. This has been replaced by the resource_id
resource.
We've spent the past few months laying the groundwork for these changes - and whilst we appreciate that your Terraform Configurations may require code changes to upgrade to 2.0 - we take Semantic Versioning seriously and so try our best to limit these changes to major versions.
You can follow along with the work in the 2.0 release in this GitHub Milestone - and in this GitHub Issue.