workflow

big-config.workflow

The goal of the BigConfig Workflow is to enable independent development of automation units while providing a structured way to compose them into complex pipelines.

Workflow Types

• tool-workflow: The fundamental unit. It renders templates and executes CLI tools (e.g., Terraform/OpenTofu, Ansible). It is driven by ::params.
• comp-workflow: A high-level orchestrator that sequences multiple tool-workflows to create a unified lifecycle (e.g., create, delete).

Usage Syntax

# Execute a tool workflow directly
bb <tool-workflow> <step|cmd>+ [-- <raw-command>]

# Execute a composite workflow
bb <comp-workflow> <step>+

Examples

# Individual development/testing
bb tool-wf-a render tofu:init -- tofu apply -auto-approve
bb tool-wf-b render ansible-playbook:main.yml

# Orchestrated execution
bb comp-wf-c create

In this example, comp-wf-c composes tool-wf-a and tool-wf-b. Development and debugging happen within the individual tool workflows, while the composite workflow manages the sequence.

Core Logic & Functions

• run-steps: The engine for dynamic workflow execution.
• prepare: Shared logic for rendering templates and initializing execution environments.
• parse-tool-args / parse-comp-args: Utility functions to normalize string or vector-based arguments.

Options for opts

• ::name (required): The unique identifier for the workflow instance.
• ::dirs (generated): Directory context for execution and output discovery. It is generated automatically by prepare.
• ::path-fn (optional): Logic for resolving file paths.
• ::params (optional): The input data for the workflow.

Naming Conventions

To distinguish between the library core and the Babashka CLI implementation:

• [workflow name]*: The library-level function. Requires step-fns and opts.
• [workflow name]: The Babashka-ready task. Accepts args and optional opts.

; wf.clj
(defn tofu*
  [step-fns opts]
  (let [opts (prepare {::name ::tofu
                       ::render/templates [{:template "tofu"
                                            :overwrite true
                                            :transform [["tofu"
                                                         :raw]]}]}
                      opts)]
    (run-steps step-fns opts)))

(defn tofu
  [args & [opts]]
  (let [opts (merge (parse-tool-args args)
                    opts)]
    (tofu* [] opts)))

; bb.edn
{:deps {group/artifact {:local/root "."}}
 :tasks
 {:requires ([group.artifact.wf :as wf])
  tofu {:doc "bb tofu render tofu:init tofu:apply:-auto-approve"
        :task (wf/tofu *command-line-args* {:big-config/env :shell})}
  ansible {:doc "bb ansible render -- ansible-playbook main.yml"
           :task (wf/ansible *command-line-args* {:big-config/env :shell})}
  resource {:doc "bb resource create and delete a resource"
            :task (wf/resource *command-line-args* {:big-config/env :shell})}}}

Decoupled Data Sharing

Standard Terraform/HCL patterns often lead to tight coupling, where downstream resources must know the exact structure of upstream providers (e.g., the specific IP output format of AWS vs. Hetzner).

BigConfig Workflow solves this through Parameter Adaptation:

1. Isolation: tool-wf-b (Ansible) never talks directly to tool-wf-a (Tofu).
2. Orchestration: The comp-workflow acts as a glue layer. It uses ::dirs to discover outputs from the first workflow (via tofu output --json) and maps them to the ::params required by the next.
3. Interchangeability: You can swap a Hetzner workflow for an AWS workflow without modifying the downstream Ansible code. Only the mapping logic in the comp-workflow needs to be updated.

Note: Resource naming and state booking are outside the scope of BigConfig Workflow.

keyword->path

(keyword->path kw)

Function.

_Source

parse-comp-args

(parse-comp-args str-or-args)

Function.

_Source

parse-tool-args

(parse-tool-args str-or-args)

Function.

_Source

prepare

(prepare opts overrides)

Function.

Prepare opts. See the namespace big-config.workflow.

_Source

print-step-fn

(print-step-fn step opts)

Function.

Print all steps of the workflow.

_Source

run-steps

(run-steps)
(run-steps opts)
(run-steps step-fns opts)

Function.

Run the steps of a tool workflow.

_Source