Skip to content

Usage

Terratags can be used in various ways to validate tags on AWS and Azure resources in your Terraform configurations.

Validation Modes

Terratags supports two validation modes:

Directory Validation (Direct Resources)

Analyzes Terraform files directly and validates: - Resources defined in your .tf files - Module calls and their input tags

terratags -config config.yaml -dir ./infra

Plan Validation (All Resources)

Analyzes Terraform plan output and validates: - Resources defined in your .tf files - Resources created by external modules - Complete infrastructure with tag inheritance

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

Recommendation: Use plan validation for comprehensive coverage including module-created resources.

Command Examples

Generate HTML Report

Generate a detailed HTML report of tag compliance:

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

Validate tags in a Terraform plan output including module resources:

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

Show Auto-remediation Suggestions

Get suggestions for fixing non-compliant resources:

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

Use Exemptions

Apply exemptions to specific resources:

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

Verbose Output

For more detailed output, use the -verbose flag:

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

This will show additional information about the validation process, including:

  • Files being analyzed
  • Resources being checked
  • Tag inheritance from default_tags
  • Exemptions being applied

Exit Codes

Terratags uses the following exit codes:

  • 0: All resources are compliant with tagging requirements
  • 1: One or more resources are missing required tags
  • 2: Error in configuration or execution

This makes it easy to integrate Terratags into CI/CD pipelines and fail builds when tag requirements are not met.

Working with Large Codebases

For large Terraform codebases, you can:

  1. Run Terratags on specific directories: 

    terratags -config config.yaml -dir ./infra/modules/networking

  2. Use the plan-based approach to only validate resources that are changing: 

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

HTML Reports

The HTML report provides a visual representation of tag compliance across your Terraform resources, making it easy to identify which resources need attention and track compliance metrics.

To generate a report:

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

The report includes:

  • Overall compliance percentage
  • List of compliant and non-compliant resources
  • Missing tags for each non-compliant resource
  • Summary statistics

Log Levels

Terratags supports different log levels to control the verbosity of output:

terratags -config config.yaml -dir ./infra -log-level INFO

Available log levels:

  • DEBUG: Shows all debug information, including detailed tag discovery
  • INFO: Shows informational messages (same as using the -verbose flag)
  • WARN: Shows only warnings and errors
  • ERROR: Shows only errors (default)

For backward compatibility, the -verbose flag is equivalent to -log-level INFO.

Case-Insensitive Tag Matching

By default, Terratags performs case-sensitive matching for tag keys. To enable case-insensitive matching, use the -ignore-case flag:

terratags -config config.yaml -dir ./infra -ignore-case

With this option enabled, tag keys like "Environment", "ENVIRONMENT", and "environment" will all match a required tag key "Environment".