Services Control Plane

Control plane for managing hosted StreamingFast services on Kubernetes.

Project Structure

├── cli/                   # TypeScript CLI for interacting with control plane
├── cmd/control-freak/     # Go gRPC server
├── grpc/                  # gRPC service implementations
├── k8s/
│   ├── deployer/          # K8s deployment logic
│   └── setup/             # Local development environment (START HERE!)
├── pb/                    # Generated protobuf code
├── proto/                 # Public proto definitions
└── proto-internal/        # Internal proto definitions

🚀 Quick Start (Local Development)

Want to test without touching production? Start here!

# One-time setup (creates local K8s cluster)
go run ./cmd/control-freak k8s setup

# Start port forwards (runs in foreground, Ctrl+C to stop)
go run ./cmd/control-freak k8s port-forward

# Run CLI (in another terminal)
cd cli
NODE_ENV=local bun run index.ts

🎉 You now have a complete local environment with:

• Local Kubernetes cluster (Kind)
• gRPC server running
• Redis for state
• 3 test deployments you can scale

📖 Full guide: k8s/setup/QUICKSTART.md
📚 Detailed docs: k8s/setup/README.md

Features

• Deploy: Create new service deployments on Kubernetes
• SetReplica: Scale deployments up or down
• Pod Tracking: Real-time monitoring of deployment state via Redis
• TUI: Beautiful terminal interface for operations

Production Deployment

# Build and run gRPC server
go build -o control-freak ./cmd/control-freak
./control-freak

# Run CLI (in separate terminal)
cd cli
bun run index.ts

Self-Hosted Runner Setup (for Local Testing)

1. Download and install GitHub Actions Runner
2. Configure with your repo token
3. Ensure Kind, Docker, kubectl are installed
4. Runner will execute tests on your local machine/cluster

Cloud Runner Setup

GitHub Actions uses ubuntu-latest with Kind for isolated testing.

Development

Make server changes

# Edit Go code, then:
go run ./cmd/control-freak k8s restart

Make CLI changes

# Edit TypeScript code, then:
cd cli
NODE_ENV=local bun run index.ts

Teardown local environment

go run ./cmd/control-freak k8s teardown

🤖 AI-Driven Development with GitHub Copilot

This project is optimized for AI-assisted development using GitHub Copilot and GitHub Actions.

Workflow

1. Planning: Create GitHub Issues for feature requests or bugs
2. Development: Copilot suggests code changes in PRs
3. Testing: GitHub Actions automatically run tests on Kind cluster
4. Review: Copilot assists with code reviews and merges

Running Tests

• Local: Use go test ./k8s/... -v (auto-sets up Kind cluster if needed)
• CI: GitHub Actions automatically run tests on Kind cluster
• Specific Suite: Use workflow dispatch with test_suite input

PR Lifecycle

• Copilot creates PRs with code changes
• Actions run tests automatically
• On success, PR can be auto-merged (configure branch protection)

Environment Variables

Variable	Default	Description
NODE_ENV	production	local for dev cluster, production for prod
GRPC_HOST	Varies by env	gRPC server address
REDIS_ADDR	Varies by env	Redis server address
NAMESPACE	default	Kubernetes namespace for deployments

Architecture

┌─────────────┐      gRPC       ┌──────────────┐
│     CLI     │◄────────────────►│ control-freak│
│ (TypeScript)│                  │   (Go)       │
└─────────────┘                  └──────┬───────┘
                                        │
                                        │ manages
                                        ▼
                                 ┌──────────────┐
                                 │  Kubernetes  │
                                 │  StatefulSets│
                                 └──────────────┘
                                        │
                                        │ state
                                        ▼
                                 ┌──────────────┐
                                 │    Redis     │
                                 └──────────────┘

License

See LICENSE file.