Configuring Remote Backends

1. Declaring Backend Configuration

Property	Description	Default	Notes
backend	Defines the backend to use for storing Terraform state	local	Required for remote state management
address	URL of the remote backend service	None	Required for HTTP backends like Consul or S3
config	Configuration options specific to the backend type	Empty object	Passed as key-value pairs to the backend

Example: Declaring a remote backend in Terraform

terraform {
  backend "s3" {
    bucket = "my-terraform-state-bucket"
    key    = "prod/terraform.tfstate"
    region = "us-west-2"
  }
}

Note: Backend configuration must be declared at the top level of your Terraform configuration, outside any resource or data blocks.

2. Using S3 Backend

Option	Values	Notes
bucket	`string`	Name of the S3 bucket
key	`string`	Path to the state file in the bucket
region	`string`	AWS region where the bucket is located
access_key	`string`	AWS access key ID (optional)
secret_key	`string`	AWS secret access key (optional)
dynamodb_table	`string`	DynamoDB table for state locking (optional)
encrypt	`bool`	Enable server-side encryption of the state file

Example: S3 Backend Configuration

backend "s3" {
  bucket        = "my-terraform-state-bucket"
  key           = "prod/terraform.tfstate"
  region        = "us-west-2"
  access_key    = "<AWS_ACCESS_KEY>"
  secret_key    = "<AWS_SECRET_KEY>"
  dynamodb_table = "terraform-locks"
  encrypt       = true
}

Note: Ensure the IAM user or role has appropriate permissions to read/write to the S3 bucket and DynamoDB table.

3. Using Azure Blob Backend

Parameter	Description	Example Value
storage_account_name	Name of the Azure Storage account	`myterraformstorage`
container_name	Name of the blob container to use	`tfstate`
key	Path to the state file within the container	`prod/terraform.tfstate`
access_key	Storage account access key (recommended to use environment variables or Azure AD)	`...`
use_azuread_auth	Set to true to use Azure AD authentication instead of access key	`true`

Example: Basic Configuration with Access Key

terraform {
  backend "azurerm" {
    storage_account_name = "myterraformstorage"
    container_name       = "tfstate"
    key                  = "prod/terraform.tfstate"
    access_key           = "<storage-account-access-key>"
  }
}

Example: Configuration with Azure AD Authentication

terraform {
  backend "azurerm" {
    storage_account_name = "myterraformstorage"
    container_name       = "tfstate"
    key                  = "prod/terraform.tfstate"
    use_azuread_auth     = true
  }
}

Note: When using Azure AD authentication, ensure that the service principal or user has appropriate permissions to read and write to the blob container.

4. Using GCS Backend

Option	Values	Notes
bucket	`string`	Required. Name of the GCS bucket to use for state storage.
prefix	`string`	Optional. Prefix within the bucket to use for state files.
credentials	`string`	Optional. Path to service account key file or JSON credentials.
project	`string`	Optional. GCP project ID to use for authentication.
region	`string`	Optional. Region where the GCS bucket is located.
encryption_key	`string`	Optional. Path to a GCP KMS key for encryption.

Example: GCS Backend Configuration

backend "gcs" {
  bucket = "my-terraform-state-bucket"
  prefix = "prod/"
  credentials = "/path/to/service-account.json"
  project = "my-gcp-project"
  region = "us-central1"
  encryption_key = "/path/to/kms-key"
}

Note: Ensure the service account has storage.objectAdmin permissions on the bucket.

Warning: The GCS backend does not support lock or unlock operations natively. Use a separate locking mechanism like DynamoDB.

5. Configuring State Locking

Option	Values	Description
dynamodb_table	`"terraform-locks"`	Name of the DynamoDB table used for state locking
lock_table	`"terraform-locks"`	Alias for `dynamodb_table`, deprecated in favor of DEPRECATED `dynamodb_table`
retry_seconds	`15`	Number of seconds to wait before retrying a failed lock operation

Example: DynamoDB State Locking Configuration

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "us-west-2"

    dynamodb_table = "terraform-locks"
    retry_seconds  = 15
  }
}

Note: The DynamoDB table must be created manually or via a Terraform configuration before using it for state locking.

6. Migrating Backend Configuration

Migration Process Overview

Ensure all team members are aware of the migration and coordinate timing
Backup current state files and configuration
Update backend configuration in your Terraform code
Run terraform init to initialize the new backend
Verify that all resources are correctly migrated and accessible
Update any CI/CD pipelines or automation scripts to reflect new backend settings

