486 lines
8.7 KiB
Markdown
486 lines
8.7 KiB
Markdown
---
|
|
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
|
|
``` |