tf-tagguard 0.1.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 CLI tool to validate and enforce AWS tags on resources deployed via Terraform. It is designed for CI/CD pipelines and local CLI environments, ensuring all resources meet your organization's tagging policies.

---

Features

• Validate presence of required tags.
• Validate tag values (exact match, list of values, or regex patterns).
• Tabular summary of missing or invalid tags using tabulate.
• Fail-fast behavior for duplicate tag declarations.
• Easy integration into CI/CD pipelines.
• Modular design for future extensions.

---

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.*$

Examples

1. Validate only tag presence

validatetags-tf plan.json -r Name,Environment,Owner

2. Validate tag values

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

3. Validate presence + values (fallback: -v takes precedence if duplicated)

validatetags-tf plan.json -r Name,Owner -v "Environment=dev","Team=[ops,dev]"

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

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.*$"

CI/CD Integration

GitHub Actions:

- name: Validate Terraform Tags
  run: |
    terraform plan -out=tfplan.binary
    terraform show -json tfplan.binary > plan.json
    validatetags-tf plan.json -r Name,Environment,Owner

GitLab CI:

validate_tags:
  script:
    - terraform plan -out=tfplan.binary
    - terraform show -json tfplan.binary > plan.json
    - validatetags-tf plan.json -r Name,Environment,Owner

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.