docs: add comprehensive documentation for sunbeam CLI
This commit is contained in:
262
docs/core-modules.md
Normal file
262
docs/core-modules.md
Normal file
@@ -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)
|
||||
```
|
||||
Reference in New Issue
Block a user