tfpipboy

Terraform orchestration tool with parallel execution, dependency management, and real-time monitoring.

---

Overview

tfpipboy is a powerful Terraform orchestration tool that simplifies managing complex, multi-module infrastructure deployments. It provides dependency-aware execution, parallel processing, and real-time monitoring through a beautiful terminal interface.

Key Features

• 🚀 Parallel Execution - Run independent modules concurrently
• 🔗 Dependency Management - Automatic execution ordering
• 🔍 Module Discovery - Automatically scan and generate configuration for Terraform modules
• 🔐 Authentication Monitoring - Real-time status for AWS, Azure, GCP, GitHub
• 📊 Live Board - Beautiful TUI with real-time job status
• 🏗️ Isolated Workspaces - Each module runs in its own environment
• 📋 Pipeline Support - Define reusable deployment workflows
• ✅ Validation - Comprehensive configuration validation

---

Quick Start

Installation

Homebrew (macOS/Linux)

brew tap stanleyxie/tap
brew install tfpipboy

Go Install

go install github.com/StanleyXie/tfpipboy/cmd/tfpipboy@latest

From Source

git clone https://github.com/StanleyXie/tfpipboy.git
cd tfpipboy
make build
make install

Basic Usage

1. Create configuration:

mkdir .tfpipboy

2. Define your infrastructure in .tfpipboy/tfproject.yaml:

version: "1.0"

modules:
  - name: networking
    path: terraform/modules/networking
    
  - name: database
    path: terraform/modules/database
    depends_on: [networking]
    
  - name: application
    path: terraform/modules/application
    depends_on: [networking, database]

instances:
  - module: networking
    workspace: "prod-network"
    
  - module: database
    workspace: "prod-db"
    
  - module: application
    workspace: "prod-app"

3. Execute:

# Plan all modules
tfpipboy --operation plan --targets-all

# Apply infrastructure
tfpipboy --operation apply --targets-all

# Destroy specific modules
tfpipboy --operation destroy --targets networking,database

---

Status

Current Version: v0.7.0-beta.1
Status: Core features complete, CI/CD stabilized, preparing for v1.0 release

What's Implemented ✅

• ✅ Multi-module Terraform orchestration
• ✅ Parallel execution with dependency management
• ✅ Authentication monitoring (AWS, Azure, GCP, GitHub)
• ✅ Live board TUI with real-time status
• ✅ Configuration validation
• ✅ Pipeline support
• ✅ Isolated workspace management
• ✅ Cross-platform support (Linux, macOS, Windows)
• ✅ Comprehensive security validation (SBOM, vulnerability scanning)
• ✅ Automated CI/CD with GitHub Actions

Roadmap 🗺️

See ROADMAP.md for detailed project history and future plans.

• v0.7.0: Code quality improvements, address linter findings
• v0.8.0: Enhanced documentation & user experience
• v1.0.0: Production release with comprehensive testing

---

Documentation

Getting Started

• Getting Started Guide - Quick start and basic concepts
• User Guide - Complete usage documentation
• Configuration Reference - Detailed configuration options
• Module Discovery Guide - Automatically discover and configure Terraform modules

Project Information

• ROADMAP - Project evolution and future plans
• CHANGELOG - Version history
• CONTRIBUTING - How to contribute
• SECURITY - Security policy

Additional Resources

• Documentation Index - Complete documentation overview
• Design History - Historical design documents
• Examples - Real-world configuration examples (private examples directory)

---

Core Concepts

Modules

Terraform configurations that manage related resources.

Instances

Specific executions of modules with their own workspaces and variables.

Dependencies

Define execution order - modules run in the correct sequence automatically.

Pipelines

Reusable deployment workflows with multiple stages.

---

Features in Detail

Parallel Execution

tfpipboy automatically runs independent modules in parallel:

Stage 1: networking (runs alone)
Stage 2: database-primary, database-replica (run in parallel)
Stage 3: application (runs after database-primary)

Control concurrency:

