What is a Datasource? #

# resource — Terraform OWNS this
# Created, updated, and deleted by Terraform
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
  # This VPC exists because Terraform created it
  # If this block is removed from the configuration → the VPC is deleted
}

# data — Terraform READS this
# Already exists outside, Terraform only queries
data "aws_vpc" "existing" {
  id = "vpc-0abcdef1234567890"
  # This VPC existed before Terraform — created manually or by another team
  # Terraform only reads it, never modifies or deletes it
}

# Data sources are evaluated first, then the resources using them are planned

data "aws_ami" "ubuntu" {
  most_recent = true
  owners      = ["099720109477"]  # Canonical

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-*-22.04-amd64-server-*"]
  }
}

resource "aws_instance" "web" {
  # At plan time, data.aws_ami.ubuntu.id is already known
  # (not "known after apply" like a resource)
  ami           = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"
}

# 1. Latest AMI
data "aws_ami" "ubuntu_22_04" {
  most_recent = true
  owners      = ["099720109477"]

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }
}

# 2. Current AWS account information
data "aws_caller_identity" "current" {}

data "aws_region" "current" {}

# Use in the configuration:
resource "aws_s3_bucket" "logs" {
  bucket = "logs-${data.aws_caller_identity.current.account_id}-${data.aws_region.current.name}"
}

# 3. Available availability zones
data "aws_availability_zones" "available" {
  state = "available"
}

resource "aws_subnet" "public" {
  count             = 3
  availability_zone = data.aws_availability_zones.available.names[count.index]
  vpc_id            = aws_vpc.main.id
  cidr_block        = "10.0.${count.index}.0/24"
}

# 4. A VPC or resource managed by another Terraform
data "aws_vpc" "shared_services" {
  tags = {
    Name = "shared-services-vpc"
    Environment = "production"
  }
}

# 5. A secret from AWS Secrets Manager
data "aws_secretsmanager_secret_version" "api_key" {
  secret_id = "production/myapp/api-key"
}

# 6. An IAM policy document
data "aws_iam_policy_document" "assume_role" {
  statement {
    effect  = "Allow"
    actions = ["sts:AssumeRole"]

    principals {
      type        = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "instance" {
  assume_role_policy = data.aws_iam_policy_document.assume_role.json
}

# ANTI-PATTERN: Overly broad filter — may return >1 result
data "aws_instance" "web" {
  filter {
    name   = "instance-state-name"
    values = ["running"]  # There are many running instances!
  }
  # Error: Your query returned more than one result. Please try a more specific search criteria.
}

# CORRECT: A filter specific enough to return exactly 1 result
data "aws_instance" "web" {
  filter {
    name   = "tag:Name"
    values = ["web-server-production"]
  }

  filter {
    name   = "instance-state-name"
    values = ["running"]
  }
}

# DATA SOURCE: Fetch from the cloud API
data "aws_ami" "latest" {
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*"]
  }
}

# VARIABLE: Provided by the user or tfvars
variable "ami_id" {
  type    = string
  default = "ami-12345"
}

# When a data source is better:
# - The value changes over time (latest AMI, availability zones)
# - The value depends on resources already existing in the cloud
# - You need information the user doesn't know

# When a variable is better:
# - The value is known and specific
# - You need custom validation
# - The value differs per environment

# ANTI-PATTERN: Fetching too much data
data "aws_instances" "all" {
  # Fetches ALL instances in the account → expensive API calls
  # No filter → a very large response
}

# CORRECT: Filter as early as possible
data "aws_instances" "running" {
  filter {
    name   = "instance-state-name"
    values = ["running"]
  }
  
  filter {
    name   = "tag:Environment"
    values = [var.environment]
  }
}

# Fetch info about an existing VPC (shared infrastructure)
data "aws_vpc" "main" {
  filter {
    name   = "tag:Environment"
    values = [var.environment]
  }
}

data "aws_subnets" "private" {
  filter {
    name   = "vpc-id"
    values = [data.aws_vpc.main.id]
  }
  filter {
    name   = "tag:Tier"
    values = ["private"]
  }
}

# Use data sources for conditional resources
resource "aws_instance" "web" {
  count         = var.environment == "production" ? 3 : 1
  ami           = data.aws_ami.latest.id
  instance_type = var.environment == "production" ? "m5.large" : "t3.micro"
  subnet_id     = data.aws_subnets.private.ids[0]
}

# Common errors:

# 1. Resource not found
# Error: no matching AMI found
# → Check the filter, make sure the resource actually exists

# 2. Multiple matches
# Error: multiple VPCs matched; use additional constraints
# → Add a more specific filter

# 3. Permission denied
# Error: UnauthorizedOperation
# → Make sure the IAM policy has read permission for the resource type

# 4. API rate limit
# Error: Throttling
# → Reduce data sources, use caching, or retry

# Tip: use try() for graceful degradation
locals {
  # If the data source fails, use a default
  vpc_cidr = try(data.aws_vpc.main.cidr_block, "10.0.0.0/16")
  
  # If the data source returns empty
  subnet_ids = length(data.aws_subnets.private.ids) > 0     ? data.aws_subnets.private.ids     : [aws_subnet.fallback.id]
}

DATA SOURCE LIFECYCLE:

terraform init
  └── Download providers

terraform plan
  ├── Read the data source (API call)
  ├── Store the result in state
  ├── Use the result to compute resource arguments
  └── Plan resource changes

terraform apply
  ├── Read the data source again (refresh)
  ├── Apply resource changes
  └── Update state

terraform destroy
  └── Delete managed resources (data sources are NOT deleted)

# Data sources are ALWAYS refreshed during plan/apply
# This can be slow if there are many data sources

# Speed up: use -refresh=false (not recommended)
terraform plan -refresh=false

# Better: reduce the number of data sources
# or use a caching mechanism