---
title: Workflow
---

**Workflows** are automated execution plans that orchestrate the provisioning of multiple resources in the correct dependency order. Workflows are created from Blueprints and handle the complexity of wiring outputs from one resource into the inputs of another.

Workflows are the orchestration layer in your infrastructure kitchen — they take a Blueprint's definition of what needs to be built and execute it step-by-step, resolving dependencies, passing outputs between resources, and tracking progress throughout the process.

A workflow combines:

- **Steps** (ordered list of resource provisioning tasks)
- **Wiring Snapshot** (captured dependency rules from the blueprint)
- **Variable Overrides** (runtime customizations per template)
- **Integrations** (cloud credentials shared across all steps)
- **Secrets** (sensitive data shared across all steps)
- **Storage** (backend for Terraform/OpenTofu state)

Once executed, workflows provision resources in topological order — ensuring that upstream resources are created before downstream resources that depend on their outputs.

## Workflow Lifecycle

Workflows move through these stages: **Create → Execute → Complete/Error**.

**Statuses:** `pending`, `in_progress`, `done`, `error`

Each workflow step also maintains its own status, allowing granular tracking of multi-resource provisioning.

```mermaid
graph TD
    A[Blueprint] -->|Create Execution| B[Workflow Created]
    B -->|Execute| C[In Progress]
    C --> D{Step Execution}
    D -->|Step Success| E[Next Step]
    E --> D
    D -->|All Steps Done| F[Workflow Done]
    D -->|Step Error| G[Workflow Error]

    style B fill:#fff3cd
    style C fill:#d1ecf1
    style F fill:#d4edda
    style G fill:#f8d7da
```

## Workflow Properties

Each workflow in InfraKitchen contains the following core properties:

| Property               | Description                                         | Notes                                     |
| :--------------------- | :-------------------------------------------------- | :---------------------------------------- |
| **ID**                 | Unique identifier for the workflow                  | Auto-generated UUID                       |
| **Status**             | Current execution status                            | `pending`, `in_progress`, `done`, `error` |
| **Error Message**      | Description of failure if status is `error`         | Only present on failure                   |
| **Steps**              | Ordered list of provisioning tasks                  | One per template in the blueprint         |
| **Wiring Snapshot**    | Copy of blueprint wiring rules at execution time    | Immutable after creation                  |
| **Variable Overrides** | Runtime variable customizations per template        | Merged with blueprint defaults            |
| **Creator**            | User who triggered the execution                    | Used for permissions and audit            |
| **Started At**         | Timestamp when execution began                      | Set when first step starts                |
| **Completed At**       | Timestamp when execution finished                   | Set on success or failure                 |
| **Created At**         | Timestamp when the workflow was created             | Set on creation                           |

## Workflow Step Properties

Each step within a workflow tracks the provisioning of a single resource:

| Property                | Description                                        | Notes                                     |
| :---------------------- | :------------------------------------------------- | :---------------------------------------- |
| **ID**                  | Unique identifier for the step                     | Auto-generated UUID                       |
| **Template**            | The template this step provisions                  | From the blueprint's template list        |
| **Resource**            | The resource created by this step                  | Populated after successful provisioning   |
| **Position**            | Execution order (BFS level)                        | Steps at the same level can run in parallel |
| **Status**              | Current step status                                | `pending`, `in_progress`, `done`, `error` |
| **Error Message**       | Description of failure if step errored             | Only present on failure                   |
| **Resolved Variables**  | Final merged variables for this step               | Defaults + wired outputs + overrides      |
| **Parent Resources**    | Resources that this step depends on                | From template hierarchy or overrides      |
| **Cloud Integrations**  | Cloud provider credentials for this step           | Shared from workflow request              |
| **Secrets**             | Sensitive data for this step                       | Shared from workflow request              |
| **Template Version** | Specific code version for this step                | Can be overridden per template            |
| **Storage**             | Backend for Terraform/OpenTofu state               | Shared from workflow request              |
| **Started At**          | Timestamp when step execution began                | Set when step starts                      |
| **Completed At**        | Timestamp when step execution finished             | Set on success or failure                 |

## Creating Workflows

Workflows are created by executing a Blueprint. The system automatically resolves the dependency order and prepares each step.

### Creation Flow

1. **Execute**

    Open a Blueprint and click <kbd>Execute</kbd>.

2. **Optionally configure runtime overrides**

    - Variable overrides per template
    - Template version overrides per template
    - Parent resource overrides for templates with external parents