Step	Description	Action Required
1. Backup State	Save local state files before migration	NEW Backup state files to secure location
2. Update Configuration	Modify backend block in Terraform config	Update `backend` section with new backend settings
3. Initialize New Backend	Run `terraform init` to switch backends	Execute command and confirm migration success
4. Validate Resources	Ensure all resources are accessible and up-to-date	Verify that state reflects current infrastructure
5. Update Automation	Adjust CI/CD pipelines or scripts	Update any automation to use new backend configuration

Example: Migrating from Local to S3 Backend

terraform {
  backend "s3" {
    bucket = "my-terraform-state-bucket"
    key    = "prod/terraform.tfstate"
    region = "us-west-2"
  }
}

Note: Migrating between backends can be a complex process. Always test the migration in a non-production environment first.

Warning: Ensure that all team members are aware of the migration to avoid concurrent changes during the process.

7. Using HTTP Backend

Option	Values	Notes
address	`"https://my-backend.example.com"`	URL of the HTTP backend server
lock_address	`"https://my-backend.example.com/locks"`	URL for state locking
unlock_address	`"https://my-backend.example.com/locks"`	URL for state unlocking
username	`"admin"`	Username for basic auth
password	`"secret"`	Password for basic auth
retry_max	`5`	Maximum number of retries for failed requests
retry_wait_min	`1`	Minimum wait time between retries (seconds)
retry_wait_max	`30`	Maximum wait time between retries (seconds)

Example: HTTP Backend Configuration

backend "http" {
  address = "https://my-backend.example.com"
  lock_address = "https://my-backend.example.com/locks"
  unlock_address = "https://my-backend.example.com/locks"
  username = "admin"
  password = "secret"
  retry_max = 5
  retry_wait_min = 1
  retry_wait_max = 30
}

Note: The HTTP backend requires a server that implements the Terraform state storage protocol. Ensure your server supports the necessary endpoints for state operations and locking.

8. Configuring Terraform Cloud Backend

Option	Values	Notes
cloud	`{}`	Configures Terraform Cloud/Enterprise backend
cloud.organization	`"myorg"`	Organization name in Terraform Cloud
cloud.workspaces.name	`"myworkspace"`	Workspace name in Terraform Cloud
cloud.workspaces.tags	`["tag1", "tag2"]`	Tags to apply to workspace (optional)
cloud.token	`"tfp.xxxxxx"`	Terraform Cloud API token (optional, can be set via env)

Example: Basic Terraform Cloud Backend Configuration

terraform {
  cloud {
    organization = "myorg"
    workspaces {
      name = "myworkspace"
    }
  }
}

Note: Ensure the TF_TOKEN_applying_terraform_cloud environment variable is set or the token is configured in ~/.terraformrc.

Warning: Changing the organization or workspace name after state initialization will cause Terraform to treat it as a new workspace.

9. Setting Backend Encryption

Option	Values	Notes
backend	`"s3"`	Specifies the backend type for remote state storage
encrypt	`true`	Enables server-side encryption for state files stored in S3
kms_key_id	`arn:aws:kms:us-east-1:123456789012:key/abcd1234-a1b2-c3d4-e5f6-7890ghij1234`	Optional KMS key ARN for SSE-KMS encryption
sse_algorithm	`"AES256"`	Server-side encryption algorithm (e.g., AES256, aws:kms)

Example: S3 Backend with Encryption

terraform {
  backend "s3" {
    bucket = "my-terraform-state-bucket"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"

    encrypt = true
    kms_key_id = "arn:aws:kms:us-east-1:123456789012:key/abcd1234-a1b2-c3d4-e5f6-7890ghij1234"
    sse_algorithm = "aws:kms"
  }
}

Note: Enabling encryption ensures that state files are securely stored and protected at rest in the remote backend.

10. Using Partial Backend Configuration

Property	Description	Example
backend	Defines the backend configuration for Terraform state storage	`backend "s3" {`
bucket	Name of the S3 bucket to store state files	`bucket = "my-terraform-state"`
key	Path within the bucket where state files are stored	`key = "prod/terraform.tfstate"`
region	AWS region where the S3 bucket is located	`region = "us-west-2"`
access_key	AWS access key ID for authentication (not recommended in config)	`access_key = "AKIAIOSFODNN7EXAMPLE"`
secret_key	AWS secret access key for authentication (not recommended in config)	`secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"`

Example: Partial Backend Configuration

terraform {
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "us-west-2"
  }
}

Note: Partial backend configurations allow you to define a base configuration that can be overridden or extended in different environments.