masonjames/dockhand-plugin/dh-infra

Dockhand Infrastructure

Manage infrastructure-as-code operations with Terraform for Hetzner Cloud resources. Enforces environment-based safety workflows.

Environment Safety Model

Core Operations

Plan Changes

Preview infrastructure changes before applying:

terraform_plan environment="prod"
  → Shows diff of proposed changes
  → No state modification
  → Safe to run anytime

For all environments:

terraform_plan environment="global"
terraform_plan environment="prod"
terraform_plan environment="test"

Apply Changes

Test environment (direct allowed):

terraform_plan environment="test"
  → Review changes
terraform_apply environment="test" confirmed=true
  → Applied directly

Production/Global (PR workflow):

1. Create feature branch
2. Make Terraform changes
3. Run terraform_plan to verify
4. Create PR with plan output
5. Merge after review
6. Apply from main branch (CI/CD or manual)

View Current State

Inspect current Terraform state:

terraform_show environment="prod"
  → Current resource inventory
  → Useful for debugging drift

Collect Platform State

Capture full platform state for documentation:

collect_state environment="prod"
  → Docker services, containers, volumes
  → Outputs to state-snapshots/
  → Commit to git for drift detection

Infrastructure Components

Global Resources (infra/terraform/global/)

• Hetzner Cloud network (platform-net)
• Subnets per environment
• Firewalls (SSH, HTTP, HTTPS, internal)
• Object storage buckets (backups, terraform state)

Per-Environment Resources (infra/terraform/envs/<env>/)

• Server instances (CPX31, CCX13, etc.)
• Volumes (data persistence)
• Floating IPs (if configured)
• Server-specific firewall attachments

Common Workflows

Add New Server

1. Create Terraform config in infra/terraform/envs/new-server/
2. Define server, volume, network attachment
3. Run terraform_plan environment="new-server"
4. Create PR with plan
5. After merge, terraform_apply environment="new-server" confirmed=true
6. Bootstrap with /dh:bootstrap

Resize Server

1. Update server_type in Terraform
2. Plan: terraform_plan environment="<env>"
3. Warning: May require server restart
4. Apply during maintenance window

Add Storage Volume

1. Add hcloud_volume resource
2. Plan and review size/location
3. Apply
4. Mount on server via SSH

Bootstrap New Host

After Terraform provisions a server, bootstrap it:

/dh:bootstrap host=<new-host>

Bootstrap sequence:

1. SSH connectivity test
2. Install Docker
3. Join Docker Swarm (manager or worker)
4. Install Tailscale
5. Configure monitoring agents
6. Verify health

State Management

Terraform State

• Stored in Cloudflare R2 (S3-compatible)
• Backend configured per environment
• State locking via DynamoDB-compatible

Platform State Snapshots

• Generated by collect_state
• Stored in state-snapshots/ in git
• Compare for drift detection:

`` diff state-snapshots/prod/latest.json state-snapshots/prod/previous.json ``

Integration with dh-guardrails

The dh-guardrails skill enforces:

• No terraform destroy without explicit confirmation
• PR-first for production changes
• Backup verification before destructive operations

Error Handling