Update to docs for setting provider version (#10396)

README.md

@@ -9,13 +9,22 @@ Version 2.x of the AzureRM Provider requires Terraform 0.12.x and later.
 
 ## Usage Example
 
-```
+> When using the AzureRM Provider with Terraform 0.13 and later, the recommended approach is to declare Provider versions in the root module Terraform configuration, using a `required_providers` block as per the following example. For previous versions, please continue to pin the version within the provider block.
+
+```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
 # Configure the Microsoft Azure Provider
 provider "azurerm" {
- # We recommend pinning to the specific version of the Azure Provider you're using
- # since new versions are released frequently
- version = "=2.40.0"
-
  features {}
 
  # More information on the authentication methods supported by

website/docs/guides/2.0-upgrade-guide.html.markdown

@@ -36,15 +36,36 @@ provider "azurerm" {
 
 More information on [how to pin the version of a Terraform Provider being used can be found on the Terraform Website](https://www.terraform.io/docs/configuration/providers.html#provider-versions).
 
-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:
+To use version 2.0 and newer of the AzureRM Provider - you can upgrade to it in a controlled manner by updating the version specified in the Provider block, like so:
 
 ```hcl
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
  version = "=2.0.0"
  features {}
 }
 ```
 
+When using the AzureRM Provider with Terraform 0.13 and later, the recommended approach is to declare Provider versions in the root module Terraform configuration, using a `required_providers` block as per the following example:
+
+```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
+provider "azurerm" {
+ features {}
+}
+```
+
 ## What's available in Version 2.0 of the AzureRM Provider?
 
 At a high level, version 2.0 to includes the following changes:

website/docs/guides/azure_cli.html.markdown

@@ -83,9 +83,20 @@ Now that we're logged into the Azure CLI - we can configure Terraform to use the
 To configure Terraform to use the Default Subscription defined in the Azure CLI - we can use the following Provider block:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=1.44.0"
+ features {}
 }
 ```
 
@@ -98,9 +109,20 @@ At this point running either `terraform plan` or `terraform apply` should allow
 It's also possible to configure Terraform to use a specific Subscription - for example:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=1.44.0"
+ features {}
 
  subscription_id = "00000000-0000-0000-0000-000000000000"
 }
@@ -115,9 +137,20 @@ At this point running either `terraform plan` or `terraform apply` should allow
 If you're looking to use Terraform across Tenants - it's possible to do this by configuring the Tenant ID field in the Provider block, as shown below:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=1.44.0"
+ features {}
 
  subscription_id = "00000000-0000-0000-0000-000000000000"
  tenant_id = "11111111-1111-1111-1111-111111111111"

website/docs/guides/managed_service_identity.html.markdown

@@ -88,11 +88,23 @@ $ export ARM_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # only necessary for
 $ export ARM_MSI_ENDPOINT=$MSI_ENDPOINT # only necessary when the msi endpoint is different than the well-known one
 ```
 
-A provider block is _technically_ optional when using environment variables. Even so, we recommend defining a provider block so that you can pin or constrain the version of the provider being used:
+A provider block is _technically_ optional when using environment variables. Even so, we recommend defining provider blocks so that you can pin or constrain the version of the provider being used, and configure other optional settings:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- version = "~> 1.23"
+ features {}
 }
 ```
 
@@ -101,8 +113,20 @@ provider "azurerm" {
 It's also possible to configure a managed identity within the provider block:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- version = "~> 1.23"
+ features {}
 
  use_msi = true
  #...
@@ -112,8 +136,21 @@ provider "azurerm" {
 If you intend to configure a remote backend in the provider block, put `use_msi` outside of the backend block:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- version = "~> 1.23"
+ features {}
+
  use_msi = true
 
  backend "azurerm" {

website/docs/guides/migrating-to-azuread.html.markdown

@@ -20,22 +20,50 @@ This guide covers how to migrate from using the following Data Sources and Resou
 
 ## Updating the Provider block
 
-As the AzureAD and AzureRM Provider support the same authentication methods - it's possible to update the Provider block by setting the new Provider name and version, for example:
+As the AzureAD and AzureRM Provider support the same authentication methods, it's possible to simply add the AzureAD Provider to the `required_providers` block and declare the configuration in a Provider block as per the following example:
 
 ```hcl
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
 provider "azurerm" {
- version = "=1.44.0"
+ features {}
 }
 ```
 
 can become:
 
 ```hcl
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ azuread = {
+ source = "hashicorp/azuread"
+ version = "=1.3.0"
+ }
+ }
+}
+
+provider "azurerm" {
+ features {}
+}
+
 provider "azuread" {
- version = "=0.10.0"
+ features {}
 }
 ```
 
+> For modules containing only resources from the AzureAD Provider, we recommend that you also remove the AzureRM Provider settings.
+
 ## Updating the Terraform Configurations
 
 The Azure Active Directory Data Sources and Resources have been split out into the new Provider - which means the name of the Data Sources and Resources has changed slightly.

website/docs/guides/service_principal_client_certificate.html.markdown

@@ -99,12 +99,23 @@ $ export ARM_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
 $ export ARM_TENANT_ID="00000000-0000-0000-0000-000000000000"
 ```
 
-The following Provider block can be specified - where `1.44.0` is the version of the Azure Provider that you'd like to use:
+The following Terraform and Provider blocks can be specified - where `2.46.0` is the version of the Azure Provider that you'd like to use:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=1.44.0"
+ features {}
 }
 ```
 
@@ -122,9 +133,20 @@ It's also possible to configure these variables either in-line or from using var
 variable "client_certificate_path" {}
 variable "client_certificate_password" {}
 
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=1.44.0"
+ features {}
 
  subscription_id = "00000000-0000-0000-0000-000000000000"
  client_id = "00000000-0000-0000-0000-000000000000"

website/docs/guides/service_principal_client_secret.html.markdown

@@ -175,12 +175,22 @@ $ export ARM_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
 $ export ARM_TENANT_ID="00000000-0000-0000-0000-000000000000"
 ```
 
-The following Provider block can be specified - where `2.5.0` is the version of the Azure Provider that you'd like to use:
+The following Terraform and Provider blocks can be specified - where `2.46.0` is the version of the Azure Provider that you'd like to use:
 
 ```hcl
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=2.5.0"
  features {}
 }
 ```
@@ -199,16 +209,25 @@ It's also possible to configure these variables either in-line or from using var
 variable "client_secret" {
 }
 
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
- version = "=2.4.0"
+ features {}
 
  subscription_id = "00000000-0000-0000-0000-000000000000"
  client_id = "00000000-0000-0000-0000-000000000000"
  client_secret = var.client_secret
  tenant_id = "00000000-0000-0000-0000-000000000000"
-
- features {}
 }
 ```
 

website/docs/index.html.markdown

@@ -28,10 +28,19 @@ We recommend using either a Service Principal or Managed Service Identity when r
 ## Example Usage
 
 ```hcl
-# Configure the Azure Provider
+# We strongly recommend using the required_providers block to set the
+# Azure Provider source and version being used
+terraform {
+ required_providers {
+ azurerm = {
+ source = "hashicorp/azurerm"
+ version = "=2.46.0"
+ }
+ }
+}
+
+# Configure the Microsoft Azure Provider
 provider "azurerm" {
- # whilst the `version` attribute is optional, we recommend pinning to a given version of the Provider
- version = "=2.40.0"
  features {}
 }