mirror of https://github.com/hashicorp/terraform
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
588 lines
43 KiB
588 lines
43 KiB
---
|
|
page_title: 'Backend Type: azurerm'
|
|
description: Terraform can store state remotely in Azure Blob Storage.
|
|
---
|
|
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
|
|
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
|
|
|
|
|
|
# azurerm
|
|
|
|
Stores the state as a Blob with the given Key within the Blob Container within [the Blob Storage Account](https://docs.microsoft.com/en-us/azure/storage/common/storage-introduction).
|
|
|
|
This backend supports state locking and consistency checking with Azure Blob Storage native capabilities.
|
|
|
|
## Authentication
|
|
|
|
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/backend#credentials-and-sensitive-data) for details.
|
|
|
|
The `azurerm` backend needs to authenticate to the storage account data plane in order to manipulate the state file blob in the storage account container. In order to do that, it needs to authenticate and to know the data plane URI for the storage account.
|
|
|
|
The `azurerm` backend supports 5 methods to authenticate to the storage account data plane:
|
|
|
|
- [Azure Active Directory](#azure-active-directory) **(Recommended)**
|
|
- [SAS Token](#sas-token) *(Not recommended for new workloads)*
|
|
- [Access Key](#access-key) *(Not recommended for new workloads)*
|
|
- [Access Key Lookup](#access-key-lookup) *(Not recommended for new workloads)*
|
|
|
|
### Azure Active Directory and Access Key Lookup Authentication Types
|
|
|
|
There are 5 types of Azure Active Directory authentication supported, which apply to the Azure Active Directory and Access Key Lookup methods.
|
|
|
|
- OpenID Connect / Workload identity federation **(Recommended)**
|
|
- User Assigned Managed Identity with Federated Credentials **(Recommended)**
|
|
- Service Princial / App Registration with Federated Credentials
|
|
- User or System Assigned Managed Identity
|
|
- User Assigned Managed Identity attached to Azure compute instance (agent / runner)
|
|
- System Assigned Managed Identity attached to Azure compute instance (agent / runner)
|
|
- Service Principal / App Registration with Client Secret
|
|
- Service Principal / App REgistration with Client Certificate
|
|
- User Account with Azure CLI only (for local development cycle)
|
|
|
|
These types can be supplied via inputs or via a pre-authenticated Azure CLI. We cover them in more depth in the following sections.
|
|
|
|
### Data Plane URI
|
|
|
|
In most cases, you can infer the data plane URI from the `storage_account_name` and `container_name`. Refer to the [storage account overview documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview#standard-endpoints) for more information on the standard endpoints.
|
|
|
|
If you are using the ['Azure DNS zone endpoints' feature](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-overview#azure-dns-zone-endpoints-preview), the backend will need to lookup the data plane URI from the management plane. This requires that you set the `lookup_blob_endpoint` configuration option to `true` and the `Reader` role assignment on the storage account.
|
|
|
|
## Azure Active Directory
|
|
|
|
This method requires a valid Azure Active Directory principal and a predictable storage account data plane URI.
|
|
|
|
### Required Configuration Options
|
|
|
|
The following configuration options are always required for this method:
|
|
|
|
- `use_azuread_auth` - Set to `true` to use Azure Active Directory authentication to the storage account data plane. This can also be set via the `ARM_USE_AZUREAD` environment variable.
|
|
- `tenant_id` - The tenant ID of the Azure Active Directory principal is required to authenticate to the storage account data plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_TENANT_ID` environment variable.
|
|
- `storage_account_name` - The name of the storage account to write the state file blob to.
|
|
- `container_name` - The name of the storage account container to write the state file blob to.
|
|
- `key` - The name of the blob within the storage account container to write the state file to.
|
|
|
|
### Optional Inputs
|
|
|
|
These optional configuration options apply when [looking up the data plane URI](#data-plane-uri) from the management plane. They are not required when the data plane URI can be inferred from the `storage_account_name` and `container_name`.
|
|
|
|
- `lookup_blob_endpoint` - Set to `true` to lookup the storage account data plane URI from the management plane. This is required if you are using the 'Azure DNS zone endpoints' feature. Defaults to `false`. This value can also be sourced from the `ARM_USE_DNS_ZONE_ENDPOINT` environment variable.
|
|
- `subscription_id` - The subscription ID of the storage account is required to query the management plane. This is only required if `lookup_blob_endpoint` is set to `true`. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_SUBSCRIPTION_ID` environment variable.
|
|
- `resource_group_name` - The resource group name of the storage account is required to query the management plane. This is only required if `lookup_blob_endpoint` is set to `true`.
|
|
|
|
### Storage Account Required Role Assignments
|
|
|
|
The recommended data plane role assignments required for this method are either one of:
|
|
|
|
- `Storage Blob Data Owner` on the storage account container (Recommended)
|
|
- `Storage Blob Data Contributor` on the storage account
|
|
|
|
The recommended management plane role assignments required for this method are:
|
|
|
|
- `Reader` on the storage account *(Only required if `lookup_blob_endpoint` is set to `true`)*
|
|
|
|
### Azure Active Directory with OpenID Connect / Workload identity federation
|
|
|
|
#### Required Configuration Options
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `use_oidc` - Set to `true` to use OpenID Connect / Workload identity federation to authenticate to the storage account data plane. This can also be set via the `ARM_USE_OIDC` environment variable.
|
|
- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration or User Assigned Managed Identity is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
|
|
|
|
#### Example Configuration for GitHub
|
|
|
|
With GitHub, the ID Token environment variables are automatically found, so no further settings are required.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_oidc = true # Can also be set via `ARM_USE_OIDC` environment variable.
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Example Configuration for Azure DevOps
|
|
|
|
With Azure DevOps, the ID Token endpoint environment variables are automatically found, but you need to supply the service connection ID in `oidc_azure_service_connection_id`. If you are using the `AzureCLI` or `AzurePowerShell` tasks, the service connection ID is automatically set to the `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID` environment variable.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_oidc = true # Can also be set via `ARM_USE_OIDC` environment variable.
|
|
oidc_azure_service_connection_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_OIDC_AZURE_SERVICE_CONNECTION_ID` environment variable.
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Azure Active Directory with Compute Attached Managed Identity
|
|
|
|
#### Required Configuration Options
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `use_msi` - Set to `true` to use the managed identity to authenticate to the storage account data plane. This can also be set via the `ARM_USE_MSI` environment variable.
|
|
|
|
#### Optional Configuration Options
|
|
|
|
The following additional configuration options are optional for this sub-type:
|
|
|
|
- `client_id` - The client ID of the User Assigned Managed Identity is required to authenticate to the storage account data plane. This is not required for System Assigned Managed Identity. This can also be set via the `ARM_CLIENT_ID` environment variable.
|
|
|
|
#### Example Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_msi = true # Can also be set via `ARM_USE_MSI` environment variable.
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable. Not required for System Assigned Managed Identity.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Azure Active Directory with Azure CLI
|
|
|
|
You must have a pre-authenticated Azure CLI session using any supported method.
|
|
|
|
#### Required Configuration Options
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `use_cli` - Set to `true` to use the Azure CLI session authenticate to the storage account data plane. This can also be set via the `ARM_USE_CLI` environment variable.
|
|
|
|
#### Example Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_cli = true # Can also be set via `ARM_USE_CLI` environment variable.
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable. Azure CLI will fallback to use the connected tenant ID if not supplied.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Azure Active Directory with Client Secret
|
|
|
|
Terraform retains this method for backwards compatibility only, do not use it for any new workloads.
|
|
|
|
~> **Warning!** This method requires you to manage and rotate a secret. Use OpenID Connect / Workload identity federation as a more secure approach.
|
|
|
|
#### Required Inputs
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
|
|
- `client_secret` - The client secret of the Azure Active Directory Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_SECRET` environment variable.
|
|
|
|
#### Example Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
client_secret = "************************************" # Can also be set via `ARM_CLIENT_SECRET` environment variable.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Azure Active Directory with Client Certificate
|
|
|
|
Terraform retains this method for backwards compatibility only, do not use it for any new workloads.
|
|
|
|
~> **Warning!** This method requires you to manage and rotate a secret. Use OpenID Connect / Workload identity federation as a more secure approach.
|
|
|
|
#### Required Inputs
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
|
|
- `client_certificate_path` - The path to the client certificate bundle is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_CERTIFICATE_PATH` environment variable.
|
|
- `client_certificate_password` - The password for the client certificate bundle is required to authenticate to the storage account data plane. This can also be set via the `ARM_CLIENT_CERTIFICATE_PASSWORD` environment variable.
|
|
|
|
#### Example Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
client_certificate_path = "/path/to/bundle.pfx" # Can also be set via `ARM_CLIENT_CERTIFICATE_PATH` environment variable.
|
|
client_certificate_password = "************************************" # Can also be set via `ARM_CLIENT_CERTIFICATE_PASSWORD` environment variable.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
## Access Key
|
|
|
|
This method requires you find the Access Key for the storage account and supply it to the backend configuration.
|
|
|
|
The Access Key is then used to directly authenticate to the storage account data plane.
|
|
|
|
Terraform retains this method for backwards compatibility, we do not recommend it for new workloads.
|
|
|
|
### Required Configuration Options
|
|
|
|
The following configuration options are always required for this method:
|
|
|
|
- `access_key` - The Access Key of the storage account is required to authenticate to the storage account data plane. This can also be set via the `ARM_ACCESS_KEY` environment variable.
|
|
- `storage_account_name` - The name of the storage account to write the state file blob to.
|
|
- `container_name` - The name of the storage account container to write the state file blob to.
|
|
- `key` - The name of the blob within the storage account container to write the state file to.
|
|
|
|
### Storage Account Required Role Assignments
|
|
|
|
There are no role assignments required on the storage account for this method as the Access Key is used to authenticate to the data plane.
|
|
|
|
### Example Configuration
|
|
|
|
~> **Warning!** This method requires you to manage and rotate a secret. Consider using OIDC as a more secure approach.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
access_key = "abcdefghijklmnopqrstuvwxyz0123456789..." # Can also be set via `ARM_ACCESS_KEY` environment variable.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
## SAS Token
|
|
|
|
This method requires you generate a SAS Token for the storage account container or blob and supply it to the backend configuration.
|
|
|
|
The SAS Token is then used to directly authenticate to the storage account data plane.
|
|
|
|
Terraform retains this method for backwards compatibility, we do not recommend it for new workloads.
|
|
|
|
### Required Configuration Options
|
|
|
|
The following configuration options are always required for this method:
|
|
|
|
- `sas_token` - The SAS Token for the storage account container or blob is required to authenticate to the storage account data plane. This can also be set via the `ARM_SAS_TOKEN` environment variable.
|
|
- `storage_account_name` - The name of the storage account to write the state file blob to.
|
|
- `container_name` - The name of the storage account container to write the state file blob to.
|
|
- `key` - The name of the blob within the storage account container to write the state file to.
|
|
|
|
### Storage Account Required Permissions
|
|
|
|
The SAS Token requires `write` and `list` permissions on the container or blob.
|
|
|
|
### Example Configuration
|
|
|
|
~> **Warning!** This method requires you to manage and rotate a secret. Consider using OIDC as a more secure approach.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
sas_token = "abcdefghijklmnopqrstuvwxyz0123456789..." # Can also be set via `ARM_SAS_TOKEN` environment variable.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
## Access Key Lookup
|
|
|
|
This method requires a valid Azure Active Directory principal and is a fallback for when Azure Active Directory authentication cannot be used on the storage account data plane.
|
|
|
|
This method queries the management plane to get the storage account Access Key and then uses that Access Key to authenticate to the storage account data plane. It requires elevated permissions on the storage account.
|
|
|
|
Terraform retains this method for backwards compatibility, we do not recommend it for new workloads.
|
|
|
|
### Required Configuration Options
|
|
|
|
The following configuration options are always required for this method:
|
|
|
|
- `tenant_id` - The tenant ID of the Azure Active Directory principal is required to authenticate to the storage account management and data plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_TENANT_ID` environment variable.
|
|
- `subscription_id` - The subscription ID of the storage account is required to query the management plane. If using Azure CLI, this can be inferred from the CLI session. This can also be set via the `ARM_SUBSCRIPTION_ID` environment variable.
|
|
- `resource_group_name` - The resource group name of the storage account is required to query the management plane.
|
|
- `storage_account_name` - The name of the storage account to write the state file blob to.
|
|
- `container_name` - The name of the storage account container to write the state file blob to.
|
|
- `key` - The name of the blob within the storage account container to write the state file to.
|
|
|
|
### Optional Configuration Options
|
|
|
|
These optional configuration options apply when [looking up the data plane URI](#data-plane-uri) from the management plane. They are not required when the data plane URI can be inferred from the `storage_account_name` and `container_name`.
|
|
|
|
- `lookup_blob_endpoint` - Set to `true` to lookup the storage account data plane URI from the management plane. This is required if you are using the 'Azure DNS zone endpoints' feature. Defaults to `false`. This value can also be sourced from the `ARM_USE_DNS_ZONE_ENDPOINT` environment variable.
|
|
|
|
### Storage Account Required Role Assignments
|
|
|
|
The recommended data plane role assignments required for this method are either one of:
|
|
|
|
- `Storage Blob Data Owner` on the storage account container (Recommended)
|
|
- `Storage Blob Data Contributor` on the storage account
|
|
|
|
The recommended management plane role assignments required for this method are:
|
|
|
|
- `Reader` on the storage account
|
|
- `Storage Account Key Operator Service Role` on the storage account
|
|
|
|
### Access Key Lookup with OpenID Connect / Workload identity federation
|
|
|
|
OpenID Connect / Workload identity federation is the recommended method for this scenario.
|
|
|
|
#### Required Configuration Options
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `use_oidc` - Set to `true` to use OpenID Connect / Workload identity federation to authenticate to the storage account management and data plane. This can also be set via the `ARM_USE_OIDC` environment variable.
|
|
- `client_id` - The client ID of the Azure Active Directory Service Principal / App Registration or User Assigned Managed Identity is required to authenticate to the storage account management and data plane. This can also be set via the `ARM_CLIENT_ID` environment variable.
|
|
|
|
#### Example Configuration for GitHub
|
|
|
|
With GitHub, the ID Token environment variables are automatically found, so no further settings are required.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_oidc = true # Can also be set via `ARM_USE_OIDC` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
subscription_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_SUBSCRIPTION_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
resource_group_name = "StorageAccount-ResourceGroup" # Can be passed via `-backend-config=`"resource_group_name=<resource group name>"` in the `init` command.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Example Configuration for Azure DevOps
|
|
|
|
With Azure DevOps, the ID Token endpoint environment variables are automatically found, but you need to supply the service connection ID in `oidc_azure_service_connection_id`. If you are using the `AzureCLI` or `AzurePowerShell` tasks, the service connection ID is automatically set to the `AZURESUBSCRIPTION_SERVICE_CONNECTION_ID` environment variable.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_oidc = true # Can also be set via `ARM_USE_OIDC` environment variable.
|
|
oidc_azure_service_connection_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_OIDC_AZURE_SERVICE_CONNECTION_ID` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
subscription_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_SUBSCRIPTION_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
resource_group_name = "StorageAccount-ResourceGroup" # Can be passed via `-backend-config=`"resource_group_name=<resource group name>"` in the `init` command.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Access Key Lookup with Compute Attached Managed Identity
|
|
|
|
#### Required Configuration Options
|
|
|
|
The following additional configuration options are always required for this sub-type:
|
|
|
|
- `use_msi` - Set to `true` to use the managed identity to authenticate to the storage account data plane. This can also be set via the `ARM_USE_MSI` environment variable.
|
|
|
|
#### Optional Configuration Options
|
|
|
|
The following additional configuration options are optional for this sub-type:
|
|
|
|
- `client_id` - The client ID of the User Assigned Managed Identity is required to authenticate to the storage account data plane. This is not required for System Assigned Managed Identity. This can also be set via the `ARM_CLIENT_ID` environment variable.
|
|
|
|
#### Example Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_msi = true # Can also be set via `ARM_USE_MSI` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
subscription_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_SUBSCRIPTION_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable. Not required for System Assigned Managed Identity.
|
|
resource_group_name = "StorageAccount-ResourceGroup" # Can be passed via `-backend-config=`"resource_group_name=<resource group name>"` in the `init` command.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Access Key Lookup with Azure CLI
|
|
|
|
You must have a pre-authenticated Azure CLI session using any supported method.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
use_cli = true # Can also be set via `ARM_USE_CLI` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable. Azure CLI will fallback to use the connected tenant ID if not supplied.
|
|
subscription_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_SUBSCRIPTION_ID` environment variable. Azure CLI will fallback to use the connected subscription ID if not supplied.
|
|
resource_group_name = "StorageAccount-ResourceGroup" # Can be passed via `-backend-config=`"resource_group_name=<resource group name>"` in the `init` command.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Access Key Lookup with Client Secret
|
|
|
|
Terraform retains this method for backwards compatibility only, do not use it for any new workloads.
|
|
|
|
~> **Warning!** This method requires you to manage and rotate a secret. Use OpenID Connect / Workload identity federation as a more secure approach.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
subscription_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_SUBSCRIPTION_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
client_secret = "************************************" # Can also be set via `ARM_CLIENT_SECRET` environment variable.
|
|
resource_group_name = "StorageAccount-ResourceGroup" # Can be passed via `-backend-config=`"resource_group_name=<resource group name>"` in the `init` command.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
### Access Key Lookup with Client Certificate
|
|
|
|
Terraform retains this method for backwards compatibility only, do not use it for any new workloads.
|
|
|
|
~> **Warning!** This method requires you to manage and rotate a secret. Use OpenID Connect / Workload identity federation as a more secure approach.
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "azurerm" {
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
subscription_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_SUBSCRIPTION_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
client_certificate_path = "/path/to/bundle.pfx" # Can also be set via `ARM_CLIENT_CERTIFICATE_PATH` environment variable.
|
|
client_certificate_password = "************************************" # Can also be set via `ARM_CLIENT_CERTIFICATE_PASSWORD` environment variable.
|
|
resource_group_name = "StorageAccount-ResourceGroup" # Can be passed via `-backend-config=`"resource_group_name=<resource group name>"` in the `init` command.
|
|
storage_account_name = "abcd1234" # Can be passed via `-backend-config=`"storage_account_name=<storage account name>"` in the `init` command.
|
|
container_name = "tfstate" # Can be passed via `-backend-config=`"container_name=<container name>"` in the `init` command.
|
|
key = "prod.terraform.tfstate" # Can be passed via `-backend-config=`"key=<blob key name>"` in the `init` command.
|
|
}
|
|
}
|
|
```
|
|
|
|
## terraform_remote_state Data Source
|
|
|
|
To use the `terraform_remote_state` data source with the `azurerm` backend, you must use the exact same configuration as you would for the `backend` block in your configuration.
|
|
|
|
For example to use [Direct Azure Active Directory authentication with OpenID Connect / Workload identity federation for GitHub](#azure-active-directory-with-openid-connect--workload-identity-federation) you would use the following configuration:
|
|
|
|
```hcl
|
|
data "terraform_remote_state" "foo" {
|
|
backend = "azurerm"
|
|
config = {
|
|
use_oidc = true # Can also be set via `ARM_USE_OIDC` environment variable.
|
|
use_azuread_auth = true # Can also be set via `ARM_USE_AZUREAD` environment variable.
|
|
tenant_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_TENANT_ID` environment variable.
|
|
client_id = "00000000-0000-0000-0000-000000000000" # Can also be set via `ARM_CLIENT_ID` environment variable.
|
|
storage_account_name = "abcd1234" # There is not environment variable support for this input.
|
|
container_name = "tfstate" # There is not environment variable support for this input.
|
|
key = "prod.terraform.tfstate" # There is not environment variable support for this input.
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration Variables
|
|
|
|
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/backend#credentials-and-sensitive-data) for details.
|
|
|
|
For more information on when each of these configuration settings is required, refer to the previous sections of this page.
|
|
|
|
The following configuration options are supported:
|
|
|
|
* `storage_account_name` - (Required) The Name of [the Storage Account](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_account).
|
|
|
|
* `container_name` - (Required) The Name of [the Storage Container](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_container) within the Storage Account.
|
|
|
|
* `key` - (Required) The name of the Blob used to retrieve/store Terraform's State file inside the Storage Container.
|
|
|
|
* `environment` - (Optional) The Azure Environment which should be used. This can also be sourced from the `ARM_ENVIRONMENT` environment variable. Possible values are `public`, `china` and `usgovernment`. Defaults to `public`.
|
|
|
|
* `metadata_host` - (Optional) The Hostname of the Azure Metadata Service (for example `management.azure.com`), used to obtain the Cloud Environment when using a Custom Azure Environment. This can also be sourced from the `ARM_METADATA_HOSTNAME` Environment Variable.
|
|
|
|
* `lookup_blob_endpoint` - (Optional) Set to `true` to look up the Storage Account Data Plane URI from the Management Plane. Defaults to `false`. This value can also be sourced from the `ARM_USE_DNS_ZONE_ENDPOINT` environment variable.
|
|
|
|
* `snapshot` - (Optional) Set to `true` to snapshot the Blob used to store the Terraform state file before use. Defaults to `false`. This value can also be sourced from the `ARM_SNAPSHOT` environment variable.
|
|
|
|
* `tenant_id` - (Optional) The Tenant ID of the principal. This can also be sourced from the `ARM_TENANT_ID` environment variable.
|
|
|
|
* `use_azuread_auth` - (Optional) Whether Azure Active Directory Authentication for storage account data plane authentication. This can also be sourced from the `ARM_USE_AZUREAD` environment variable.
|
|
|
|
* `subscription_id` - (Optional) The Subscription ID of the storage account required for management plane authentication. This can also be sourced from the `ARM_SUBSCRIPTION_ID` environment variable.
|
|
|
|
* `resource_group_name` - (Optional) The Name of the Resource Group in which the Storage Account exists required for management plane authentication.
|
|
|
|
* `access_key` - (Optional) The Access Key used to authenticate to the storage account data plane with the [Direct Access Key](#direct-access-key) authenticaton method. This can also be sourced from the `ARM_ACCESS_KEY` environment variable.
|
|
|
|
* `sas_token` - (Optional) The SAS Token used to authenticate to the storage account data plane with the [Direct SAS Token](#direct-sas-token) authentication method. This can also be sourced from the `ARM_SAS_TOKEN` environment variable.
|
|
|
|
* `use_cli` - (Optional) Set to `true` to use the Azure CLI session for authentication to the storage account management and data plane. This value can also be sourced from the `ARM_USE_CLI` environment variable.
|
|
|
|
* `use_oidc` - (Optional) Set to `true` to use OpenID Connect / Workload identity federation authentication for authentication to the storage account management and data plane. This can also be sourced from the `ARM_USE_OIDC` environment variable.
|
|
|
|
* `client_id` - (Optional) The Client ID of the Azure Active Directory Principal required for some authentication sub-types. This can also be sourced from the `ARM_CLIENT_ID` environment variable.
|
|
|
|
* `ado_pipeline_service_connection_id` - (Optional) The Azure DevOps Pipeline Service Connection ID required for Open ID Connect / Workload identity federation authentication with Azure DevOps. This can also be sourced from the `ARM_ADO_PIPELINE_SERVICE_CONNECTION_ID` or `ARM_OIDC_AZURE_SERVICE_CONNECTION_ID` environment variables. The provider will look for values in this order and use the first it finds configured.
|
|
|
|
* `oidc_request_url` - (Optional) The URL for the Open ID Connect provider from which to request an ID token. This is only required for advanced scenarios or third party integrations. This can also be sourced from the `ARM_OIDC_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_URL` or `SYSTEM_OIDCREQUESTURI` environment variables. The provider will look for values in this order and use the first it finds configured.
|
|
|
|
* `oidc_request_token` - (Optional) The bearer token for the request to the Open ID Connect provider. This is only required for advanced scenarios or third party integrations. This can also be sourced from the `ARM_OIDC_REQUEST_TOKEN`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` or `SYSTEM_ACCESSTOKEN` environment variables. The provider will look for values in this order and use the first it finds configured.
|
|
|
|
* `oidc_token` - (Optional) The ID Token when authenticating using OpenID Connect. This is only required for advanced scenarios or third party integrations. This can also be sourced from the `ARM_OIDC_TOKEN` environment variable.
|
|
|
|
* `oidc_token_file_path` - (Optional) The path to a file containing an ID token when authenticating using OpenID Connect. This is only required for advanced scenarios or third party integrations. This can also be sourced from the `ARM_OIDC_TOKEN_FILE_PATH` environment variable.
|
|
|
|
* `use_aks_workload_identity` (Optional) Set to `true` to use Azure AKS Workload Identity for authentication. This is only required for advanced scenarios or third party integrations. This can also be sourced from the `ARM_USE_AKS_WORKLOAD_IDENTITY` environment variable.
|
|
|
|
* `use_msi` - (Optional) Set to `true` to use a Compute Attached Managed Service Identity for authentication to the storage account management and data planes. This can also be sourced from the `ARM_USE_MSI` environment variable.
|
|
|
|
* `msi_endpoint` - (Optional) The path to a custom Managed Service Identity endpoint which is automatically determined if not specified. This can also be sourced from the `ARM_MSI_ENDPOINT` environment variable.
|
|
|
|
* `client_id_file_path` (Optional) The path to a file containing the Client ID which should be used. This can also be sourced from the `ARM_CLIENT_ID_FILE_PATH` Environment Variable.
|
|
|
|
* `client_certificate_password` - (Optional) The password associated with the Client Certificate specified in `client_certificate_path`. This can also be sourced from the `ARM_CLIENT_CERTIFICATE_PASSWORD` environment variable.
|
|
|
|
* `client_certificate_path` - (Optional) The path to the PFX file used as the Client Certificate when authenticating as a Service Principal. This can also be sourced from the `ARM_CLIENT_CERTIFICATE_PATH` environment variable.
|
|
|
|
* `client_certificate` - (Optional) Base64 encoded PKCS#12 certificate bundle to use when authenticating as a Service Principal using a Client Certificate. This can also be sourced from the `ARM_CLIENT_CERTIFICATE` environment variable.
|
|
|
|
* `client_id_file_path` (Optional) The path to a file containing the Client ID which should be used. This can also be sourced from the `ARM_CLIENT_ID_FILE_PATH` Environment Variable.
|
|
|
|
* `client_secret` - (Optional) The Client Secret of the Service Principal. This can also be sourced from the `ARM_CLIENT_SECRET` environment variable.
|
|
|
|
* `client_secret_file_path` - (Optional) The path to a file containing the Client Secret which should be used. This can also be sourced from the `ARM_CLIENT_SECRET_FILE_PATH` Environment Variable.
|