Blueprints

Blueprints are reusable templates that compose infrastructure stacks

Most infrastructure stacks are made up of multiple components: a VPC, a database, a compute cluster, a load balancer. Each might live in its own Terraform module or Helm chart. A blueprint wires these components together into a cohesive unit that others can deploy reliably, again and again.

Think of it like a Docker Compose file for infrastructure. Compose defines how containers connect through networks and volumes; a blueprint defines how IaC components connect through data references and shared properties.

Blueprint as a composition layer

A blueprint wraps one or more packages (each representing a distinct infrastructure component) and defines how they connect.

Bluebricks maps the relationships between package inputs and outputs and builds a directed acyclic graph (DAG) to determine execution order. Packages run in parallel where possible and sequentially where one depends on another's output.

This means you can build small, focused artifacts and assemble them into larger stacks without duplicating code or managing execution order manually.

Complete Example: bricks.yaml

name: my_app_stack # (Required) Unique blueprint name
version: 1.0.0 # (Required) Semantic version (MAJOR.MINOR.PATCH)
description: Deploys a VPC, database, and app server with secure secret handling  # (Optional)
tag: [app, vpc, database, server] # (Optional)
inputs:
  region:
    type: string
    allowed_values:
      - us-east-1
      - us-west-2

packages:
  - name: vpc # Reference to an artifact or blueprint
    version: 1.0.0
    props:
      region: inputs.region # Reference to a global input
      cidr_block: 10.0.0.0/16 # Hardcoded value

  - name: database
    version: 1.0.0
    props:
      region: inputs.region # Reference to a global input
      db_user: admin # Hardcoded value
      db_password: secrets.db_password # Secret reference
      vpc_id: data.vpc.vpc_id # Data reference to an output of another package

  - name: app_server
    version: 1.0.0
    props:
      db_host: data.database.endpoint # Data reference to an output of another package
      db_user: admin # Hardcoded value
      db_password: secrets.db_password # Secret reference
      
outputs:
  app_server_ip:
    description: Public IP address of the app server
    value: data.app_server.public_ip # Data reference to an output of a package

Conceptual diagram

In the diagram, three artifacts compose into a blueprint. Data references between them define the execution order (the DAG). An environment binds the blueprint to a collection, which supplies credentials, properties, and secrets.

Blueprint as an interface

A blueprint acts as a contract between the person who builds it and the person who deploys it.

What the builder defines:

• Properties (inputs): the values a deployer can or must provide at deployment time. Each property can be marked as required, given a default, or constrained to a set of allowed values.

• Outputs: values that the blueprint surfaces after execution, such as endpoint URLs, resource IDs, or connection strings. Other blueprints or downstream systems can consume these.

• Internal wiring: data references and hardcoded values that stay hidden from the deployer.

What the deployer sees:

• A list of required and optional properties to fill in

• A description of what the blueprint provisions

• The outputs it will produce

This separation is intentional. The deployer doesn't need to know that the blueprint internally connects three Terraform modules and a Helm chart. They see a clean interface: "provide a region, an instance size, and a cluster name, and you get a running Kubernetes cluster with a load balancer endpoint."

Blueprint as a versioned contract

Every published blueprint is immutable and follows semantic versioning (MAJOR.MINOR.PATCH).

This model gives teams reproducibility and trust. When you deploy version 2.1.0 of a network blueprint today and again three months later, you get the same behavior. No one can silently change a published version. If the blueprint needs to evolve, a new version is published.

Immutability also supports auditability. Every environment tracks which blueprint version it ran, making it straightforward to trace what changed and when.

Blueprint in the deployment lifecycle

A blueprint on its own is a template. It doesn't provision anything until it's bound to an environment targeting a specific collection.

The lifecycle works like this:

1. Build: a builder creates and publishes a blueprint with defined packages, properties, and outputs.

2. Install: a deployer installs the blueprint into an environment, selecting a target collection and providing property values.

3. Plan: Bluebricks evaluates the DAG, resolves data references and secrets from the collection, and produces a unified plan across all packages.

4. Apply: the plan executes, provisioning or updating resources in the correct dependency order.

5. Iterate: subsequent runs re-evaluate the same blueprint version against the current state, enabling incremental updates, drift correction, or teardown.

The collection provides the runtime context: cloud account credentials, properties, and secrets. The blueprint provides the structural definition. This separation means you can deploy the same blueprint across development, staging, and production collections without modification.