Skip to main content

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:

OperationEndpointDescription
PlanPOST /api/v1/stack/planDry-run — shows what would change without making any modifications
ApplyPOST /api/v1/stack/applyExecutes the plan and reconciles your project to match the stack definition
ExportGET /api/v1/stack/exportDumps the current project state as a stack YAML/JSON file
Start with Plan

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
Avoid secrets in shell history

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
}
}
Prune deletes resources

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