From 1a977814ad6620a91e837df38c3fa2d60e866a91 Mon Sep 17 00:00:00 2001 From: Sienna Meridian Satterwhite Date: Sat, 7 Mar 2026 14:50:36 +0000 Subject: [PATCH] docs: add comprehensive documentation for sunbeam CLI --- docs/api-reference.md | 518 ++++++++++++++++++++++++++++++++++++++++ docs/cli-reference.md | 254 ++++++++++++++++++++ docs/core-modules.md | 262 ++++++++++++++++++++ docs/index.md | 67 ++++++ docs/usage-examples.md | 486 +++++++++++++++++++++++++++++++++++++ docs/utility-modules.md | 286 ++++++++++++++++++++++ 6 files changed, 1873 insertions(+) create mode 100644 docs/api-reference.md create mode 100644 docs/cli-reference.md create mode 100644 docs/core-modules.md create mode 100644 docs/index.md create mode 100644 docs/usage-examples.md create mode 100644 docs/utility-modules.md diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..f855446 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,518 @@ +--- +layout: default +title: API Reference +description: Comprehensive API documentation for all Sunbeam modules +parent: index +toc: true +--- + +# API Reference + +This section provides comprehensive API documentation for all Sunbeam modules, including function signatures, parameters, return values, and usage examples. + +## CLI Module (`sunbeam.cli`) + +### Main Function + +```python +def main() -> None +``` + +**Description:** Main entry point for the Sunbeam CLI. Parses arguments and dispatches to appropriate command handlers. + +**Environment Variables:** +- `SUNBEAM_SSH_HOST`: Required for production environment + +**Global Arguments:** +- `--env`: Target environment (`local` or `production`) +- `--context`: kubectl context override +- `--domain`: Domain suffix for production +- `--email`: ACME email for cert-manager + +### Command Dispatch + +The main function uses a dispatch pattern to route commands to their handlers: + +```python +# Example dispatch pattern +if args.verb == "up": + from sunbeam.cluster import cmd_up + cmd_up() +elif args.verb == "status": + from sunbeam.services import cmd_status + cmd_status(args.target) +# ... additional commands +``` + +## Kubernetes Module (`sunbeam.kube`) + +### Context Management + +```python +def set_context(ctx: str, ssh_host: str = "") -> None +``` + +**Parameters:** +- `ctx`: Kubernetes context name +- `ssh_host`: SSH host for production tunnel (optional) + +**Description:** Sets the active kubectl context and SSH host for production environments. + +```python +def context_arg() -> str +``` + +**Returns:** `--context=` string for subprocess calls + +### Kubernetes Operations + +```python +def kube(*args, input=None, check=True) -> subprocess.CompletedProcess +``` + +**Parameters:** +- `*args`: kubectl arguments +- `input`: stdin input (optional) +- `check`: Whether to raise exception on non-zero exit (default: True) + +**Returns:** CompletedProcess result + +**Description:** Run kubectl against active context with automatic SSH tunnel management. + +```python +def kube_out(*args) -> str +``` + +**Parameters:** +- `*args`: kubectl arguments + +**Returns:** stdout output (empty string on failure) + +```python +def kube_ok(*args) -> bool +``` + +**Parameters:** +- `*args`: kubectl arguments + +**Returns:** True if command succeeds + +```python +def kube_apply(manifest: str, *, server_side: bool = True) -> None +``` + +**Parameters:** +- `manifest`: YAML manifest string +- `server_side`: Use server-side apply (default: True) + +**Description:** Apply YAML manifest via kubectl. + +### Resource Management + +```python +def ns_exists(ns: str) -> bool +``` + +**Parameters:** +- `ns`: Namespace name + +**Returns:** True if namespace exists + +```python +def ensure_ns(ns: str) -> None +``` + +**Parameters:** +- `ns`: Namespace name + +**Description:** Ensure namespace exists, creating if necessary. + +```python +def create_secret(ns: str, name: str, **literals) -> None +``` + +**Parameters:** +- `ns`: Namespace name +- `name`: Secret name +- `**literals`: Key-value pairs for secret data + +**Description:** Create or update Kubernetes secret idempotently. + +### Kustomize Integration + +```python +def kustomize_build(overlay: Path, domain: str, email: str = "") -> str +``` + +**Parameters:** +- `overlay`: Path to kustomize overlay directory +- `domain`: Domain suffix for substitution +- `email`: ACME email for substitution (optional) + +**Returns:** Built manifest YAML with substitutions applied + +**Description:** Build kustomize overlay with domain/email substitution and helm support. + +### SSH Tunnel Management + +```python +def ensure_tunnel() -> None +``` + +**Description:** Open SSH tunnel to production cluster if needed. Automatically checks if tunnel is already open. + +### Utility Functions + +```python +def parse_target(s: str | None) -> tuple[str | None, str | None] +``` + +**Parameters:** +- `s`: Target string in format `namespace/name` or `namespace` + +**Returns:** Tuple of (namespace, name) + +**Examples:** +```python +parse_target("ory/kratos") # ("ory", "kratos") +parse_target("lasuite") # ("lasuite", None) +parse_target(None) # (None, None) +``` + +```python +def domain_replace(text: str, domain: str) -> str +``` + +**Parameters:** +- `text`: Input text containing DOMAIN_SUFFIX placeholders +- `domain`: Domain to substitute + +**Returns:** Text with DOMAIN_SUFFIX replaced by domain + +```python +def get_lima_ip() -> str +``` + +**Returns:** IP address of Lima VM + +**Description:** Discover Lima VM IP using multiple fallback methods. + +```python +def get_domain() -> str +``` + +**Returns:** Active domain from cluster state + +**Description:** Discover domain from various cluster sources with fallback to Lima IP. + +### Command Functions + +```python +def cmd_k8s(kubectl_args: list[str]) -> int +``` + +**Parameters:** +- `kubectl_args`: Arguments to pass to kubectl + +**Returns:** Exit code + +**Description:** Transparent kubectl passthrough for active context. + +```python +def cmd_bao(bao_args: list[str]) -> int +``` + +**Parameters:** +- `bao_args`: Arguments to pass to bao CLI + +**Returns:** Exit code + +**Description:** Run bao CLI inside OpenBao pod with root token injection. + +## Manifests Module (`sunbeam.manifests`) + +### Main Command + +```python +def cmd_apply(env: str = "local", domain: str = "", email: str = "", namespace: str = "") -> None +``` + +**Parameters:** +- `env`: Environment (`local` or `production`) +- `domain`: Domain suffix (required for production) +- `email`: ACME email for cert-manager +- `namespace`: Limit apply to specific namespace (optional) + +**Description:** Build kustomize overlay, apply domain/email substitution, and apply manifests with convergence handling. + +### Cleanup Functions + +```python +def pre_apply_cleanup(namespaces=None) -> None +``` + +**Parameters:** +- `namespaces`: List of namespaces to clean (default: all managed namespaces) + +**Description:** Clean up immutable resources and stale secrets before apply. + +### ConfigMap Management + +```python +def _snapshot_configmaps() -> dict +``` + +**Returns:** Dictionary of `{ns/name: resourceVersion}` for all ConfigMaps + +```python +def _restart_for_changed_configmaps(before: dict, after: dict) -> None +``` + +**Parameters:** +- `before`: ConfigMap snapshot before apply +- `after`: ConfigMap snapshot after apply + +**Description:** Restart deployments that mount changed ConfigMaps. + +### Webhook Management + +```python +def _wait_for_webhook(ns: str, svc: str, timeout: int = 120) -> bool +``` + +**Parameters:** +- `ns`: Namespace of webhook service +- `svc`: Service name +- `timeout`: Maximum wait time in seconds + +**Returns:** True if webhook becomes ready + +**Description:** Wait for webhook service endpoint to become available. + +### Utility Functions + +```python +def _filter_by_namespace(manifests: str, namespace: str) -> str +``` + +**Parameters:** +- `manifests`: Multi-document YAML string +- `namespace`: Namespace to filter by + +**Returns:** Filtered YAML containing only resources for specified namespace + +**Description:** Filter manifests by namespace using string matching. + +## Services Module (`sunbeam.services`) + +### Status Command + +```python +def cmd_status(target: str | None) -> None +``` + +**Parameters:** +- `target`: Optional target in format `namespace` or `namespace/name` + +**Description:** Show pod health across managed namespaces with VSO sync status. + +### Log Command + +```python +def cmd_logs(target: str, follow: bool) -> None +``` + +**Parameters:** +- `target`: Target in format `namespace/name` +- `follow`: Whether to stream logs + +**Description:** Stream logs for a service using label-based pod selection. + +### Get Command + +```python +def cmd_get(target: str, output: str = "yaml") -> None +``` + +**Parameters:** +- `target`: Target in format `namespace/name` +- `output`: Output format (`yaml`, `json`, or `wide`) + +**Description:** Get raw kubectl output for a resource. + +### Restart Command + +```python +def cmd_restart(target: str | None) -> None +``` + +**Parameters:** +- `target`: Optional target in format `namespace` or `namespace/name` + +**Description:** Rolling restart of services. If no target, restarts all managed services. + +### VSO Sync Status + +```python +def _vso_sync_status() -> None +``` + +**Description:** Print VaultStaticSecret and VaultDynamicSecret sync health status. + +## Tools Module (`sunbeam.tools`) + +### Tool Management + +```python +def ensure_tool(name: str) -> Path +``` + +**Parameters:** +- `name`: Tool name (must be in TOOLS dictionary) + +**Returns:** Path to executable + +**Raises:** +- `ValueError`: Unknown tool +- `RuntimeError`: SHA256 verification failure + +**Description:** Ensure tool is available, downloading and verifying if necessary. + +```python +def run_tool(name: str, *args, **kwargs) -> subprocess.CompletedProcess +``` + +**Parameters:** +- `name`: Tool name +- `*args`: Arguments to pass to tool +- `**kwargs`: Additional subprocess.run parameters + +**Returns:** CompletedProcess result + +**Description:** Run tool, ensuring it's downloaded first. Handles PATH setup for kustomize/helm integration. + +### Internal Utilities + +```python +def _sha256(path: Path) -> str +``` + +**Parameters:** +- `path`: Path to file + +**Returns:** SHA256 hash of file contents + +**Description:** Calculate SHA256 hash (internal utility). + +## Output Module (`sunbeam.output`) + +### Output Functions + +```python +def step(msg: str) -> None +``` + +**Parameters:** +- `msg`: Message to display + +**Description:** Print step header with `==>` prefix. + +```python +def ok(msg: str) -> None +``` + +**Parameters:** +- `msg`: Message to display + +**Description:** Print success/info message with indentation. + +```python +def warn(msg: str) -> None +``` + +**Parameters:** +- `msg`: Warning message + +**Description:** Print warning to stderr. + +```python +def die(msg: str) -> None +``` + +**Parameters:** +- `msg`: Error message + +**Description:** Print error to stderr and exit with code 1. + +```python +def table(rows: list[list[str]], headers: list[str]) -> str +``` + +**Parameters:** +- `rows`: List of row data +- `headers`: List of column headers + +**Returns:** Formatted table string + +**Description:** Generate aligned text table with automatic column sizing. + +## Usage Patterns + +### Typical Command Flow + +```python +# CLI entry point +from sunbeam.cli import main +main() + +# Module usage example +from sunbeam.kube import kube, kube_out, set_context +from sunbeam.output import step, ok, warn + +# Set context +set_context("sunbeam") + +# Check cluster status +step("Checking cluster status...") +if kube_ok("get", "nodes"): + ok("Cluster is ready") + node_count = kube_out("get", "nodes", "--no-headers").count("\n") + 1 + ok(f"Found {node_count} nodes") +else: + warn("Cluster not ready") +``` + +### Error Handling Pattern + +```python +from sunbeam.output import step, ok, die +from sunbeam.kube import kube_ok + +step("Validating cluster requirements...") + +# Check required components +required = [ + ("kube-system", "kube-dns"), + ("ingress-nginx", "ingress-nginx-controller") +] + +for ns, deployment in required: + if not kube_ok("get", "deployment", deployment, "-n", ns): + die(f"Required deployment {ns}/{deployment} not found") + +ok("All requirements satisfied") +``` + +### Tool Usage Pattern + +```python +from sunbeam.tools import ensure_tool, run_tool + +# Ensure kubectl is available +kubectl_path = ensure_tool("kubectl") + +# Run kubectl command +result = run_tool("kubectl", "get", "pods", "-A", + capture_output=True, text=True) +print(result.stdout) +``` \ No newline at end of file diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..fe59246 --- /dev/null +++ b/docs/cli-reference.md @@ -0,0 +1,254 @@ +--- +layout: default +title: CLI Reference +description: Complete command reference for Sunbeam CLI +parent: index +toc: true +--- + +# CLI Reference + +The Sunbeam CLI provides a comprehensive set of commands for managing local development environments. + +## Command Structure + +```bash +sunbeam [global-options] [verb-options] +``` + +### Global Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--env` | Target environment (`local` or `production`) | `local` | +| `--context` | kubectl context override | Auto-determined | +| `--domain` | Domain suffix for production deploys | `` | +| `--email` | ACME email for cert-manager | `` | + +## Commands + +### Cluster Management + +#### `sunbeam up` +Bring up the full local cluster including Lima VM and Kubernetes. + +```bash +sunbeam up +``` + +#### `sunbeam down` +Tear down the Lima VM and local cluster. + +```bash +sunbeam down +``` + +### Status and Information + +#### `sunbeam status [target]` +Show pod health across all namespaces, optionally filtered. + +```bash +# All pods +sunbeam status + +# Specific namespace +sunbeam status ory + +# Specific service +sunbeam status ory/kratos +``` + +### Manifest Management + +#### `sunbeam apply [namespace]` +Build kustomize overlay, apply domain substitution, and apply manifests. + +```bash +# Apply all manifests +sunbeam apply + +# Apply specific namespace only +sunbeam apply lasuite + +# Production environment with custom domain +sunbeam apply --env production --domain sunbeam.pt +``` + +### Service Operations + +#### `sunbeam logs [-f]` +View logs for a service. + +```bash +# View recent logs +sunbeam logs ory/kratos + +# Stream logs +sunbeam logs ory/kratos -f +``` + +#### `sunbeam get [-o yaml|json|wide]` +Get raw kubectl output for a resource. + +```bash +# Get pod details +sunbeam get ory/kratos-abc -o yaml +``` + +#### `sunbeam restart [target]` +Rolling restart of services. + +```bash +# Restart all services +sunbeam restart + +# Restart specific namespace +sunbeam restart ory + +# Restart specific service +sunbeam restart ory/kratos +``` + +#### `sunbeam check [target]` +Run functional service health checks. + +```bash +# Check all services +sunbeam check + +# Check specific service +sunbeam check ory/kratos +``` + +### Build and Deployment + +#### `sunbeam build [--push] [--deploy]` +Build artifacts and optionally push and deploy. + +```bash +# Build proxy +sunbeam build proxy + +# Build and push +sunbeam build proxy --push + +# Build, push, and deploy +sunbeam build proxy --deploy +``` + +Available build targets: +- `proxy`, `integration`, `kratos-admin`, `meet` +- `docs-frontend`, `people-frontend`, `people` + +#### `sunbeam mirror` +Mirror amd64-only La Suite images. + +```bash +sunbeam mirror +``` + +### Secret Management + +#### `sunbeam seed` +Generate and store all credentials in OpenBao. + +```bash +sunbeam seed +``` + +#### `sunbeam verify` +End-to-end VSO + OpenBao integration test. + +```bash +sunbeam verify +``` + +### Bootstrap Operations + +#### `sunbeam bootstrap` +Create Gitea orgs/repos and set up Lima registry. + +```bash +sunbeam bootstrap +``` + +### Kubernetes Operations + +#### `sunbeam k8s [kubectl args...]` +Transparent kubectl passthrough. + +```bash +# Any kubectl command +sunbeam k8s get pods -A +``` + +#### `sunbeam bao [bao args...]` +Run bao CLI inside OpenBao pod with root token. + +```bash +# Run bao commands +sunbeam bao secrets list +``` + +### User Management + +#### `sunbeam user list [--search email]` +List identities. + +```bash +# List all users +sunbeam user list + +# Search by email +sunbeam user list --search user@example.com +``` + +#### `sunbeam user get ` +Get identity by email or ID. + +```bash +sunbeam user get user@example.com +``` + +#### `sunbeam user create [--name name] [--schema schema]` +Create identity. + +```bash +sunbeam user create user@example.com --name "User Name" +``` + +#### `sunbeam user delete ` +Delete identity. + +```bash +sunbeam user delete user@example.com +``` + +#### `sunbeam user recover ` +Generate recovery link. + +```bash +sunbeam user recover user@example.com +``` + +#### `sunbeam user disable ` +Disable identity and revoke sessions. + +```bash +sunbeam user disable user@example.com +``` + +#### `sunbeam user enable ` +Re-enable a disabled identity. + +```bash +sunbeam user enable user@example.com +``` + +#### `sunbeam user set-password ` +Set password for an identity. + +```bash +sunbeam user set-password user@example.com newpassword +``` \ No newline at end of file diff --git a/docs/core-modules.md b/docs/core-modules.md new file mode 100644 index 0000000..f769ec5 --- /dev/null +++ b/docs/core-modules.md @@ -0,0 +1,262 @@ +--- +layout: default +title: Core Modules +description: Detailed documentation of Sunbeam's core modules +parent: index +toc: true +--- + +# Core Modules + +Sunbeam's functionality is organized into several core modules, each responsible for specific aspects of cluster and service management. + +## Module Overview + +```mermaid +graph TD + cli[CLI Entry Point] --> kube[Kubernetes Interface] + cli --> manifests[Manifest Management] + cli --> services[Service Operations] + cli --> secrets[Secret Management] + cli --> users[User Management] + cli --> images[Image Building] + cli --> cluster[Cluster Lifecycle] + cli --> tools[Tool Management] + cli --> output[Output Utilities] +``` + +## Kubernetes Interface (`sunbeam.kube`) + +The Kubernetes interface module provides core functionality for interacting with Kubernetes clusters. + +### Key Functions + +#### `set_context(ctx: str, ssh_host: str = "")` +Set the active kubectl context and optional SSH host for production tunnels. + +#### `kube(*args, input=None, check=True)` +Run kubectl commands against the active context with automatic SSH tunnel management. + +#### `kube_out(*args) -> str` +Run kubectl and return stdout. + +#### `kube_ok(*args) -> bool` +Return True if kubectl command succeeds. + +#### `kube_apply(manifest: str, server_side: bool = True)` +Apply YAML manifest via kubectl. + +#### `kustomize_build(overlay: Path, domain: str, email: str = "") -> str` +Build kustomize overlay with domain/email substitution. + +### Environment Management + +- **Local Development**: Uses Lima VM with context `sunbeam` +- **Production**: Supports SSH tunneling to remote clusters +- **Domain Handling**: Automatic domain discovery and substitution + +### SSH Tunnel Management + +The module automatically manages SSH tunnels for production environments: + +```python +# Automatic tunnel opening when needed +def ensure_tunnel(): + # Check if tunnel is already open + # Open SSH tunnel if needed + # Verify tunnel is working +``` + +## Manifest Management (`sunbeam.manifests`) + +Handles kustomize-based manifest building, application, and lifecycle management. + +### Key Functions + +#### `cmd_apply(env: str = "local", domain: str = "", email: str = "", namespace: str = "")` +Main entry point for manifest application: + +1. **Pre-apply Cleanup**: Remove immutable resources and stale secrets +2. **ConfigMap Snapshotting**: Track ConfigMap versions for restart detection +3. **Kustomize Build**: Build overlay with domain/email substitution +4. **Namespace Filtering**: Apply only specific namespaces if requested +5. **Webhook Waiting**: Wait for cert-manager webhook before convergence +6. **ConfigMap Change Detection**: Restart deployments when ConfigMaps change + +#### `pre_apply_cleanup(namespaces=None)` +Clean up resources that must be recreated: +- Delete completed Jobs +- Remove test Pods +- Prune stale VaultStaticSecrets + +#### `_wait_for_webhook(ns: str, svc: str, timeout: int = 120) -> bool` +Wait for webhook services to become ready. + +#### `_restart_for_changed_configmaps(before: dict, after: dict)` +Restart deployments when mounted ConfigMaps change. + +### Manifest Processing Flow + +```mermaid +flowchart TD + A[Start] --> B[Pre-apply Cleanup] + B --> C[Snapshot ConfigMaps] + C --> D[Build Kustomize Overlay] + D --> E[Apply Domain/Email Substitution] + E --> F[First Apply Pass] + F --> G{Webhook Present?} + G -->|Yes| H[Wait for Webhook] + H --> I[Convergence Pass] + G -->|No| I + I --> J[Detect ConfigMap Changes] + J --> K[Restart Affected Deployments] + K --> L[Complete] +``` + +## Service Operations (`sunbeam.services`) + +Provides service management capabilities including status checks, log viewing, and restarts. + +### Key Functions + +#### `cmd_status(target: str | None)` +Show pod health across managed namespaces: +- Filter by namespace or namespace/service +- Color-coded status indicators +- VSO secret sync status + +#### `cmd_logs(target: str, follow: bool)` +Stream logs for a service: +- Automatic pod selection via labels +- Follow mode for real-time logging + +#### `cmd_get(target: str, output: str = "yaml")` +Get raw kubectl output for resources. + +#### `cmd_restart(target: str | None)` +Rolling restart of services: +- Restart all, by namespace, or specific service +- Uses predefined service list + +### Managed Namespaces + +``` +["data", "devtools", "ingress", "lasuite", "media", "ory", "storage", "vault-secrets-operator"] +``` + +### Service Health Monitoring + +The status command provides comprehensive health monitoring: + +- **Pod Status**: Running, Completed, Failed, Pending +- **Readiness**: Container ready ratios +- **VSO Sync**: VaultStaticSecret and VaultDynamicSecret synchronization + +## Secret Management (`sunbeam.secrets`) + +Handles credential generation and OpenBao integration. + +### Key Functions + +#### `cmd_seed()` +Generate and store all credentials in OpenBao. + +#### `cmd_verify()` +End-to-end VSO + OpenBao integration test. + +### OpenBao Integration + +- **Root Token Management**: Automatic injection into bao commands +- **Secret Generation**: Comprehensive credential seeding +- **Integration Testing**: Verify VSO-OpenBao connectivity + +## User Management (`sunbeam.users`) + +Provides identity management for development environments. + +### Key Functions + +#### User Operations +- `cmd_user_list(search: str)` - List identities +- `cmd_user_get(target: str)` - Get identity details +- `cmd_user_create(email: str, name: str, schema_id: str)` - Create identity +- `cmd_user_delete(target: str)` - Delete identity +- `cmd_user_recover(target: str)` - Generate recovery link +- `cmd_user_disable(target: str)` - Disable identity +- `cmd_user_enable(target: str)` - Enable identity +- `cmd_user_set_password(target: str, password: str)` - Set password + +### Identity Management + +- Email-based identity lookup +- Schema-based identity creation +- Session management and recovery +- Password management + +## Image Building (`sunbeam.images`) + +Handles container image building, pushing, and deployment. + +### Key Functions + +#### `cmd_build(what: str, push: bool, deploy: bool)` +Build Docker images with optional push and deploy: + +- **Build Targets**: proxy, integration, kratos-admin, meet, frontend apps +- **Push Integration**: Automatic registry pushing +- **Deploy Integration**: Manifest application and rollout + +#### `cmd_mirror()` +Mirror amd64-only La Suite images for ARM compatibility. + +## Cluster Management (`sunbeam.cluster`) + +Handles cluster lifecycle operations. + +### Key Functions + +#### `cmd_up()` +Bring up the full local cluster including Lima VM. + +#### `cmd_down()` +Tear down the Lima VM and cluster. + +## Tool Management (`sunbeam.tools`) + +Automatic binary management for required tools. + +### Key Features + +- **Binary Caching**: Download and cache kubectl, kustomize, helm +- **SHA256 Verification**: Security verification of downloaded binaries +- **Version Pinning**: Specific versions for reproducibility +- **Automatic Updates**: Re-download when versions change + +### Supported Tools + +| Tool | Version | Purpose | +|------|---------|---------| +| kubectl | v1.32.2 | Kubernetes CLI | +| kustomize | v5.8.1 | Manifest customization | +| helm | v4.1.0 | Helm chart management | + +## Output Utilities (`sunbeam.output`) + +Consistent output formatting and user feedback. + +### Functions + +- `step(msg: str)` - Step headers +- `ok(msg: str)` - Success messages +- `warn(msg: str)` - Warnings +- `die(msg: str)` - Error messages with exit +- `table(rows: list, headers: list)` - Formatted tables + +### Output Style Guide + +```python +step("Starting cluster...") # ==> Starting cluster... +ok("Cluster ready") # Cluster ready +warn("Low memory") # WARN: Low memory +die("Failed to start") # ERROR: Failed to start (exits) +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..bcbc3cf --- /dev/null +++ b/docs/index.md @@ -0,0 +1,67 @@ +--- +layout: default +title: Sunbeam CLI Documentation +description: Comprehensive documentation for the Sunbeam local dev stack manager +toc: true +--- + +# Sunbeam CLI Documentation + +Welcome to the comprehensive documentation for **Sunbeam CLI** - a powerful local development stack manager for Kubernetes-based applications. + +## Overview + +Sunbeam is a command-line tool designed to simplify the management of local development environments for Kubernetes applications. It provides a comprehensive suite of commands to handle cluster operations, service management, secret handling, and more. + +## Key Features + +- **Cluster Management**: Bring up and tear down local Kubernetes clusters +- **Service Operations**: Manage services, logs, and health checks +- **Secret Management**: Secure credential handling with OpenBao integration +- **Manifest Management**: Kustomize-based manifest application with domain substitution +- **User Management**: Identity management for development environments +- **Tool Bundling**: Automatic download and management of required binaries + +## Getting Started + +### Installation + +```bash +# Clone the repository +git clone https://github.com/your-org/sunbeam.git +cd sunbeam/cli + +# Install dependencies +pip install . + +# Verify installation +sunbeam --help +``` + +### Basic Usage + +```bash +# Start your local cluster +sunbeam up + +# Check cluster status +sunbeam status + +# Apply manifests +sunbeam apply + +# View service logs +sunbeam logs ory/kratos +``` + +## Documentation Structure + +- **[CLI Reference](cli-reference)**: Complete command reference +- **[Core Modules](core-modules)**: Detailed module documentation +- **[Architecture](architecture)**: System architecture and design +- **[Usage Examples](usage-examples)**: Practical usage scenarios +- **[Development Guide](development)**: Contributing and extending Sunbeam + +## Support + +For issues, questions, or contributions, please refer to the [GitHub repository](https://github.com/your-org/sunbeam). \ No newline at end of file diff --git a/docs/usage-examples.md b/docs/usage-examples.md new file mode 100644 index 0000000..e92d0e6 --- /dev/null +++ b/docs/usage-examples.md @@ -0,0 +1,486 @@ +--- +layout: default +title: Usage Examples +description: Practical usage examples and best practices for Sunbeam CLI +parent: index +toc: true +--- + +# Usage Examples and Best Practices + +This section provides practical usage examples and best practices for working with Sunbeam CLI. + +## Common Workflows + +### Starting a New Development Session + +```bash +# Start the local cluster +sunbeam up + +# Check cluster status +sunbeam status + +# Apply manifests with local domain +sunbeam apply + +# Seed secrets +sunbeam seed + +# Verify everything is working +sunbeam verify +``` + +### Production Deployment + +```bash +# Set environment variables +export SUNBEAM_SSH_HOST=user@your-server.example.com + +# Apply production manifests with custom domain +sunbeam apply --env production --domain sunbeam.pt --email ops@sunbeam.pt + +# Check production status +sunbeam status --env production + +# Restart specific service in production +sunbeam restart ory/kratos --env production +``` + +### Debugging a Service Issue + +```bash +# Check service status +sunbeam status ory/kratos + +# View recent logs +sunbeam logs ory/kratos + +# Stream logs in real-time +sunbeam logs ory/kratos -f + +# Get pod details +sunbeam get ory/kratos-abc123 + +# Restart the service +sunbeam restart ory/kratos + +# Run health checks +sunbeam check ory/kratos +``` + +## Advanced Usage Patterns + +### Partial Manifest Application + +```bash +# Apply only specific namespace +sunbeam apply lasuite + +# Apply multiple namespaces individually +sunbeam apply ingress +sunbeam apply ory + +# Apply all manifests +sunbeam apply +``` + +### Build and Deploy Workflow + +```bash +# Build an image +sunbeam build proxy + +# Build and push to registry +sunbeam build proxy --push + +# Build, push, and deploy +sunbeam build proxy --deploy + +# Build multiple components +sunbeam build people-backend --push +sunbeam build people-frontend --push +sunbeam build proxy --deploy +``` + +### User Management Workflow + +```bash +# Create a new user +sunbeam user create user@example.com --name "User Name" + +# Set user password +sunbeam user set-password user@example.com "securepassword123" + +# List all users +sunbeam user list + +# Get user details +sunbeam user get user@example.com + +# Disable a user (lockout) +sunbeam user disable user@example.com + +# Re-enable a user +sunbeam user enable user@example.com + +# Generate recovery link +sunbeam user recover user@example.com +``` + +## Best Practices + +### Environment Management + +**Use separate contexts for different environments:** + +```bash +# Local development (default) +sunbeam status + +# Production with explicit context +sunbeam status --env production --context production +``` + +**Set domain appropriately:** + +```bash +# Local development uses automatic Lima IP domain +sunbeam apply + +# Production requires explicit domain +sunbeam apply --env production --domain sunbeam.pt +``` + +### Service Management + +**Use targeted restarts:** + +```bash +# Restart specific service instead of all +sunbeam restart ory/kratos + +# Restart namespace instead of entire cluster +sunbeam restart lasuite +``` + +**Monitor service health:** + +```bash +# Check status before and after operations +sunbeam status ory + +# Use health checks for functional verification +sunbeam check ory/kratos +``` + +### Manifest Management + +**Apply in logical order:** + +```bash +# Apply infrastructure first +sunbeam apply ingress +sunbeam apply data + +# Then apply application layers +sunbeam apply ory +sunbeam apply lasuite +``` + +**Handle webhook dependencies:** + +```bash +# cert-manager must be ready before applying certificates +# Sunbeam automatically handles this with convergence passes +sunbeam apply +``` + +### Debugging Techniques + +**Use kubectl passthrough for advanced debugging:** + +```bash +# Direct kubectl access +sunbeam k8s get pods -A -o wide + +# Describe resources +sunbeam k8s describe pod ory/kratos-abc123 + +# View events +sunbeam k8s get events --sort-by=.metadata.creationTimestamp +``` + +**Check VSO secret sync status:** + +```bash +# Status command includes VSO sync information +sunbeam status + +# Look for sync indicators in output +# ✓ indicates synced, ✗ indicates issues +``` + +### Configuration Management + +**Use environment variables for sensitive data:** + +```bash +# Set ACME email via environment +export SUNBEAM_ACME_EMAIL=ops@sunbeam.pt +sunbeam apply --env production --domain sunbeam.pt +``` + +**Manage multiple clusters:** + +```bash +# Use context overrides for different clusters +sunbeam status --context cluster1 +sunbeam status --context cluster2 +``` + +## Troubleshooting Guide + +### Common Issues and Solutions + +**Issue: Cluster not starting** + +```bash +# Check Lima VM status +limactl list +limactl start sunbeam + +# Check cluster components +sunbeam k8s get nodes +sunbeam k8s get pods -A +``` + +**Issue: Manifest apply failures** + +```bash +# Check for webhook issues +sunbeam k8s get validatingwebhookconfigurations +sunbeam k8s get mutatingwebhookconfigurations + +# Check cert-manager status +sunbeam status cert-manager +sunbeam logs cert-manager/cert-manager +``` + +**Issue: Secret sync problems** + +```bash +# Check VSO status +sunbeam status + +# Check OpenBao connection +sunbeam bao status + +# Verify secrets exist +sunbeam k8s get vaultstaticsecrets -A +sunbeam k8s get vaultdynamicsecrets -A +``` + +**Issue: Service not responding** + +```bash +# Check service status +sunbeam status ory/kratos + +# Check logs +sunbeam logs ory/kratos -f + +# Check service and endpoint +sunbeam k8s get service ory/kratos +sunbeam k8s get endpoints ory/kratos + +# Restart service +sunbeam restart ory/kratos +``` + +## Integration Patterns + +### CI/CD Integration + +```yaml +# Example GitHub Actions workflow +- name: Deploy to production + env: + SUNBEAM_SSH_HOST: ${{ secrets.PRODUCTION_SSH_HOST }} + run: | + sunbeam apply --env production --domain sunbeam.pt --email ops@sunbeam.pt + sunbeam check +``` + +### Local Development Workflow + +```bash +# Start fresh each day +sunbeam down +sunbeam up +sunbeam apply +sunbeam seed + +# During development +sunbeam restart lasuite/people-backend +sunbeam logs lasuite/people-backend -f + +# End of day cleanup +sunbeam down +``` + +### Team Collaboration + +```bash +# Bootstrap new environment +sunbeam up +sunbeam apply +sunbeam seed +sunbeam bootstrap + +# Onboard new team member +sunbeam user create newuser@company.com --name "New User" +sunbeam user set-password newuser@company.com "temporary123" + +# Share access information +sunbeam user recover newuser@company.com +``` + +## Performance Tips + +**Targeted operations:** + +```bash +# Apply only what's needed +sunbeam apply lasuite # Instead of sunbeam apply + +# Restart only affected services +sunbeam restart ory/kratos # Instead of sunbeam restart +``` + +**Use namespace filtering:** + +```bash +# Focus on specific areas +sunbeam status lasuite +sunbeam logs lasuite/people-backend +``` + +**Monitor resource usage:** + +```bash +# Check cluster resource usage +sunbeam k8s top nodes +sunbeam k8s top pods -A + +# Check specific namespace +sunbeam k8s top pods -n lasuite +``` + +## Security Best Practices + +**Secret management:** + +```bash +# Use sunbeam's built-in secret management +sunbeam seed +sunbeam verify + +# Avoid hardcoding secrets in manifests +``` + +**User management:** + +```bash +# Regularly audit users +sunbeam user list + +# Disable unused accounts +sunbeam user disable olduser@company.com + +# Rotate passwords regularly +sunbeam user set-password user@company.com "newsecurepassword" +``` + +**Production access:** + +```bash +# Use SSH host environment variable securely +export SUNBEAM_SSH_HOST=user@server.example.com + +# Never commit SSH host in code +# Use secret management for production credentials +``` + +## Monitoring and Maintenance + +**Regular health checks:** + +```bash +# Daily health monitoring +sunbeam status +sunbeam check + +# Weekly deep checks +sunbeam verify +sunbeam k8s get events -A --sort-by=.metadata.creationTimestamp +``` + +**Log management:** + +```bash +# Check logs for errors +sunbeam logs ory/kratos | grep ERROR +sunbeam logs lasuite/people-backend | grep Exception + +# Monitor specific services +sunbeam logs ingress/nginx-ingress -f +``` + +**Resource cleanup:** + +```bash +# Clean up completed jobs +sunbeam k8s delete jobs --field-selector=status.successful=1 + +# Remove old resources +sunbeam k8s delete pods --field-selector=status.phase=Succeeded +``` + +## Advanced Patterns + +### Custom Domain Management + +```bash +# Discover current domain +CURRENT_DOMAIN=$(sunbeam k8s get cm gitea-inline-config -n devtools -o jsonpath='{.data.server}' | grep DOMAIN= | cut -d= -f2) + +# Apply with custom domain +sunbeam apply --domain custom.example.com +``` + +### Multi-environment Testing + +```bash +# Test changes in local first +sunbeam apply --env local +sunbeam check + +# Then apply to production +sunbeam apply --env production --domain sunbeam.pt +sunbeam check --env production +``` + +### Integration with Other Tools + +```bash +# Use with kubectl +kubectl --context=sunbeam get pods -A + +# Use with helm +helm --kube-context=sunbeam list -A + +# Use with k9s (set context first) +sunbeam k8s config use-context sunbeam +k9s +``` \ No newline at end of file diff --git a/docs/utility-modules.md b/docs/utility-modules.md new file mode 100644 index 0000000..18eec5d --- /dev/null +++ b/docs/utility-modules.md @@ -0,0 +1,286 @@ +--- +layout: default +title: Utility Modules +description: Documentation of Sunbeam's utility and helper modules +parent: index +toc: true +--- + +# Utility Modules + +Sunbeam includes several utility modules that provide essential helper functionality. + +## Output Utilities (`sunbeam.output`) + +The output module provides consistent formatting for user feedback and status messages. + +### Functions + +#### `step(msg: str)` +Print a step header with `==>` prefix. + +**Parameters:** +- `msg`: The message to display + +**Example:** +```python +step("Starting cluster initialization...") +# Output: ==> Starting cluster initialization... +``` + +#### `ok(msg: str)` +Print a success or informational message with indentation. + +**Parameters:** +- `msg`: The message to display + +**Example:** +```python +ok("Cluster initialized successfully") +# Output: Cluster initialized successfully +``` + +#### `warn(msg: str)` +Print a warning message to stderr. + +**Parameters:** +- `msg`: The warning message + +**Example:** +```python +warn("Low memory detected") +# Output: WARN: Low memory detected +``` + +#### `die(msg: str)` +Print an error message and exit the program. + +**Parameters:** +- `msg`: The error message + +**Example:** +```python +die("Failed to connect to cluster") +# Output: ERROR: Failed to connect to cluster +# Exits with status code 1 +``` + +#### `table(rows: list[list[str]], headers: list[str]) -> str` +Generate an aligned text table. + +**Parameters:** +- `rows`: List of row data (list of strings) +- `headers`: List of column headers + +**Returns:** Formatted table string + +**Example:** +```python +table_data = table([ + ["pod-1", "Running", "2/2"], + ["pod-2", "Pending", "0/1"] +], ["Name", "Status", "Ready"]) + +# Output: +# Name Status Ready +# ------------------------- +# pod-1 Running 2/2 +# pod-2 Pending 0/1 +``` + +### Usage Patterns + +```python +from sunbeam.output import step, ok, warn, die, table + +# Progress reporting +step("Deploying application...") +ok("Namespace created") +ok("ConfigMaps applied") + +# Error handling +if not cluster_ready: + die("Cluster not ready - aborting deployment") + +# Warning conditions +if memory_low: + warn("System memory is low - performance may be affected") + +# Tabular data display +pod_data = [ + ["kratos-abc", "Running", "2/2"], + ["hydra-xyz", "Running", "1/1"] +] +print(table(pod_data, ["Pod", "Status", "Ready"])) +``` + +## Tool Management (`sunbeam.tools`) + +The tools module handles automatic downloading, caching, and verification of required binaries. + +### Constants + +#### `CACHE_DIR` +Default cache directory: `~/.local/share/sunbeam/bin` + +#### `TOOLS` +Dictionary of supported tools with version and download information: + +```python +TOOLS = { + "kubectl": { + "version": "v1.32.2", + "url": "https://dl.k8s.io/release/v1.32.2/bin/darwin/arm64/kubectl", + "sha256": "" + }, + "kustomize": { + "version": "v5.8.1", + "url": "https://github.com/kubernetes-sigs/kustomize/releases/download/...", + "sha256": "", + "extract": "kustomize" + }, + "helm": { + "version": "v4.1.0", + "url": "https://get.helm.sh/helm-v4.1.0-darwin-arm64.tar.gz", + "sha256": "82f7065bf4e08d4c8d7881b85c0a080581ef4968a4ae6df4e7b432f8f7a88d0c", + "extract": "darwin-arm64/helm" + } +} +``` + +### Functions + +#### `ensure_tool(name: str) -> Path` +Ensure a tool is available, downloading and verifying if necessary. + +**Parameters:** +- `name`: Tool name (must be in TOOLS dictionary) + +**Returns:** Path to the executable + +**Behavior:** +- Checks cache for existing binary +- Verifies version and SHA256 hash +- Downloads if missing or verification fails +- Extracts from archives if needed +- Makes executable and sets permissions +- Caches version information + +**Example:** +```python +kubectl_path = ensure_tool("kubectl") +subprocess.run([str(kubectl_path), "version"]) +``` + +#### `run_tool(name: str, *args, **kwargs) -> subprocess.CompletedProcess` +Run a tool, ensuring it's downloaded first. + +**Parameters:** +- `name`: Tool name +- `*args`: Arguments to pass to the tool +- `**kwargs`: Additional subprocess.run parameters + +**Returns:** CompletedProcess result + +**Special Handling:** +- For kustomize: Adds CACHE_DIR to PATH so helm is found +- Automatically ensures tool is available before running + +**Example:** +```python +result = run_tool("kustomize", "build", "overlays/local", + capture_output=True, text=True) +print(result.stdout) +``` + +#### `_sha256(path: Path) -> str` +Calculate SHA256 hash of a file (internal utility). + +**Parameters:** +- `path`: Path to file + +**Returns:** Hexadecimal SHA256 hash + +### Tool Management Workflow + +```mermaid +flowchart TD + A[ensure_tool] --> B{Tool in cache?} + B -->|Yes| C{Version matches?} + C -->|Yes| D{SHA256 matches?} + D -->|Yes| E[Return cached path] + B -->|No| F[Download] + C -->|No| F + D -->|No| F + F --> G{Extract needed?} + G -->|Yes| H[Extract from archive] + G -->|No| I[Save binary] + H --> I + I --> J{Verify SHA256?} + J -->|Yes| K{Hash matches?} + K -->|Yes| L[Set executable] + K -->|No| M[Error: Hash mismatch] + J -->|No| L + L --> N[Write version file] + N --> E +``` + +### Error Handling + +The module includes comprehensive error handling: + +- **Unknown tools**: Raises `ValueError` for unsupported tools +- **Download failures**: Propagates network errors +- **SHA256 mismatches**: Raises `RuntimeError` with expected vs actual hashes +- **Permission issues**: Handles file system errors gracefully + +## Helper Functions + +### Target Parsing (`sunbeam.kube.parse_target`) + +```python +def parse_target(s: str | None) -> tuple[str | None, str | None]: + """Parse 'ns/name' -> ('ns', 'name'), 'ns' -> ('ns', None), None -> (None, None).""" +``` + +**Examples:** +```python +parse_target("ory/kratos") # ("ory", "kratos") +parse_target("lasuite") # ("lasuite", None) +parse_target(None) # (None, None) +``` + +### Domain Replacement (`sunbeam.kube.domain_replace`) + +```python +def domain_replace(text: str, domain: str) -> str: + """Replace all occurrences of DOMAIN_SUFFIX with domain.""" +``` + +**Example:** +```python +manifest = "apiVersion: v1\nkind: Service\nspec:\n host: app.DOMAIN_SUFFIX" +domain_replace(manifest, "example.com") +# Returns: "apiVersion: v1\nkind: Service\nspec:\n host: app.example.com" +``` + +### Lima VM IP Discovery (`sunbeam.kube.get_lima_ip`) + +```python +def get_lima_ip() -> str: + """Get the socket_vmnet IP of the Lima sunbeam VM (192.168.105.x).""" +``` + +Uses multiple fallback methods to discover the Lima VM IP address. + +### Domain Discovery (`sunbeam.kube.get_domain`) + +```python +def get_domain() -> str: + """Discover the active domain from cluster state.""" +``` + +Discovery priority: +1. Gitea inline-config secret +2. La Suite OIDC provider configmap +3. Lima VM IP with sslip.io domain \ No newline at end of file