Dynamic Backend Blocks with OpenTofu

This post is part of a series on Terraform State.

One of the significant advantages OpenTofu brings to the Infrastructure as Code landscape, setting it apart from its predecessor Terraform, is the ability to use configuration variables directly within the backend block. This feature — often called a "dynamic backend block" — provides flexibility for managing state, especially in complex or multi-environment setups.

In Terraform, the backend configuration has traditionally been static, requiring workarounds like generating backend configuration files dynamically or relying heavily on command-line flags during terraform init, like -backend-config as mentioned in this blog. OpenTofu eliminates this rigidity, allowing you to define backend parameters using input variables and local values.

Why Dynamic Backends Matter

The ability to dynamically configure your backend opens up several powerful use cases:

• Multi-environment deployments: Easily switch between different state backends (e.g., S3 buckets, Azure Storage containers) for development, staging, and production without modifying your core OpenTofu configuration files.
• Region-specific state: Store state in regions corresponding to your infrastructure deployments, improving latency and data residency compliance.
• Dynamic credentials: Pass sensitive credentials for backend access via variables, avoiding hardcoding them in your configuration.
• Simplified CI/CD pipelines: Streamline automation by allowing CI/CD systems to inject backend configurations based on pipeline variables or environment-specific logic.

How to Use Variables in OpenTofu Backends

1. Using Input Variables

You can define variables and then reference them directly within your backend block.

variable "env" {
  description = "The deployment environment (e.g., dev, prod)"
  type        = string
  default     = "dev"
}
 
variable "aws_region" {
  description = "The AWS region for state storage"
  type        = string
  default     = "us-east-1"
}
 
terraform {
  backend "s3" {
    bucket  = "my-opentofu-state"
    key     = "path/to/my/state/${var.env}.tfstate"
    region  = var.aws_region
    encrypt = true
  }
}

In this example, the state file key is dynamically constructed based on the env variable, and aws_region is also pulled from a variable. You can set these via terraform.tfvars files, environment variables (TF_VAR_env), or command-line arguments (-var="env=prod").

2. Leveraging Local Values

Local values let you assign a name to an expression that can be used throughout your configuration, including the backend block. This is particularly useful for derived values.

variable "workspace_name" {
  description = "The name of the OpenTofu workspace"
  type        = string
}
 
locals {
  s3_bucket_prefix = "my-company-opentofu-states"
  s3_key_path      = "${local.s3_bucket_prefix}/${var.workspace_name}/terraform.tfstate"
  s3_region_map = {
    "us-west"    = "us-west-2"
    "eu-central" = "eu-central-1"
  }
  backend_region = local.s3_region_map[split("-", var.workspace_name)[0]]
}
 
terraform {
  backend "s3" {
    bucket  = local.s3_bucket_prefix
    key     = local.s3_key_path
    region  = local.backend_region
    encrypt = true
  }
}

Here, s3_bucket_prefix and s3_key_path are defined as locals for better readability and reusability. The example also derives backend_region from a portion of workspace_name using a map lookup.

3. Dynamic AWS Assume Role Credentials

This capability extends to sensitive information like assume_role blocks within an S3 backend.

variable "account_id" {
  description = "The AWS account ID for assuming a role"
  type        = string
}
 
terraform {
  backend "s3" {
    bucket = "my-secure-opentofu-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
    assume_role {
      role_arn = "arn:aws:iam::${var.account_id}:role/opentofu-backend-access"
    }
  }
}

This makes your backend configuration adaptable to different AWS accounts or environments without code changes.

Important Considerations

• tofu init requirement: Backend configuration is evaluated during tofu init. Any variables used in the backend block must be resolvable at init time. You can provide these values via:
  • -var command-line flags
  • -backend-config command-line flags (for partial configuration)
  • Environment variables (TF_VAR_NAME)
  • Note: terraform.tfvars files are not automatically loaded for backend configuration during init if the backend block itself depends on variables from them.
• No state references: You cannot reference values from the state or locals derived from the state within the backend block, since the backend must be initialized before the state is available.
• Security: Be mindful of how you pass sensitive information to backend configuration. Environment variables are generally preferred over hardcoding, especially in CI/CD environments.

OpenTofu's support for configuration variables in backend blocks is a powerful addition that significantly enhances the flexibility and maintainability of your IaC workflows. By embracing this feature, you can create more adaptable and robust OpenTofu configurations for diverse infrastructure environments.