Terraform Cloud Variables

Introduction

When working with infrastructure as code, you'll frequently need to use configuration values that vary across environments or contain sensitive information. Terraform Cloud provides a robust variable management system that allows you to define, store, and secure these values without hardcoding them in your configuration files.

In this guide, we'll explore how Terraform Cloud Variables work, their types, and best practices for using them effectively in your infrastructure deployments.

Understanding Terraform Cloud Variables

Terraform Cloud Variables serve as a way to parameterize your Terraform configurations, providing values at runtime rather than embedding them directly in your code. This separation improves security, facilitates reuse, and enables environment-specific configurations.

Why Use Terraform Cloud Variables?

• Security: Store sensitive information like API keys and passwords securely
• Environment Management: Easily manage different values for development, staging, and production
• Collaboration: Share configurations without exposing sensitive values
• Automation: Support CI/CD workflows with variable sets and API-driven variable management

Types of Variables in Terraform Cloud

Terraform Cloud supports two primary types of variables:

1. Terraform Variables

These are the variables you typically define in your .tf files and pass values to. In Terraform Cloud, you can set these at the workspace level.

hcl

variable "instance_type" {
  description = "EC2 instance type"
  type        = string
  default     = "t2.micro"
}

2. Environment Variables

These are shell environment variables that are set when Terraform runs. They're commonly used for provider authentication (like AWS credentials).

bash

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Variable Attributes

Each variable in Terraform Cloud has several important attributes:

• Key: The variable name
• Value: The variable's value
• Description: A human-readable explanation of the variable's purpose
• Category: Either "terraform" or "env" (environment)
• Sensitive: A boolean flag indicating whether the value should be hidden in the UI and logs
• HCL: A boolean indicating if the value should be parsed as HCL code rather than a string

Setting Up Variables in Terraform Cloud

Let's walk through how to set up variables in Terraform Cloud:

Step 1: Navigate to Variables in Your Workspace

After creating a workspace in Terraform Cloud, navigate to the "Variables" tab:

1. Go to your Terraform Cloud organization
2. Select your workspace
3. Click on the "Variables" tab

Step 2: Add a Terraform Variable

Let's add a variable for an AWS region:

1. Click the "Add variable" button
2. Select "Terraform variable" as the category
3. Enter "aws_region" as the key
4. Enter "us-west-2" as the value
5. Add a description: "AWS region for resource deployment"
6. Click "Add variable"

Here's how this variable might be used in your Terraform configuration:

hcl

provider "aws" {
  region = var.aws_region
}

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
  tags = {
    Name = "Main VPC in ${var.aws_region}"
  }
}

Step 3: Add an Environment Variable

Now, let's add AWS credentials as environment variables:

1. Click "Add variable" again
2. Select "Environment variable" as the category
3. Enter "AWS_ACCESS_KEY_ID" as the key
4. Enter your access key as the value
5. Check the "Sensitive" checkbox
6. Click "Add variable"

Repeat the process for AWS_SECRET_ACCESS_KEY.

Working with Sensitive Variables

Sensitive variables are a critical feature of Terraform Cloud:

• Their values are never shown in the UI after creation
• They are encrypted in Terraform Cloud's database
• They don't appear in logs or API responses
• They can be updated, but not viewed

Example of adding a sensitive database password:

1. Add a new Terraform variable
2. Key: "db_password"
3. Value: "your-secure-password"
4. Description: "Password for the database"
5. Check "Sensitive"
6. Click "Add variable"

In your configuration, you might use it like this:

hcl

resource "aws_db_instance" "database" {
  allocated_storage    = 20
  engine               = "mysql"
  engine_version       = "5.7"
  instance_class       = "db.t2.micro"
  name                 = "mydb"
  username             = "admin"
  password             = var.db_password  # Using our sensitive variable
  parameter_group_name = "default.mysql5.7"
  skip_final_snapshot  = true
}

HCL Variables

When you need to pass complex structured data (like lists or maps), use the HCL option:

1. Add a new Terraform variable
2. Key: "subnet_cidr_blocks"
3. Value: ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
4. Check "HCL"
5. Click "Add variable"

This allows you to define complex data structures directly in the Terraform Cloud interface:

hcl

resource "aws_subnet" "main" {
  count      = length(var.subnet_cidr_blocks)
  vpc_id     = aws_vpc.main.id
  cidr_block = var.subnet_cidr_blocks[count.index]
  
  tags = {
    Name = "Subnet-${count.index + 1}"
  }
}

Variable Sets

Variable sets allow you to define collections of variables that can be applied to multiple workspaces:

