Stack Engine (IaC)
Define your entire project infrastructure in a single YAML file and apply it with one API call.
The Stack Engine is SailOps' infrastructure-as-code system. Instead of creating resources one by one through the UI or individual API calls, you describe your desired state in a YAML file and the Stack Engine figures out what to create, update, or delete.
How It Works
The Stack Engine has three operations:
| Operation | Endpoint | Description |
|---|---|---|
| Plan | POST /api/v1/stack/plan | Dry-run — shows what would change without making any modifications |
| Apply | POST /api/v1/stack/apply | Executes the plan and reconciles your project to match the stack definition |
| Export | GET /api/v1/stack/export | Dumps the current project state as a stack YAML/JSON file |
Always run a plan before apply on an existing project. The response lists every resource that would be created, updated, deleted, or left unchanged.
Stack File Format
Stack files are YAML (or JSON) documents. You can define any combination of containers, services (PostgreSQL, MariaDB, Valkey, NATS, Kafka, OpenSearch, Supabase, Keycloak, WordPress), gateways, routes, and connections.
containers:
- name: api
spec:
computeClass: standard
image: ghcr.io/myorg/api:v2.0.0
resources:
cpu: 500
memory: 512
ports:
- containerPort: 8080
autoscaling:
minReplicas: 1
maxReplicas: 5
cpuThreshold: 70
configuration:
environment:
- key: LOG_LEVEL
type: config
value: info
- key: DATABASE_URL
type: secret
value: "${DATABASE_URL}"
- name: worker
spec:
computeClass: standard
image: ghcr.io/myorg/worker:v2.0.0
resources:
cpu: 250
memory: 256
volumes:
- name: data
mountPath: /data
sizeInMB: 2048
services:
postgresql:
- name: main-db
version: 16
flavor: small
computeClass: standard
storage: 20Gi
databases:
- app
valkey:
- name: cache
flavor: small
computeClass: standard
replicas: 3
mariadb:
- name: wp-db
version: "11.4"
flavor: small
computeClass: standard
storage: 10Gi
databases:
- wordpress
wordpress:
- name: blog
version: "7.1.2"
flavor: small
computeClass: standard
instances: 1
siteTitle: Company Blog
adminEmail: [email protected]
storage:
size: 1073741824
storageClass: standard
database:
existing: wp-db
gateways:
- name: main-lb
class: gw-small
routes:
- name: api-route
gateway: main-lb
type: HTTPRoute
httpSpec:
hostnames:
- api.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: api
port: 8080
connections:
- sourceType: container
sourceId: api
targetType: postgresql
targetId: main-db
alias: DB
dedicatedDatabase: true
databaseName: app
- sourceType: container
sourceId: api
targetType: valkey
targetId: cache
alias: CACHE
Variable Substitution
Stack files support ${VAR_NAME} placeholders for sensitive values. Pass variable values in the variables field of the request body — they are never stored by SailOps.
curl -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat stack.yaml | jq -Rs .),
\"variables\": {
\"DATABASE_URL\": \"$DATABASE_URL\",
\"SECRET_KEY\": \"$SECRET_KEY\"
}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply
Always reference environment variables ($DATABASE_URL) instead of pasting credentials directly in the command. This prevents secrets from appearing in your shell history.
Scope Filtering
By default, apply and plan operate on all sections declared in the stack file. Use scope to restrict the operation to specific resource types:
{
"stack": "...",
"options": {
"scope": ["containers"]
}
}
Valid scope values: containers, services, gateways, routes, connections.
Resource Tags
The apply and plan requests accept a top-level tags object that sets default tags on every resource created by that invocation:
{
"stack": "...",
"tags": { "environment": "staging", "team": "backend" }
}
Individual resources can override the defaults with their own tags field. An explicit empty object {} clears all tags for that resource. When no resource-level tags are provided and no request-level defaults are set, existing tags are preserved.
Stack export includes tags on each resource that has them. See Resource tags for tag rules and limits.
Prune Option
By default, resources that exist in your project but are not declared in the stack file are left untouched. Enable prune to delete them:
{
"stack": "...",
"options": {
"prune": true
}
}
With prune: true, any resource in your project that is not declared in the stack will be deleted. Always run a plan with prune: true first to verify what would be removed.
Response Format
Both plan and apply return the same response shape:
{
"status": "applied",
"changes": [
{"action": "create", "resourceType": "container", "name": "api"},
{"action": "update", "resourceType": "service", "name": "main-db", "details": "storage: 10Gi -> 20Gi"},
{"action": "unchanged", "resourceType": "gateway", "name": "main-lb"}
],
"errors": []
}
status values: applied (apply succeeded), planned (plan dry-run), failed.
action values per change: create, update, delete, unchanged.
Practical curl Examples
Plan a stack (dry-run)
STACK=$(cat stack.yaml)
curl -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"stack\": $(echo "$STACK" | jq -Rs .), \"variables\": {\"SECRET\": \"$MY_SECRET\"}}" \
https://app.sailops.io/api/public/api/v1/stack/plan
Apply a stack
curl -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"stack\": $(cat stack.yaml | jq -Rs .),
\"variables\": {\"SECRET\": \"$MY_SECRET\"},
\"options\": {\"prune\": false}
}" \
https://app.sailops.io/api/public/api/v1/stack/apply
Export current state as YAML
curl -H "X-Api-Key: $SAILOPS_API_KEY" \
"https://app.sailops.io/api/public/api/v1/stack/export?format=yaml" \
| jq -r '.stack'
Export only containers and services
curl -H "X-Api-Key: $SAILOPS_API_KEY" \
"https://app.sailops.io/api/public/api/v1/stack/export?format=yaml&scope=containers,services" \
| jq -r '.stack'
CI/CD Integration
The Stack Engine is well-suited for GitOps workflows. Store your stack.yaml in your repository and apply it on every merge to the main branch:
# .github/workflows/deploy.yml
name: Deploy Stack
on:
push:
branches: [main]
paths:
- 'infra/stack.yaml'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Plan stack
run: |
RESPONSE=$(curl -sf -X POST \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d "{\"stack\": $(cat infra/stack.yaml | jq -Rs .)}" \
https://app.sailops.io/api/public/api/v1/stack/plan)
echo "$RESPONSE" | jq .
- name: Apply stack
run: |
curl -sf -X POST \
-H "X-Api-Key: ${{ secrets.SAILOPS_API_KEY }}" \
-H "Content-Type: application/json" \
-d "{\"stack\": $(cat infra/stack.yaml | jq -Rs .)}" \
https://app.sailops.io/api/public/api/v1/stack/apply
Related Topics
- CI/CD Integration — Complete GitHub Actions and GitLab CI examples
- Endpoints Reference — Stack API endpoints
- MCP Server — Use the Stack Engine from an AI assistant
- Containers — Container configuration reference
- Gateways — Gateway and route configuration reference