Terraform Lists vs Maps

Table of Contents

Introduction: Why Lists and Maps Matter

Terraform's power lies in its ability to manage infrastructure declaratively. However, choosing the right data type - lists or maps - can significantly impact the scalability, readability, and reusability of your code. Both data types have unique strengths: lists excel in ordered collections, while maps shine in descriptive and scalable configurations.

By mastering lists and maps, you'll enhance your Terraform workflows, reduce redundancy, and ensure that your code remains clean and maintainable as your infrastructure grows.

What Are Lists in Terraform?

A list is an ordered collection of elements in Terraform, where sequence matters. Use lists for simple, homogeneous data that needs to be iterated or accessed by position.

Syntax and Basic Example

variable "example_list" {
  type    = list(string)
  default = ["us-east-1", "us-west-2", "eu-central-1"]
}

In this example, the list contains three region identifiers.

When to Use Lists

1. Preserve Order: Ideal for scenarios where sequence matters (e.g., processing tasks in order).
2. Batch Operations: Simplifies operations like deploying identical instances or resources.
3. Iterative Access: Use functions like count.index to loop through list elements efficiently.

Practical Scenario:

You have a list of subnet IDs and want to deploy multiple EC2 instances. A list ensures that each instance uses the corresponding subnet in the correct order.

What Are Maps in Terraform?

A map is a collection of key-value pairs, offering a more descriptive and scalable alternative to lists. Maps allow you to store complex configurations with unique identifiers, making them ideal for larger or more diverse datasets.

Syntax and Basic Example

variable "example_map" {
  type = map(string)
  default = {
    dev     = "t2.micro"
    staging = "t3.medium"
    prod    = "m5.large"
  }
}

Here, the map associates each environment with its corresponding EC2 instance type.

When to Use Maps

1. Key-Based Access: Retrieve values using descriptive keys instead of numeric indices.
2. Multi-Attribute Data: Store complex data, such as configurations for multiple environments.
3. Ease of Updates: Add, modify, or remove specific elements without affecting the entire collection.

Practical Scenario:

Use a map to define different AMIs for regions:

variable "ami_map" {
  type = map(string)
  default = {
    us-east-1 = "ami-0c55b159cbfafe1f0"
    us-west-2 = "ami-01e24be29428c15b2"
  }
}

Lists vs. Maps: Key Differences

Advanced Use Cases

Real-World Example: Azure SQL DB Metric Alerts

Using Lists (Initial Approach):

variable "alert_metrics" {
  type = list(object({
    metric_type = string
    metric_name = string
  }))
}

Challenges:

• Accessing elements by index is error-prone.
• Adding new metrics disrupts the structure.

Improved with Maps:

variable "alert_metrics" {
  type = map(object({
    metric_type = string
    metric_name = string
  }))
  default = {
    memory = { metric_type = "Memory" metric_name = "sql_instance_memory_percent" }
    cpu    = { metric_type = "CPU" metric_name = "sql_instance_cpu_percent" }
  }
}

Benefits:

• Metrics are accessed by descriptive keys like memory.
• Adding new metrics is straightforward.

Working with Nested Maps for Complex Structures

Nested maps are invaluable for managing hierarchical configurations.

variable "environment_configs" {
  type = map(map(string))
  default = {
    dev     = { region = "us-east-1" instance_type = "t2.micro" }
    staging = { region = "us-west-2" instance_type = "t3.medium" }
    prod    = { region = "eu-central-1" instance_type = "m5.large" }
  }
}

Access environment-specific configurations like this:

var.environment_configs["prod"]["region"]

Best Practices for Using Lists and Maps

Use for loops to create dynamic maps from lists:

variable "environments" {
  type = list(string)
  default = ["dev", "staging", "prod"]
}

variable "cidr_blocks" {
  type = list(string)
  default = ["10.0.0.0/16", "10.1.0.0/16", "10.2.0.0/16"]
}

locals {
  vpc_map = { for idx, env in var.environments : env => var.cidr_blocks[idx] }
}

This creates a map where each environment is linked to its CIDR block.

Best Practices for Using Lists and Maps

1. Prefer Maps for Readability: Use maps for descriptive configurations.
2. Combine Data Dynamically: Use loops and locals for complex structures.
3. Avoid Hardcoding: Use maps to centralize environment-specific variables.
4. Leverage Functions: Use lookup, merge, and tomap for dynamic transformations.
5. Validate Configurations: Use Terraform’s validation block to enforce rules.

JSON Representation for Maps

Use JSON for interoperability with external tools:

{
  "alert_metrics": {
    "cpu": {
      "metric_type": "CPU",
      "metric_name": "sql_instance_cpu_percent"
    },
    "memory": {
      "metric_type": "Memory",
      "metric_name": "sql_instance_memory_percent"
    }
  }
}

Conclusion: Lists, Maps, or Both?

Both lists and maps are powerful tools in Terraform. Use lists for ordered, simple data and maps for descriptive, complex configurations. Often, the best solutions combine both data types dynamically for optimal flexibility and scalability.

FAQs

1. How do I convert a list to a map in Terraform?
Use toset() or tomap() functions to transform lists into maps.

2. Can I nest maps inside lists?
Yes, Terraform supports nested data structures for advanced configurations.

3. Should I use JSON instead of HCL?
HCL is preferred for readability, while JSON is great for integration.

Useful Links to HashiCorp Resources

For a deeper understanding of Terraform's features and to access official documentation and best practices, here are some valuable resources from HashiCorp:

1. Terraform Official Documentation
   Explore comprehensive guides, syntax references, and tutorials for building, managing, and automating infrastructure with Terraform.

2. Variables Documentation
   Learn about defining, using, and managing variables in Terraform, including lists and maps, with detailed examples.

3. For Loops and Dynamic Blocks
   Dive into how to use for expressions to create dynamic configurations and simplify resource definitions.

4. Built-In Functions
   Discover Terraform’s robust set of built-in functions for transforming data, such as lookup, merge, tomap, and toset.

5. Terraform Tutorials
   Access beginner to advanced-level tutorials for mastering Terraform, including real-world use cases and interactive labs.

6. HashiCorp Learn - Multi-Environment Workflows
   Understand how to manage environments like dev, staging, and prod using workspaces and other best practices.

7. Terraform Best Practices Guide
   Follow HashiCorp’s official recommendations for writing modular, reusable, and maintainable Terraform code.

By leveraging these resources, you'll gain deeper insights and practical guidance to maximize your Terraform proficiency. Whether you’re just starting or refining your workflows, these links will empower you to tackle any Terraform challenge.