tfpipboy --operation apply --targets-all --concurrent 10

Authentication Monitoring

Real-time authentication status:

╭─────────────────────── Authentication ────────────────────────╮
│ ✓ AWS     (account: 123456789012)                            │
│ ✓ Azure   (subscription: prod-subscription)                   │
│ ✗ GCP     (not authenticated)                                │
│ ✓ GitHub  (user: yourname)                                   │
╰────────────────────────────────────────────────────────────────╯

Live Board Interface

Beautiful TUI showing real-time progress:

╭─────────────────────── Execution Progress ────────────────────╮
│ [✓] networking            Completed    45s                    │
│ [→] database-primary      Running      23s                    │
│ [→] database-replica      Running      23s                    │
│ [⧖] application           Waiting                             │
╰────────────────────────────────────────────────────────────────╯

Multi-Region Support

Deploy to multiple regions easily:

instances:
  - module: regional-app
    workspace: "prod-us-east-1-app"
    variables:
      region: us-east-1
      
  - module: regional-app
    workspace: "prod-eu-west-1-app"
    variables:
      region: eu-west-1

---

Example Commands

# Discover modules and generate configuration
tfpipboy --discover ./terraform --discover-output .tfpipboy/modules.yaml

# Plan all modules
tfpipboy --operation plan --targets-all

# Apply specific modules
tfpipboy --operation apply --targets networking,database

# Execute a pipeline
tfpipboy --pipeline deploy-all --env production

# Dry run (show execution plan)
tfpipboy --operation apply --targets-all --dry-run

# High concurrency
tfpipboy --operation apply --targets-all --concurrent 10

# Verbose logging
tfpipboy --operation plan --targets-all --verbose

# Manually track state (capture current state without changes)
tfpipboy --state-track --targets networking

---

Project Structure

tfpipboy/
├── cmd/
│   └── tfpipboy/          # Main application
├── pkg/
│   ├── orchestrator/      # Orchestration engine
│   ├── auth/              # Authentication detection
│   ├── terraform/         # Terraform integration
│   └── cli/               # CLI interface
├── docs/                  # User documentation
│   ├── getting-started.md
│   ├── user-guide.md
│   ├── configuration.md
│   ├── design-archive/    # Historical design docs
│   └── archive/           # Historical status reports
├── ROADMAP.md            # Project roadmap
├── SECURITY.md           # Security policy
└── CHANGELOG.md          # Version history

---

Development

Prerequisites

• Go 1.23 or later
• Terraform 1.0.0 or later
• Make (optional but recommended)

Setup

# Clone repository
git clone https://github.com/StanleyXie/tfpipboy.git
cd tfpipboy

# Install dependencies
go mod download

# Build
make build

# Run tests
make test

# Run linter
make lint

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development workflow
• Code style guidelines
• Testing requirements
• Pull request process

---

Technology Stack

• Language: Go 1.23+
• CLI Framework: Cobra
• TUI Framework: Bubble Tea
• Styling: Lip Gloss
• Build: GoReleaser
• CI/CD: GitHub Actions
• Security: Gosec, Trivy, SBOM generation

---

Architecture

tfpipboy uses an async event-driven architecture:

• Orchestrator: Coordinates module execution
• Dependency Graph: Determines execution order
• Parallel Executor: Manages concurrent jobs
• Live Board: Real-time TUI updates
• Auth Monitor: Tracks cloud provider authentication

See Design Archive for complete architecture history.

---

Security

tfpipboy follows security best practices:

• No credential storage
• Read-only authentication checks via official CLI tools
• State management through Terraform (no direct manipulation)
• Comprehensive input validation

See SECURITY.md for our security policy and reporting vulnerabilities.

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• Bubble Tea - Excellent TUI framework
• Cobra - Powerful CLI framework
• Lip Gloss - Terminal styling
• Inspired by Terragrunt

---

Links

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Releases: GitHub Releases

---

Ready to orchestrate? Get started with the Quick Start Guide!