Sienna Meridian Satterwhite
db97853f9c
Adds `sunbeam_sdk::registry`, the discovery layer that the new
service-oriented CLI commands use to resolve names like "hydra",
"auth", or "ory" into the right Kubernetes resources.
Instead of duplicating service definitions in Rust code, the registry
queries Deployments, StatefulSets, DaemonSets, and ConfigMaps that
carry the `sunbeam.pt/service` label and reads everything else from
labels and annotations:
- sunbeam.pt/service / sunbeam.pt/category — required, the primary keys
- sunbeam.pt/display-name — human-readable label for status output
- sunbeam.pt/kv-path — OpenBao KV v2 path (for `sunbeam secrets <svc>`)
- sunbeam.pt/db-user / sunbeam.pt/db-name — CNPG postgres credentials
- sunbeam.pt/build-target — buildkit target for `sunbeam build`
- sunbeam.pt/depends-on — comma-separated dependency names
- sunbeam.pt/health-check — pod-ready / cnpg / seal-status / HTTP path
- sunbeam.pt/virtual=true — for ConfigMap-only "external" services
`ServiceRegistry::resolve(input)` does name → category → namespace
matching in that order, so `sunbeam logs hydra`, `sunbeam restart auth`,
and `sunbeam status ory` all work uniformly.
Multi-deployment services (e.g. messages-{backend,mta-in,mta-out})
share a service label and the registry merges them into a single
ServiceDefinition with multiple `deployments`.
Includes 14 unit tests covering name/category/namespace resolution,
case-insensitivity, virtual services, and the empty registry case.
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.