Parallel Execution

How Bluebricks builds a dependency graph from your blueprint and executes packages in parallel.

When a run starts, Bluebricks evaluates every package in the blueprint and builds a directed acyclic graph (DAG) based on Data references between packages. Independent packages execute in parallel; dependent packages wait for their inputs.

Data references

Data references let one package consume the outputs of another:

Data.<packageId>.<outputKey>

• Data. is the reserved prefix for cross-package references

• <packageId> is the unique ID of the source package

• <outputKey> is the name of the output

Example JSON

{
  "packages": [
    {
      "id": "vpc_module",
      "props": {
        "region": { "value": "Props.region" }
      }
    },
    {
      "id": "eks_cluster",
      "props": {
        "vpc_id": { "value": "Data.vpc_module.vpc_id" },
        "subnet_ids": { "value": "Data.vpc_module.private_subnet_ids" }
      }
    }
  ]
}

Here eks_cluster depends on vpc_module. Bluebricks executes vpc_module first, then passes its vpc_id and private_subnet_ids outputs to eks_cluster.

Data references in expressions

You can combine Data references with other values using expr expressions

Example JSON

{
  "props": {
    "bucket_name": {
      "value": "'my-app-' + Data.vpc_module.vpc_id + '-logs'"
    },
    "enable_logging": {
      "value": "Props.create_bucket || Data.s3_module.bucket_exists"
    }
  }
}

Expressions are evaluated at runtime after dependencies complete.

Plan vs apply

Data references behave differently in each phase:

• Plan phase: Bluebricks identifies that a value will change but does not resolve the actual value yet

• Apply phase: Actual values are resolved, passed to dependent packages, and used in expressions

The data flow model

Bluebricks uses a hierarchical data flow:

• Properties flow down from parent to child packages, set at deployment time, referenced with Props.<key>

• Data flows up from child packages to parent, calculated at runtime, referenced with Data.<packageId>.<key>

How the DAG determines execution order

Consider this blueprint:

Example JSON

{
  "packages": [
    {
      "id": "launch_template",
      "props": {
        "name": { "value": "Props.template_name" }
      }
    },
    {
      "id": "s3_bucket",
      "props": {
        "bucket_name": {
          "value": "'logs-' + Data.launch_template.launch_template_id"
        }
      }
    },
    {
      "id": "monitoring",
      "props": {
        "template_id": {
          "value": "Data.launch_template.launch_template_id"
        }
      }
    }
  ]
}

Execution order:

1. launch_template runs first (no dependencies)

2. s3_bucket and monitoring run in parallel (both depend only on launch_template)

Data reference chains

Data references can form chains across nested blueprints.

Example JSON

{
  "packages": [
    { "id": "vpc" },
    {
      "id": "subnet_blueprint",
      "packages": [
        {
          "id": "subnet_module",
          "props": {
            "vpc_id": { "value": "Data.vpc.vpc_id" }
          }
        }
      ],
      "outs": {
        "subnet_id": { "value": "Data.subnet_module.subnet_id" }
      }
    },
    {
      "id": "instance",
      "props": {
        "subnet_id": { "value": "Data.subnet_blueprint.subnet_id" }
      }
    }
  ]
}

Bluebricks resolves the full chain: vpc outputs vpc_id, subnet_module uses it to create subnets, subnet_blueprint exposes subnet_id, and instance receives it.

Designing for parallelism

Minimize Data references between packages to maximize parallel execution.

Sequential (slow): each package depends on the previous one

{
  "packages": [
    { "id": "A" },
    { "id": "B", "props": { "input": { "value": "Data.A.output" } } },
    { "id": "C", "props": { "input": { "value": "Data.B.output" } } }
  ]
}

Parallel (fast): packages use properties instead of cross-package Data references where possible

{
  "packages": [
    { "id": "A", "props": { "input": { "value": "Props.value" } } },
    { "id": "B", "props": { "input": { "value": "Props.value" } } },
    { "id": "C", "props": { "input": { "value": "Props.value" } } }
  ]
}

Group related resources into sub-blueprints so internal dependencies don't block other stacks

{
  "packages": [
    {
      "id": "network_stack",
      "packages": [
        { "id": "vpc" },
        { "id": "subnets" },
        { "id": "route_tables" }
      ]
    },
    {
      "id": "compute_stack",
      "packages": [
        { "id": "launch_templates" },
        { "id": "auto_scaling_groups" }
      ]
    }
  ]
}

network_stack and compute_stack execute in parallel if there are no Data references between them.

Best practices

• Use Props for static configuration, Data for runtime values

• Never create circular dependencies (A depends on B, B depends on A)

• Reference only outputs that will definitely be available

• Use descriptive output keys so Data references are self-documenting

• Keep expressions readable; avoid deeply nested logic

See also

• Runs

• Inputs & Outputs

• Creating Blueprints

• Using expr