Examples

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

Configuration Examples

Basic Required Tags Configuration (YAML)

required_tags:
  - Name
  - Environment
  - Owner
  - Project

Required Tags with Descriptions (YAML)

required_tags:
  - key: Name
    description: "Identifies the resource"
  - key: Environment
    description: "Deployment environment (dev, test, prod)"
  - key: Owner
    description: "Team or individual responsible for the resource"
  - key: Project
    description: "Project or application name"

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

Sample HTML Reports

Module Blocks Report

Resource Blocks Report

Provider Default Tags Report

AWSCC Resources Report

This report shows how Terratags handles AWSCC resources, including the new "Excluded" category for resources with non-compliant tag schemas.

Real-World Scenarios

Scenario 1: Multi-Environment Deployment

For a project with multiple environments, you might have different tag requirements for each environment:

# dev-config.yaml
required_tags:
  - Name
  - Environment
  - Owner

# prod-config.yaml
required_tags:
  - Name
  - Environment
  - Owner
  - Project
  - CostCenter
  - DataClassification

You can then validate each environment with the appropriate configuration:

terratags -config dev-config.yaml -dir ./infra/environments/dev
terratags -config prod-config.yaml -dir ./infra/environments/prod

Scenario 2: Gradual Tag Implementation

When implementing tagging policies gradually, you might start with a subset of required tags and add more over time:

# phase1-config.yaml
required_tags:
  - Name
  - Environment

# phase2-config.yaml
required_tags:
  - Name
  - Environment
  - Owner
  - Project

You can use exemptions to gradually roll out the new requirements:

# phase2-exemptions.yaml
exemptions:
  - resource_type: "*"
    resource_name: "*"
    exempt_tags: [Project]
    reason: "Project tag requirement being phased in"

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

As teams update their resources, you can remove exemptions until all resources comply with the full tagging policy.