Sienna Meridian Satterwhite
b5795fd97b
`sunbeam vpn create-key` calls Headscale's REST API at
`/api/v1/preauthkey` to mint a new pre-auth key for onboarding a new
client. Reads `vpn-url` and `vpn-api-key` from the active context;
the user generates the API key once via `headscale apikeys create`
on the cluster and stores it in their context config.
Flags:
- --user <name> Headscale user the key belongs to
- --reusable allow multiple registrations with the same key
- --ephemeral auto-delete the node when its map stream drops
- --expiration <dur> human-friendly lifetime ("30d", "1h", "2w")
Also adds a `vpn-tls-insecure` context flag that controls TLS
verification across the whole VPN integration: it's now used by both
the daemon (for the Noise control connection + DERP relay) and the
new create-key REST client. Test stacks with self-signed certs set
this to true; production stacks leave it false.
Verified end-to-end against the docker test stack:
$ sunbeam vpn create-key --user test --reusable --expiration 1h
==> Creating pre-auth key on https://localhost:8443
Pre-auth key for user 'test':
ebcd77f51bf30ef373c9070382b834859935797a90c2647f
Add it to a context with:
sunbeam config set --context <ctx> vpn-auth-key ebcd77f5...
Sunbeam CLI
Sunbeam CLI is a local development stack manager for Kubernetes-based applications. It simplifies cluster management, service operations, secret handling, and manifest deployment.
Quick Start
# Install from source
cargo install --path sunbeam
# Start your local cluster
sunbeam up
# Apply manifests
sunbeam apply
# Check status
sunbeam status
Features
- Cluster Management: Bring up local Kubernetes clusters with cert-manager, Linkerd, TLS
- Service Operations: Status, logs, restart, health checks across namespaces
- Secret Management: OpenBao KV seeding, DB engine config, VSO verification
- Manifest Management: Kustomize + Helm builds with domain/email substitution
- User Management: Kratos identity CRUD, onboarding/offboarding with mailbox and project provisioning
- Image Building: Buildkit-based builds with registry push and rollout deploy
- Project Management: Unified ticket management across Planka and Gitea
- Self-Update: Binary update from the latest mainline commit
- Tool Bundling: kustomize and helm binaries embedded at compile time
Installation
Prerequisites
- Rust (2024 edition)
- Docker
- Lima (for local VM management)
- A running Kubernetes cluster (kubectl context
sunbeamfor local dev)
Install from Source
git clone https://src.sunbeam.pt/studio/cli.git
cd cli
cargo install --path sunbeam
sunbeam --help
Self-Update
Once installed, sunbeam can update itself:
sunbeam update
Workspace Layout
cli/
Cargo.toml # [workspace] — sunbeam-sdk + sunbeam
sunbeam-sdk/ # Library crate — all logic
src/
lib.rs
error.rs, config.rs, output.rs, constants.rs
kube/ # client, apply, exec, secrets, kustomize_build, tools
openbao/ # BaoClient HTTP API
auth/ # OAuth2 PKCE, token cache
services/ # status, logs, get, restart
images/ # build, mirror, per-service builders
secrets/ # seed, verify, KV seeding, DB engine
users/ # identity CRUD, provisioning (mailbox, projects, email)
checks/ # functional health probes, S3 auth
pm/ # Planka + Gitea ticket management
cluster/ # cert-manager, Linkerd, TLS
manifests/ # kustomize apply, namespace filtering
gitea/ # bootstrap (orgs, repos, OIDC)
update/ # self-update, version
sunbeam/ # Binary crate — thin CLI wrapper
src/
main.rs # tokio, rustls, tracing init
cli.rs # Clap structs + dispatch
Usage
Basic Commands
sunbeam up # Full cluster bring-up
sunbeam status # Pod health across all namespaces
sunbeam status ory # Scoped to namespace
sunbeam apply # Build + apply all manifests
sunbeam apply lasuite # Apply single namespace
sunbeam logs ory/kratos # Stream logs
sunbeam logs ory/kratos -f # Follow mode
sunbeam restart # Rolling restart all services
sunbeam restart ory/kratos # Restart specific deployment
Configuration
sunbeam config set --domain sunbeam.pt --host user@server.example.com
sunbeam config get
sunbeam config use-context production
Building and Deploying
sunbeam build proxy # Build image
sunbeam build proxy --push # Build + push to registry
sunbeam build proxy --deploy # Build + push + apply + restart
sunbeam build proxy --no-cache # Disable buildkit cache
sunbeam mirror # Mirror amd64-only images
User Management
sunbeam user list
sunbeam user create user@example.com --name "User Name"
sunbeam user set-password user@example.com
sunbeam user onboard new@example.com --name "New User" --department Engineering
sunbeam user offboard departed@example.com
sunbeam user recover user@example.com
Secret Management
sunbeam seed # Generate + store all credentials in OpenBao
sunbeam verify # E2E VSO + OpenBao integration test
Project Management
sunbeam pm list # List tickets (Planka + Gitea)
sunbeam pm show p:42 # Show Planka card
sunbeam pm show g:studio/cli#7 # Show Gitea issue
sunbeam pm create "Title" --source gitea --target studio/cli
sunbeam pm assign p:42 user@example.com
sunbeam pm close g:studio/cli#7
Health Checks
sunbeam check # Run all functional probes
sunbeam check devtools # Scoped to namespace
Passthrough
sunbeam k8s get pods -A # kubectl passthrough
sunbeam bao status # bao CLI inside OpenBao pod
Production
sunbeam config set --domain sunbeam.pt --host user@62.210.145.138
sunbeam config use-context production
sunbeam apply # Opens SSH tunnel automatically
Running Tests
cargo nextest run --workspace # 232 tests
cargo test --workspace # Alternative
Python CLI (Legacy)
The original Python implementation is in the sunbeam/ package and remains functional:
pip install -e .
python -m sunbeam --help
License
MIT — see LICENSE.