Goman

A serverless K3s cluster manager for AWS. Deploy production-ready Kubernetes clusters without managing infrastructure.

Features

• 🚀 Serverless Architecture - No management servers required, uses AWS Lambda for reconciliation
• 🔒 Secure Access - Built-in SSM tunneling for secure cluster access from your local machine
• ⚡ Fast Deployment - Optimized parallel provisioning gets clusters running in ~8 minutes
• 🎨 Modern TUI - Interactive terminal interface with real-time status updates
• 💰 Cost Effective - Pay only for the EC2 instances you use, no management overhead
• 🔄 Self-Healing - Automatic reconciliation ensures clusters stay in desired state

Installation

From Release

# macOS (Apple Silicon)
curl -L https://github.com/MadHouseLabs/goman/releases/latest/download/goman-darwin-arm64.tar.gz | tar xz
sudo mv goman-darwin-arm64 /usr/local/bin/goman

# macOS (Intel)
curl -L https://github.com/MadHouseLabs/goman/releases/latest/download/goman-darwin-amd64.tar.gz | tar xz
sudo mv goman-darwin-amd64 /usr/local/bin/goman

# Linux
curl -L https://github.com/MadHouseLabs/goman/releases/latest/download/goman-linux-amd64.tar.gz | tar xz
sudo mv goman-linux-amd64 /usr/local/bin/goman

From Source

git clone https://github.com/MadHouseLabs/goman.git
cd goman
go build -o goman ./cmd/goman
sudo mv goman /usr/local/bin/

Setup

# Configure AWS credentials
aws configure

# Initialize AWS infrastructure (S3, Lambda, DynamoDB)
goman init

# Launch TUI
goman

Quick Start

# Initialize AWS infrastructure (one-time setup)
goman init

# Launch TUI
goman

# Create your first cluster
goman cluster create my-cluster --region=us-east-1 --mode=dev

Usage

Interactive TUI

Launch the terminal interface with real-time cluster status:

goman

Keyboard shortcuts:

• c - Create new cluster
• d - Delete selected cluster
• e - Edit cluster configuration
• Enter - View cluster details & metrics
• Tab - Switch between panels
• q - Quit

CLI Commands

Cluster Management

# Create clusters
goman cluster create my-cluster --region=us-east-1 --mode=dev    # Single master
goman cluster create ha-cluster --region=us-west-2 --mode=ha      # 3 masters for HA

# List all clusters
goman cluster list

# Delete cluster
goman cluster delete my-cluster

Kubernetes Access

# Get kubeconfig
goman kube my-cluster                        # Output kubeconfig
goman kube my-cluster > ~/.kube/config       # Save to file

# Execute kubectl commands (automatic SSM tunnel)
goman kube my-cluster -- kubectl get nodes   # Specify cluster
goman kube -- kubectl get pods -A            # Use current cluster
goman kube -- k9s                            # Launch k9s
goman kube -- helm install myapp ./chart     # Run helm
goman kube -- bash                           # Shell with KUBECONFIG

Tunnel Management

# Connect to cluster (sets as current)
goman cluster connect my-cluster

# Check tunnel status
goman tunnel status

# Clean up tunnels
goman tunnel cleanup

Cluster Configuration

Edit clusters to add worker node pools:

name: my-cluster
mode: dev           # or 'ha' for 3 masters
region: us-east-1
instanceType: t3.medium

nodePools:
  - name: workers
    count: 3
    instanceType: t3.large
    labels:
      role: worker

Architecture

Goman uses a serverless event-driven architecture:

User (TUI/CLI) → S3 (State) → Lambda (Controller) → EC2 (K3s Clusters)
                     ↑                                      ↓
                     └──────── Status Updates ←────────────┘

Key Components:

• S3: Stores cluster configurations and state
• Lambda: Reconciles desired vs actual cluster state
• DynamoDB: Distributed locking for safe concurrent operations
• SSM: Secure tunneling for kubectl access
• EventBridge: Monitors EC2 state changes

Requirements

• AWS Account
• AWS CLI configured with credentials
• Go 1.23+ (for building from source)

License

MIT