Skip to content

Examples

This page provides practical examples of how to use Terratags in various scenarios.

Validation Examples

Directory Validation (Direct Resources)

Validate resources defined directly in your Terraform files:

# Basic validation
terratags -config config.yaml -dir ./infra

# With HTML report
terratags -config config.yaml -dir ./infra -report report.html

# With exemptions
terratags -config config.yaml -dir ./infra -exemptions exemptions.yaml

Plan Validation (All Resources Including Modules)

Validate all resources including those created by external modules:

# Generate plan
terraform plan -out=tfplan
terraform show -json tfplan > plan.json

# Validate all resources
terratags -config config.yaml -plan plan.json

# With HTML report
terratags -config config.yaml -plan plan.json -report report.html

Configuration Examples

Basic Required Tags Configuration (YAML)

required_tags:
  - Name
  - Environment
  - Owner
  - Project

Pattern Validation Configuration (YAML)

required_tags:
  Name:
    pattern: "^\\S+$"  # No whitespace

  Environment:
    pattern: "^(dev|test|staging|prod)$"  # Specific values only

  Owner:
    pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"  # Email format

  Project:
    pattern: "^[A-Z]{2,4}-[0-9]{3,6}$"  # Project code format

  CostCenter:
    pattern: "^CC-[0-9]{4}$"  # Cost center format

Mixed Validation Configuration (YAML)

required_tags:
  # Pattern validation for critical tags
  Environment:
    pattern: "^(dev|test|staging|prod)$"

  Owner:
    pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"

  # Simple validation for others
  Name: {}
  Project: {}
  Team: {}

Exemptions Configuration

exemptions:
  - resource_type: aws_s3_bucket
    resource_name: logs_bucket
    exempt_tags: [Owner, Project]
    reason: "Legacy bucket used for system logs only"

  - resource_type: aws_dynamodb_table
    resource_name: "*"
    exempt_tags: [Environment]
    reason: "DynamoDB tables use environment from provider default_tags"

Terraform Examples

AWS Provider with Default Tags

provider "aws" {
  region = "us-west-2"

  default_tags {
    tags = {
      Environment = "dev"
      Owner       = "team-a"
      Project     = "demo"
    }
  }
}

Resource with Tags

resource "aws_instance" "example" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"

  tags = {
    Name = "example-instance"
    Environment = "production"
    Owner = "team-b"
    Project = "website"
  }
}

Resource with Default Tags

resource "aws_instance" "example" {
  ami           = "ami-12345678"
  instance_type = "t2.micro"

  # Only need to specify Name tag, as other required tags come from default_tags
  tags = {
    Name = "example-instance"
  }
}

Module with Tags

module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "3.14.0"

  name = "my-vpc"
  cidr = "10.0.0.0/16"

  tags = {
    Name = "my-vpc"
    Environment = "production"
    Owner = "team-b"
    Project = "website"
  }
}

Command Examples

Basic Usage

terratags -config config.yaml -dir ./infra

Generate HTML Report

terratags -config config.yaml -dir ./infra -report report.html

Validate Terraform Plan

terraform plan -out=tfplan
terraform show -json tfplan > plan.json
terratags -config config.yaml -plan plan.json

Show Auto-remediation Suggestions

terratags -config config.yaml -dir ./infra -remediate

Use Exemptions

terratags -config config.yaml -dir ./infra -exemptions exemptions.yaml

Verbose Output

terratags -config config.yaml -dir ./infra -verbose

Pattern Validation Examples

# Test passing pattern validation
terratags -config examples/config-patterns.yaml -dir examples/pattern_validation_passing

# Test failing pattern validation (shows violations)
terratags -config examples/config-patterns.yaml -dir examples/pattern_validation_failing

# Generate report for pattern violations
terratags -config examples/config-patterns.yaml -dir examples/pattern_validation_failing -report pattern-report.html

Repository Examples

The repository includes comprehensive examples in the examples/ directory:

Pattern Validation Examples

  • pattern_validation_passing/ - Terraform resources with tags that pass all pattern validation requirements
  • pattern_validation_failing/ - Terraform resources with tags that fail pattern validation (demonstrates common mistakes)

Provider Examples

  • provider_default_tags/ - AWS provider default_tags integration
  • awscc_tags/ - AWS Cloud Control provider tag format
  • azurerm_tags/ - Azure Resource Manager provider
  • azapi_tags/ - Azure API provider with default_tags

Resource Type Examples

  • resource_blocks/ - Individual resource validation
  • module_blocks/ - Module-level tag validation
  • mixed_blocks/ - Mixed resource and module validation

Configuration Examples

  • config.yaml - Simple format (legacy)
  • config-patterns.yaml - Advanced pattern validation
  • config-mixed.yaml - Mixed simple and pattern validation

Additional Resources

For more detailed examples and guidance, please check: