Terraform initially shipped support for the Azure Stack Provider back in June 2018.
Version 1.0 of the azurestack Provider is a major release and as such includes some larger-scale changes which are outlined in this document.
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 azurestack Provider, like so:
provider "azurestack" {
version = "=1.0.0"
}
.. or to any 1.x release:
provider "azurestack" {
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 1.0 of the azurestack Provider is released - you can then upgrade to it by updating the version specified in the Provider block, like so:
provider "azurestack" {
version = "=1.0.0"
}
At a high level, version 1.0 to includes the following changes:
arm_endpoint
property was deprecated in favour of the metadata_host
property.timeouts
block.Each of these topics is covered in more detail below.
arm_endpoint
property has been replaced with metadata_host
The be more descriptive and better align with the AzureRM provider and the provider block property arm_endpoint
has been deprecated in favour of the metadata_host
property which expects a FQDN hostname instead of a URI. For instance if you were setting it in the provider block previously:
provider "azurestack" {
version = "~> 1.x"
arm_endpoint = "https://management.region.mystack.ca"
}
It woud now have to be:
provider "azurestack" {
version = "~> 1.x"
metadata_host = "management.region.mystack.ca"
}
Alternatively, if it was being set via environment variables:
export ARM_ARM_ENDPOINT="management.region.mystack.ca"
it would now be
export ARM_METADATA_HOST="management.region.mystack.ca"
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 Stack Provider allows Importing existing resources into the state (using terraform import
) for (almost) every resource.
Version 2.0 of the Azure Stack 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 azurestack 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 `azurestack_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.
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 Stack 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 azurestack_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 "azurestack_resource_group" "example" {
name = "example-resource-group"
location = "loc1"
timeouts {
create = "10m"
delete = "30m"
}
}
We intend to support the timeouts
block in version 1.0 of the Azure Stack 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 azurestack Provider.
We originally shipped support for the azurestack_virtual_machine
and azurestack_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:
azurestack_linux_virtual_machine
)azurestack_windows_virtual_machine
)azurestack_linux_virtual_machine_scale_set
)azurestack_windows_virtual_machine_scale_set
)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 azurestack_virtual_machine
and azurestack_virtual_machine_scale_set
resources would continue to be available throughout the v1.x
releases - but over time these will be deprecated in favour of the new resources and removed in v2.x
.
The Azure Stack Provider was first launched in June 2018 - 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 1.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 1.0 upgrade.
azurestack_*
All tags properties are no longer computed.
azurestack_network_interface
The application_security_group_ids
and enable_accelerated_networking
fields have been removed as they are not supported by Azure Stack.
azurestack_managed_disk
The zones
field has been removed as it is not supported by Azure Stack.
azurestack_subnet
The ip_configurations
field has been removed.
azurestack_managed_disk
The zones
property has been removed as it is no longer supported by Azure Stack.
azurestack_network_interface
The load_balancer_backend_address_pools_ids
, load_balancer_inbound_nat_rules_ids
, internal_fqdn
, and internal_dns_name_label
properties have been removed.
azurestack_storage_blob
The resource_group_name
property has been removed in favour of the azurestack_storage_account_id
property.
azurestack_storage_container
The resource_group_name
property has been removed in favour of the azurestack_storage_account_id
property.
azurestack_virtual_network_gateway_connection
The type
property no longer supports Vnet2Vnet
.
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 1.0 - we take Semantic Versioning seriously and so try our best to limit these changes to major versions.