--- 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 ```