cli/docs/usage-examples.md

layout, title, description, parent, toc

layout	title	description	parent	toc
default	Usage Examples	Practical usage examples and best practices for Sunbeam CLI	index	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

# 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

# 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

# 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

# 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

# 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

# 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:

# Local development (default)
sunbeam status

# Production with explicit context
sunbeam status --env production --context production

Set domain appropriately:

# 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:

# Restart specific service instead of all
sunbeam restart ory/kratos

# Restart namespace instead of entire cluster
sunbeam restart lasuite

Monitor service health:

# 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:

# Apply infrastructure first
sunbeam apply ingress
sunbeam apply data

# Then apply application layers
sunbeam apply ory
sunbeam apply lasuite

Handle webhook dependencies:

# 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:

# 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:

# 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:

# Set ACME email via environment
export SUNBEAM_ACME_EMAIL=ops@sunbeam.pt
sunbeam apply --env production --domain sunbeam.pt

Manage multiple clusters:

# Use context overrides for different clusters
sunbeam status --context cluster1
sunbeam status --context cluster2

Troubleshooting Guide

Common Issues and Solutions

Issue: Cluster not starting

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# Focus on specific areas
sunbeam status lasuite
sunbeam logs lasuite/people-backend

Monitor resource usage:

# 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:

# Use sunbeam's built-in secret management
sunbeam seed
sunbeam verify

# Avoid hardcoding secrets in manifests

User management:

# 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:

# 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:

# Daily health monitoring
sunbeam status
sunbeam check

# Weekly deep checks
sunbeam verify
sunbeam k8s get events -A --sort-by=.metadata.creationTimestamp

Log management:

# 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:

# 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

# 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

# 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

# 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