tf-tagguard 1.0.0

CLI tool to validate and enforce AWS tags for resources deployed using Terraform. Targeted for CI/CD pipelines and CLI environments.

tf-tagguard

tf-tagguard is a production-ready CLI tool to validate and enforce AWS tags on resources deployed via Terraform. It features intelligent resource detection, comprehensive validation, and seamless CI/CD integration for enterprise-grade tagging compliance.

---

Features

• Smart Resource Detection: Auto-detects taggable AWS resources using Terraform provider schema
• Action Filtering: Option to validate only resources being created/updated/replaced
• Tag Validation: Presence, exact values, lists, and regex patterns
• Terraform Integration: Shows Terraform and AWS provider versions
• Non-taggable Skipping: Automatically skips resources that don't support tags
• Comprehensive Reporting: Detailed validation results with resource counts
• CI/CD Ready: Proper exit codes and structured output

---

Installation

pip install tf-tagguard

CLI Usage

validatetags-tf PLAN_FILE [OPTIONS]

Option	Description	Example
-r, --required-tags	Comma-separated list of required tags (presence only).	--required-tags Name,Environment
-v, --value-tags	List of tags with expected values. Supports: - Exact value → key=value - List of allowed values → key=[v1,v2,v3] - Regex pattern → key=^regex$	Environment=dev Team=[dev,ops,qa] Owner=^user.*$
-d, --delta	Only validate resources being created/updated/replaced	--delta
--no-terraform-detection	Disable automatic taggable resource detection	--no-terraform-detection

Examples

Basic Usage

# Validate required tags with smart resource detection
validatetags-tf plan.json -r Name,Environment,Owner

# Validate only resources being modified (delta mode)
validatetags-tf plan.json -r Name,Environment --delta

# Validate tag values with multiple types
validatetags-tf plan.json -v "Environment=[dev,prod]" -v "Owner=^user.*$"

Advanced Usage

# Disable Terraform detection (validate all resources)
validatetags-tf plan.json -r Name --no-terraform-detection

# Combined validation with delta mode
validatetags-tf plan.json -r Name -v "Environment=[dev,prod]" --delta

# Complex validation
validatetags-tf plan.json \
  -r Name,Environment,Owner \
  -v "Team=[ops,dev,qa]" \
  -v "Owner=^user[0-9]+$" \
  -v "CostCenter=[1000,2000,3000]" \
  --delta

NOTE:

⚠️ Tags declared in both -r and -v will trigger a warning, as a fallback mechanisim -v values take precedence.

Terraform Plan JSON

tf-tagguard expects a Terraform plan in JSON format. Generate it with:

terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > plan.json

Exit Codes

Code	Description
0	✅ All validations passed
1	❌ Validation failed or error occurred

Advanced Usage

Smart Resource Detection

tf-tagguard automatically detects which AWS resources support tagging:

# Shows Terraform version, provider version, and detected resource types
validatetags-tf plan.json -r Name,Environment

# Output:
# Using Terraform Version: 1.7.2
# AWS Provider Version: 5.31.0
# Detected 200+ taggable resource types
# Validated 15 resources (all resources)
# Skipped 3 non-taggable resources:
#   - data.aws_caller_identity.current
#   - random_id.bucket_suffix
#   - aws_iam_policy_document.assume_role
#
# All 15 validated resources passed tag validation.

Delta Mode (Only Modified Resources)

# Only validate resources being created, updated, or replaced
validatetags-tf plan.json -r Name,Environment --delta

# Perfect for CI/CD pipelines - faster execution

Multiple Value Tags

Use separate -v flags for multiple validations:

validatetags-tf plan.json \
  -v "Environment=[dev,staging,prod]" \
  -v "Team=[ops,dev,qa]" \
  -v "Owner=^user.*$" \
  --delta

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for version history and changes.