Stacks API

Manage Infrastructure as Code deployments via the API.

Overview

Stacks provide declarative deployment of complete application stacks including:

• Infrastructure resources (databases, namespaces, storage)
• Secrets management (Vault integration)
• Bootstrap jobs (migrations, seeds)
• Service deployments (Helm charts, manifests)

List Stacks

GET /v1/stacks

Query Parameters:

Parameter	Type	Description
status	string	Filter by status: pending, deploying, active, failed
tenant	string	Filter by tenant ID

Response:

{
  "data": [
    {
      "id": "stk_abc123",
      "name": "my-application",
      "tenant": "acme-corp",
      "status": "active",
      "version": 3,
      "phase": "services",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

Get Stack

GET /v1/stacks/:id

Response:

{
  "data": {
    "id": "stk_abc123",
    "name": "my-application",
    "tenant": "acme-corp",
    "status": "active",
    "version": 3,
    "phase": "services",
    "template": {
      "version": "1",
      "name": "my-application",
      "resources": {...},
      "secrets": {...},
      "bootstrap": {...},
      "services": {...}
    },
    "resources": [
      {
        "type": "database",
        "name": "database",
        "id": "db_xyz789",
        "status": "active"
      }
    ],
    "outputs": {
      "api_endpoint": "https://api.my-app.sparbz.cloud",
      "database_host": "db-xyz789.postgres.sparbz.cloud"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Create Stack

POST /v1/stacks

Request Body:

{
  "name": "my-application",
  "tenant": "acme-corp",
  "template": {
    "version": "1",
    "name": "my-application",

    "resources": {
      "database": {
        "type": "database",
        "properties": {
          "engine": "postgres",
          "version": "15",
          "storage_size": "10Gi"
        }
      },
      "cache": {
        "type": "valkey",
        "properties": {
          "memory": "256Mi"
        }
      }
    },

    "secrets": {
      "db_password": {
        "type": "generated",
        "generator_type": "password",
        "length": 32
      },
      "api_key": {
        "type": "generated",
        "generator_type": "token",
        "length": 64
      }
    },

    "bootstrap": {
      "migrate": {
        "image": "myapp/migrations:v1.0.0",
        "command": ["./migrate", "up"],
        "secrets": {
          "DATABASE_URL": "${resources.database.connection_string}"
        },
        "timeout": "10m"
      }
    },

    "services": {
      "backend": {
        "type": "helm",
        "depends_on": ["migrate"],
        "properties": {
          "chart": "oci://registry.sparbz.cloud/charts/backend",
          "version": "1.0.0",
          "values": {
            "replicas": 3
          }
        }
      }
    },

    "outputs": {
      "api_endpoint": {
        "value": "${services.backend.endpoint}"
      }
    }
  }
}

Response: 201 Created

{
  "data": {
    "id": "stk_abc123",
    "name": "my-application",
    "status": "pending",
    "version": 1
  }
}

Update Stack

PUT /v1/stacks/:id

Updates the stack template. Changes are not applied until apply is called.

Request Body:

{
  "template": {
    "version": "1",
    "name": "my-application",
    "services": {
      "backend": {
        "type": "helm",
        "properties": {
          "chart": "oci://registry.sparbz.cloud/charts/backend",
          "version": "1.1.0",
          "values": {
            "replicas": 5
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "id": "stk_abc123",
    "status": "pending",
    "version": 4,
    "pending_changes": true
  }
}

Delete Stack

DELETE /v1/stacks/:id

Query Parameters:

Parameter	Type	Description
destroy_resources	boolean	Also destroy provisioned resources (default: false)

Response: 204 No Content

Plan Changes

GET /v1/stacks/:id/plan

Preview what changes will be made when the stack is applied.

Response:

{
  "data": {
    "changes": [
      {
        "type": "update",
        "resource": "services.backend",
        "details": {
          "replicas": {
            "old": 3,
            "new": 5
          },
          "version": {
            "old": "1.0.0",
            "new": "1.1.0"
          }
        }
      }
    ],
    "summary": {
      "create": 0,
      "update": 1,
      "delete": 0
    }
  }
}

Apply Stack

POST /v1/stacks/:id/apply

Apply pending changes to the stack.

Request Body (optional):

{
  "dry_run": false,
  "force": false
}

Response:

{
  "data": {
    "execution_id": "exec_xyz789",
    "status": "running",
    "phase": "infrastructure",
    "started_at": "2024-01-15T11:00:00Z"
  }
}

Get Execution Status

GET /v1/stacks/:id/executions/:execution_id

Response:

{
  "data": {
    "execution_id": "exec_xyz789",
    "status": "completed",
    "phases": [
      {
        "name": "infrastructure",
        "status": "completed",
        "started_at": "2024-01-15T11:00:00Z",
        "completed_at": "2024-01-15T11:02:00Z"
      },
      {
        "name": "secrets",
        "status": "completed",
        "started_at": "2024-01-15T11:02:00Z",
        "completed_at": "2024-01-15T11:02:30Z"
      },
      {
        "name": "bootstrap",
        "status": "completed",
        "started_at": "2024-01-15T11:02:30Z",
        "completed_at": "2024-01-15T11:05:00Z"
      },
      {
        "name": "services",
        "status": "completed",
        "started_at": "2024-01-15T11:05:00Z",
        "completed_at": "2024-01-15T11:07:00Z"
      }
    ],
    "started_at": "2024-01-15T11:00:00Z",
    "completed_at": "2024-01-15T11:07:00Z"
  }
}

Destroy Stack

POST /v1/stacks/:id/destroy

Destroy all resources provisioned by the stack.

Request Body (optional):

{
  "dry_run": false,
  "force": false
}

Response:

{
  "data": {
    "execution_id": "exec_destroy123",
    "status": "running",
    "phase": "services",
    "started_at": "2024-01-15T12:00:00Z"
  }
}

Get Outputs

GET /v1/stacks/:id/outputs

Response:

{
  "data": {
    "outputs": {
      "api_endpoint": {
        "value": "https://api.my-app.sparbz.cloud",
        "sensitive": false
      },
      "database_host": {
        "value": "db-xyz789.postgres.sparbz.cloud",
        "sensitive": false
      },
      "db_password": {
        "value": "********",
        "sensitive": true,
        "vault_path": "secret/data/stacks/stk_abc123/db_password"
      }
    }
  }
}

List Secrets

GET /v1/stacks/:id/secrets

Response:

{
  "data": {
    "secrets": [
      {
        "name": "db_password",
        "type": "generated",
        "vault_path": "secret/data/stacks/stk_abc123/db_password",
        "created_at": "2024-01-15T11:02:00Z"
      },
      {
        "name": "api_key",
        "type": "generated",
        "vault_path": "secret/data/stacks/stk_abc123/api_key",
        "created_at": "2024-01-15T11:02:00Z"
      }
    ]
  }
}

List Bootstrap Jobs

GET /v1/stacks/:id/jobs

Response:

{
  "data": {
    "jobs": [
      {
        "name": "migrate",
        "status": "completed",
        "exit_code": 0,
        "started_at": "2024-01-15T11:02:30Z",
        "completed_at": "2024-01-15T11:05:00Z"
      }
    ]
  }
}

Get Job Logs

GET /v1/stacks/:id/jobs/:name/logs

Response:

{
  "data": {
    "logs": "Running migrations...\nApplied migration 001_create_users\nApplied migration 002_create_posts\nMigrations complete."
  }
}