studio/cli
2
0
Fork 0
Code Issues Pull Requests Actions Packages Releases 4 Wiki Activity

docs: update README for Rust workspace layout

Browse Source
This commit is contained in:
Sienna Meridian Satterwhite
2026-03-21 14:51:45 +00:00
parent 3ef3fc0255
commit 46d21330b1
1 changed files with 113 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
README.md
View File

@@ -1,16 +1,15 @@
# Sunbeam CLI # Sunbeam CLI
**Sunbeam CLI** is a powerful local development stack manager for Kubernetes-based applications. It simplifies cluster management, service operations, secret handling, and manifest deployment for development environments. **Sunbeam CLI** is a local development stack manager for Kubernetes-based applications. It simplifies cluster management, service operations, secret handling, and manifest deployment.
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/) [![Rust](https://img.shields.io/badge/rust-2024%20edition-orange.svg)](https://www.rust-lang.org/)
[![Documentation](https://img.shields.io/badge/docs-comprehensive-brightgreen.svg)](docs/)
## Quick Start ## Quick Start
```bash ```bash
# Install Sunbeam CLI # Install from source
pip install . cargo install --path sunbeam
# Start your local cluster # Start your local cluster
sunbeam up sunbeam up
@@ -24,41 +23,68 @@ sunbeam status
## Features ## Features
- **Cluster Management**: Bring up and tear down local Kubernetes clusters with Lima VM - **Cluster Management**: Bring up local Kubernetes clusters with cert-manager, Linkerd, TLS
- **Service Operations**: Manage services, view logs, and perform health checks - **Service Operations**: Status, logs, restart, health checks across namespaces
- **Secret Management**: Secure credential handling with OpenBao integration - **Secret Management**: OpenBao KV seeding, DB engine config, VSO verification
- **Manifest Management**: Kustomize-based manifest application with domain substitution - **Manifest Management**: Kustomize + Helm builds with domain/email substitution
- **User Management**: Identity management for development environments - **User Management**: Kratos identity CRUD, onboarding/offboarding with mailbox and project provisioning
- **Tool Bundling**: Automatic download and management of required binaries - **Image Building**: Buildkit-based builds with registry push and rollout deploy
- **Multi-environment Support**: Local development and production deployment - **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 ## Installation
### Prerequisites ### Prerequisites
- Python 3.11+ - Rust (2024 edition)
- Docker - Docker
- Lima (for local VM management) - Lima (for local VM management)
- kubectl, kustomize, helm (automatically managed by Sunbeam) - A running Kubernetes cluster (kubectl context `sunbeam` for local dev)
### Install from Source ### Install from Source
```bash ```bash
# Clone the repository
git clone https://src.sunbeam.pt/studio/cli.git git clone https://src.sunbeam.pt/studio/cli.git
cd cli cd cli
cargo install --path sunbeam
# Install dependencies
pip install .
# Verify installation
sunbeam --help sunbeam --help
``` ```
### Install in Development Mode ### Self-Update
Once installed, sunbeam can update itself:
```bash ```bash
pip install -e . 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 ## Usage
@@ -66,227 +92,102 @@ pip install -e .
### Basic Commands ### Basic Commands
```bash ```bash
# Start local cluster sunbeam up # Full cluster bring-up
sunbeam up sunbeam status # Pod health across all namespaces
sunbeam status ory # Scoped to namespace
# Check cluster status sunbeam apply # Build + apply all manifests
sunbeam status sunbeam apply lasuite # Apply single namespace
sunbeam logs ory/kratos # Stream logs
# Apply all manifests sunbeam logs ory/kratos -f # Follow mode
sunbeam apply sunbeam restart # Rolling restart all services
sunbeam restart ory/kratos # Restart specific deployment
# Apply specific namespace
sunbeam apply lasuite
# View service logs
sunbeam logs ory/kratos
# Restart services
sunbeam restart ory/kratos
# Stop cluster
sunbeam down
``` ```
### Production Deployment ### Configuration
```bash ```bash
# Set SSH host for production sunbeam config set --domain sunbeam.pt --host user@server.example.com
export SUNBEAM_SSH_HOST=user@your-server.example.com sunbeam config get
sunbeam config use-context production
# Apply production manifests
sunbeam apply --env production --domain sunbeam.pt --email ops@sunbeam.pt
# Check production status
sunbeam status --env production
``` ```
## Documentation
Comprehensive documentation is available in the [`docs/`](docs/) directory:
- **[CLI Reference](docs/cli-reference.md)** - Complete command reference
- **[Core Modules](docs/core-modules.md)** - Detailed module documentation
- **[API Reference](docs/api-reference.md)** - Full API documentation
- **[Usage Examples](docs/usage-examples.md)** - Practical usage patterns
- **[Utility Modules](docs/utility-modules.md)** - Helper function documentation
## Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `SUNBEAM_SSH_HOST` | SSH host for production access | Production only |
| `SUNBEAM_ACME_EMAIL` | ACME email for cert-manager | Optional |
### Configuration Files
Sunbeam uses kustomize overlays for environment-specific configuration:
```
infrastructure/
├── base/ # Base manifests
└── overlays/ # Environment overlays
├── local/ # Local development
└── production/ # Production deployment
```
## Architecture
```mermaid
graph TD
A[Sunbeam CLI] --> B[Kubernetes Interface]
A --> C[Manifest Management]
A --> D[Service Operations]
A --> E[Secret Management]
A --> F[User Management]
A --> G[Image Building]
A --> H[Tool Management]
B --> B1[kubectl wrapper]
B --> B2[SSH tunnel management]
B --> B3[Domain discovery]
C --> C1[Kustomize integration]
C --> C2[Webhook handling]
C --> C3[ConfigMap tracking]
D --> D1[Health monitoring]
D --> D2[Log streaming]
D --> D3[Service restart]
```
## Development Workflow
### Building and Deploying ### Building and Deploying
```bash ```bash
# Build a component sunbeam build proxy # Build image
sunbeam build proxy sunbeam build proxy --push # Build + push to registry
sunbeam build proxy --deploy # Build + push + apply + restart
# Build and push to registry sunbeam build proxy --no-cache # Disable buildkit cache
sunbeam build proxy --push sunbeam mirror # Mirror amd64-only images
# Build, push, and deploy
sunbeam build proxy --deploy
``` ```
### User Management ### User Management
```bash ```bash
# Create user
sunbeam user create user@example.com --name "User Name"
# Set password
sunbeam user set-password user@example.com "password123"
# List users
sunbeam user list 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 ### Secret Management
```bash ```bash
# Seed all credentials sunbeam seed # Generate + store all credentials in OpenBao
sunbeam seed sunbeam verify # E2E VSO + OpenBao integration test
# Verify VSO + OpenBao integration
sunbeam verify
``` ```
## Contributing ### Project Management
Contributions are welcome! Please follow these guidelines:
1. **Fork the repository** and create your branch
2. **Follow conventional commits** for commit messages
3. **Add tests** for new features
4. **Update documentation** for changes
5. **Submit a pull request**
### Development Setup
```bash ```bash
# Clone repository sunbeam pm list # List tickets (Planka + Gitea)
git clone https://src.sunbeam.pt/studio/cli.git sunbeam pm show p:42 # Show Planka card
cd cli sunbeam pm show g:studio/cli#7 # Show Gitea issue
sunbeam pm create "Title" --source gitea --target studio/cli
# Install development dependencies sunbeam pm assign p:42 user@example.com
pip install -e .[dev] sunbeam pm close g:studio/cli#7
# Run tests
python -m pytest sunbeam/tests/
``` ```
### Commit Message Format ### Health Checks
```
<type>(<scope>): <description>
<body>
<footer>
```
**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Adding or modifying tests
- `chore`: Maintenance tasks
## Troubleshooting
### Common Issues
**Cluster not starting:**
```bash
limactl list
limactl start sunbeam
```
**Manifest apply failures:**
```bash
sunbeam k8s get events -A
sunbeam logs cert-manager/cert-manager
```
**Secret sync problems:**
```bash
sunbeam verify
sunbeam bao status
```
### Debugging
```bash ```bash
# Direct kubectl access sunbeam check # Run all functional probes
sunbeam k8s get pods -A sunbeam check devtools # Scoped to namespace
```
# Describe resources ### Passthrough
sunbeam k8s describe pod ory/kratos-abc123
# View events ```bash
sunbeam k8s get events --sort-by=.metadata.creationTimestamp sunbeam k8s get pods -A # kubectl passthrough
sunbeam bao status # bao CLI inside OpenBao pod
```
### Production
```bash
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
```bash
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:
```bash
pip install -e .
python -m sunbeam --help
``` ```
## License ## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. MIT — see [LICENSE](LICENSE).
## Acknowledgments
- Kubernetes community for the excellent ecosystem
- Kustomize team for manifest management
- OpenBao for secret management
- Lima for VM management
## Contact
For questions, issues, or contributions:
- **Git Issues**: [https://src.sunbeam.pt/studio/cli/issues](https://src.sunbeam.pt/studio/cli/issues)
- **Documentation**: [https://src.sunbeam.pt/studio/cli](https://src.sunbeam.pt/studio/cli)