3. **Select shared execution context**

    - Cloud integration(s)
    - Secrets
    - Storage backend for state management

4. **Create Execution**

    Click <kbd>Create Execution</kbd>.

The system then:

1. **Resolves dependencies** via topological sort of the blueprint's wiring rules
2. **Merges variables** for each step (blueprint defaults → wired outputs → runtime overrides)
3. **Creates the workflow** with steps in the computed execution order
4. **Links the workflow** to the originating blueprint

:::tip[Variable Resolution Order]
Variables for each step are resolved in the priority order described in [Blueprint — Variable Resolution Order](./blueprint#variable-resolution-order) (runtime overrides → wired outputs → blueprint defaults, highest wins).
:::

## Managing Workflows

Workflows support lifecycle actions based on their current state.

| Action      | When Available    | Description                                   |
| :---------- | :---------------- | :-------------------------------------------- |
| **Execute** | Status: `pending` | Start processing the workflow steps            |
| **Delete**  | Any status        | Permanently remove the workflow and its steps  |

### Execution Process

When a workflow is executed, the system processes steps in order:

1. **Pick the next pending step** (respecting position/level order)
2. **Resolve wired variables** from completed upstream steps
3. **Create a resource** using the step's template and resolved variables
4. **Mark the step as done** and record the created resource
5. **Repeat** until all steps are complete or a step fails

Steps at the same position level can execute in parallel, as they have no dependencies on each other.

:::warning[Error Handling]
If any step fails, the workflow is marked as `error`. Steps that haven't started remain in `pending` status. Resources created by completed steps are **not** automatically rolled back — they remain provisioned and can be managed individually.
:::

## Wiring and Dependencies

Wiring rules define how outputs from one template's resource feed into the inputs of another template's resource. The rules are defined on the [Blueprint](./blueprint#wiring-rules) and captured as an immutable snapshot when the workflow is created.

For example, a blueprint wiring a VPC into EKS and RDS templates produces the following execution order:

```
Level 0: VPC Template (no dependencies)
Level 1: EKS Cluster Template, RDS Database Template (both depend on VPC)
```

The VPC is provisioned first. Once complete, its `vpc_id` and `private_subnet_ids` outputs are automatically wired into the EKS and RDS steps, which can then execute in parallel.

## Workflow Status Tracking

Workflows provide real-time visibility into the provisioning process.

### Workflow-Level Status

| Status         | Description                                           |
| :------------- | :---------------------------------------------------- |
| `pending`      | Workflow created but execution not yet started        |
| `in_progress`  | One or more steps are currently executing             |
| `done`         | All steps completed successfully                      |
| `error`        | One or more steps failed during execution             |

### Step-Level Status

| Status         | Description                                           |
| :------------- | :---------------------------------------------------- |
| `pending`      | Step is waiting to be executed                        |
| `in_progress`  | Step is currently provisioning a resource             |
| `done`         | Step completed successfully, resource created         |
| `error`        | Step failed, error message available                  |

## Workflow Permissions

Workflow actions are controlled by role-based access control:

| Action         | Permission Required |
| :------------- | :------------------ |
| **View**       | Read access         |
| **Execute**    | Write access        |
| **Delete**     | Admin access        |

## Workflows vs Direct Resource Creation

Executing a workflow and creating a resource directly are both valid — the difference is orchestration:

- ✅ Use a **Workflow** (via a [Blueprint](./blueprint)): "I need to provision a VPC, EKS cluster, and RDS database with automatic wiring" — dependency order, output passing, and parallel steps are computed for you.
- ✅ Use **Direct Resource Creation**: "I need to create a single S3 bucket" — no wiring, no orchestration overhead.

Note that workflows provide no automatic rollback: resources created by completed steps remain provisioned and are managed individually.

For how Workflows relate to Templates and Executors, see the [comparison table](./blueprint#blueprints-vs-templates-vs-executors) on the Blueprint page.

## Best Practices

For blueprint design and variable management, see [Blueprint — Best Practices](./blueprint#best-practices).

### Execution

- Review resolved variables before executing a workflow
- Start with non-production environments to validate wiring
- Monitor step-by-step progress during execution
- Check step error messages immediately if a workflow fails

### Error Recovery

- If a step fails, investigate the error message and fix the root cause
- Re-execute the workflow — completed steps with existing resources will be skipped
- Individual resources created by completed steps can be managed independently
- Use the resource detail page to inspect outputs and state of completed steps