1. Go to your organization settings
2. Navigate to "Variable Sets"
3. Click "Create variable set"
4. Give it a name like "AWS Credentials"
5. Add your AWS environment variables
6. Select which workspaces should use these variables

This is especially useful for credentials or common configuration that spans multiple projects.

Practical Example: Multi-Environment Deployment

Let's see a complete example of using Terraform Cloud variables for different environments:

Define Base Configuration

hcl

# main.tf
provider "aws" {
  region = var.aws_region
}

resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  count         = var.instance_count
  
  tags = {
    Name        = "${var.environment}-webserver"
    Environment = var.environment
  }
}

Define Variables

hcl

# variables.tf
variable "aws_region" {
  description = "AWS region for resource deployment"
  type        = string
}

variable "ami_id" {
  description = "AMI ID for EC2 instances"
  type        = string
}

variable "instance_type" {
  description = "Type of EC2 instance"
  type        = string
}

variable "instance_count" {
  description = "Number of instances to launch"
  type        = number
  default     = 1
}

variable "environment" {
  description = "Deployment environment (dev, staging, prod)"
  type        = string
}

Set Up Environment-Specific Variables in Terraform Cloud

For Development:

• environment: "dev"
• instance_type: "t2.micro"
• instance_count: 1
• ami_id: "ami-0abcdef1234567890"

For Production:

• environment: "prod"
• instance_type: "t2.medium"
• instance_count: 3
• ami_id: "ami-0abcdef1234567890"

With this setup, you can maintain a single configuration while deploying environment-specific infrastructure through different workspaces.

Working with Variables Programmatically

Terraform Cloud provides an API for managing variables programmatically:

bash

# Create a variable using the API
curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data '{
    "data": {
      "type": "vars",
      "attributes": {
        "key": "instance_type",
        "value": "t2.micro",
        "description": "EC2 instance type",
        "category": "terraform",
        "hcl": false,
        "sensitive": false
      },
      "relationships": {
        "workspace": {
          "data": {
            "id": "ws-example123",
            "type": "workspaces"
          }
        }
      }
    }
  }' \
  https://app.terraform.io/api/v2/vars

This approach enables you to integrate variable management into your CI/CD pipelines.

Variable Precedence

Terraform Cloud follows a specific precedence order when multiple sources define the same variable:

1. Environment variables (highest precedence)
2. Terraform variables in the workspace
3. Variable sets
4. Default values in your Terraform code (lowest precedence)

Understanding this hierarchy helps when troubleshooting unexpected values.

Best Practices for Terraform Cloud Variables

1. Use Variable Descriptions: Always add clear descriptions to help team members understand each variable's purpose.

2. Leverage Variable Sets: Use variable sets for credentials and common configurations across workspaces.

3. Mark Sensitive Data: Always mark passwords, tokens, and keys as sensitive.

4. Use Version Control for Defaults: Keep non-sensitive default values in your Terraform code for documentation.

5. Namespace Your Variables: Use prefixes for related variables (e.g., db_username, db_password).

6. Document Required Variables: Clearly document which variables must be set in Terraform Cloud.

7. Limit Access: Use Terraform Cloud's team permissions to restrict who can view or modify variables.

8. Audit Regularly: Periodically review variables to ensure they're still needed and secure.

Troubleshooting Variables

If you encounter issues with variables in Terraform Cloud:

1. Check Spelling: Ensure variable names match exactly between your code and Terraform Cloud.

2. Verify HCL Setting: Make sure complex data structures have the HCL option enabled.

3. Check Workspace: Confirm you're looking at the correct workspace's variables.

4. Review Runs: Examine run logs to see what values Terraform is actually using.

5. Consider Precedence: Remember that environment variables override Terraform variables.

Summary

Terraform Cloud Variables provide a powerful mechanism for managing configuration values across your infrastructure deployments. By separating values from code, you can improve security, manage environments more effectively, and streamline your DevOps workflows.

Key points to remember:

• Use Terraform variables for configuration parameters
• Use environment variables for authentication and secrets
• Leverage sensitive flags for security
• Use HCL for complex data structures
• Implement variable sets for multi-workspace configurations

Additional Resources

• Terraform Cloud Documentation
• Variable Set API Documentation
• Terraform Input Variables Documentation

Practice Exercises

1. Create a workspace with variables for deploying a web server in different regions.
2. Set up a variable set for your organization with common tags for all resources.
3. Use HCL variables to define a map of environment-specific settings.
4. Create a CI/CD pipeline that updates Terraform Cloud variables programmatically.
5. Configure a workspace that uses both organization-level and workspace-level variables.