Workflows
Durable workflow orchestration for long-running operations
Workflows API
Workflow orchestration for long-running operations.
Design Principle: All infrastructure mutations flow through workflows. This provides durable execution, automatic retries, audit trails, and observability. Workflows double as the event log for the platform.
Workflow Runs
Query and manage workflow executions.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
type | string | Filter by workflow type |
status | string | pending, running, completed, failed, cancelled |
resourceType | string | server, cluster, vm |
resourceId | string | Specific resource ID |
triggeredBy | string | User ID who triggered |
since | ISO date | Runs started after this time |
until | ISO date | Runs started before this time |
Response:
Response:
Response:
Design Decision: Retries create new run records linked to the original. This preserves audit history. fromStep allows resuming from a specific step when earlier steps succeeded.
Workflow Types
Available workflow types and their purposes:
| Type | Trigger Source | Description |
|---|---|---|
server.register | Atlas API | Register new bare metal server |
server.inspect | Atlas API | Hardware inspection |
server.provision | Atlas API | OS provisioning |
server.lifecycle | Atlas/Arc API | Lifecycle actions (power, provision, etc.) |
server.decommission | Atlas API | Remove from inventory |
cluster.create | Arc API | Create Kubernetes cluster |
cluster.scale | Arc API | Scale cluster nodes |
cluster.upgrade | Arc API | Upgrade Kubernetes version |
cluster.delete | Arc API | Delete cluster |
vm.create | Arc API | Create virtual machine |
vm.power | Arc API | VM power actions |
vm.delete | Arc API | Delete VM |
sync.server-state | Projector | Sync K8s state to cache |
sync.cluster-state | Projector | Sync cluster state to cache |
Workflow Metrics
Aggregate statistics for workflow performance.
Example:
Response:
Workflow Operations
Long-running operations that interact with infrastructure (BMC, Kubernetes) return 202 Accepted immediately with a workflow ID for tracking. All infrastructure mutations flow through durable workflows.
Design Principles
- Immediate Response: Return 202 within < 1 second, don't wait for completion
- Workflow ID: Provide workflow run ID for polling or webhook correlation
- Estimated Duration: Give clients a hint for progress UI
- Status Endpoint: Query workflow status via
/v1/workflows/runs/:id - Webhook Integration: Support webhooks for completion notifications
Workflow Orchestration
Use a durable workflow engine for retryable task execution:
Pattern: Compensating Actions. Use onFailure to clean up partial state.
Release allocated resources, update status to error, notify via webhook.
Workflow Status Endpoint
Event Sourcing Pattern
- We will need to get updated to use event sourcing pattern for the workflows API.
- Need to decide on K8s Informers, Watchers, or Controller-based approach.
Last updated on
How is this guide?