Hierarchy
Suga organizes infrastructure in a clear hierarchy:The Mental Model
Think of Suga as applications, not servers:- You design what you want to run (services and volumes)
- You don’t manage where or how it runs
- You focus on configuration and connections
- Suga handles provisioning, networking, and orchestration
Kubernetes powers Suga under the hood, but you never need to learn Kubernetes concepts or YAML files.
Key Concepts at a Glance
| Concept | Description | Example |
|---|---|---|
| Organization | Team workspace and billing entity | ”Acme Corp” |
| Project | Application container | ”Marketing Website” |
| Environment | Isolated deployment target | ”production”, “staging” |
| Deployment | Immutable snapshot of infrastructure | ”Deploy #42 on Jan 28” |
| Service | Running workload (Container or Function) | “api”, “frontend”, “worker” |
| Volume | Persistent block storage | ”postgres-data” (5 GB) |
| Networking | Public (HTTPS/TCP) or private (service discovery) | HTTPS domain or TCP proxy |
Organizations
Organizations are team workspaces:- The top-level entity in Suga
- Billing and subscription management
- Team member invitations and roles
- Own multiple projects
Projects
Projects are application containers:- Belong to one organization
- Have a unique name and URL slug
- Contain multiple environments
Environments
Environments are isolated deployment targets:- Separate namespaces for production, staging, development
- Each has its own services and volumes
- Independent configuration and secrets
- Share the same project structure
Preview Environments (automatic PR environments) are coming soon in a future release.
Deployments
Deployments are immutable snapshots:- Capture complete infrastructure state at a point in time
- Include all services, volumes, configuration, and networking
- Tracked in deployment history for rollback
- Only one deployment is active per environment
Services
Services are your running workloads:- Containers
- Functions
Docker-based service:
- Run any Docker image
- Support for public and private registries
- Configure commands, ports, and health checks
- Best for existing applications and standard workloads
- Environment variables with secrets encryption
- Resource limits (CPU and memory)
- Horizontal scaling with replicas
- Public networking (HTTPS/TCP) and private networking (service discovery)
Volumes
Volumes provide persistent storage:- Block storage that survives restarts and redeployments
- Size limits vary by plan (check dashboard for current limits)
- Mount to services at specified paths
- Essential for databases and stateful applications
Networking
Suga offers two networking modes: Private Networking (Service Discovery):- Automatic DNS-based discovery
- Services communicate using service names
- Format:
service-name:port - Example:
postgres:5432,redis:6379
- HTTPS Endpoints - Port 443 with automatic TLS and domains
- TCP Proxy - Non-HTTP protocols like PostgreSQL or SSH
- Automatic load balancing across replicas
Templates
Templates are pre-configured project resources:- Vetted configurations for common services
- Auto-fill images, ports, volumes, and environment variables
- Available for databases, frameworks, and tools
- Save time with best-practice defaults