Creating Blueprints

Combine multiple packages into a reusable, deployable infrastructure blueprint

Overview

Blueprints define the baseline for your environments in Bluebricks. They allow you to combine multiple infrastructure artifacts (such as Terraform modules, Helm charts, OpenTofu projects, or other code repositories) into a single, versioned template that runs together as one unit. Instead of deploying each piece separately, you define how they connect inside a blueprint. When you deploy, Bluebricks orchestrates all included packages and provisions an environment that is an instance of that blueprint version.

Blueprint structure

At a high level, a blueprint contains:

• Metadata: Name, version, description

• Inputs: Configuration exposed to deployers

• Outputs: Values exposed to environments

• Packages: Artifacts, nested blueprints, or source-based packages

How to create a blueprint

Prerequisites:

To create a blueprint, you need at least one package.

If you are using a GitOps environment, Bluebricks publishes blueprints automatically from your source code on every push. You only need to create blueprints manually when working outside of a GitOps workflow.

1

Open the blueprint creation wizard

1. Go to the Packages page in Bluebricks

2. Click Create blueprint

2

Enter metadata

Fill out the fields:

• Name: Unique within your organization

  • Names must be lowercase and can contain letters, numbers, hyphens, dots, and underscores

• Version: Semantic version (e.g., 1.0.0)

• Description: Optionally write how this blueprint will be used

3

Add packages

Choose from published artifacts or blueprints; or create a new artifact:

There are two ways to create an artifact depending on where your code is stored.

If you’ve connected GitHub (or are using a public repo), you can create artifacts directly in the Bluebricks app. If you’re working from a private Github repo or an alternative VCS, artifacts should be published using the CLI.

Choose how you want to create and publish your artifact:

Create an artifact directly from the Bluebricks app

Use this option if you’ve enabled the GitHub integration or are using a public GitHub repository and want your repo to serve as the artifact’s source of truth. Changes to the code will automatically trigger an update process.

To add a artifact:

1. In the packages field, click + Add then click Create artifact

2. In the dialog, click Use repository source

3. Choose the repository and directory that contains your IaC code (for example, a Terraform root module)

4. Fill in the artifact details: name, description, and IaC type

5. Click Create artifact

Create an artifact with the bricks CLI

Use this option if your code is in a private repository without the GitHub integration or hosted in another VCS. Artifact updates must be published via your CI pipeline or manually using the CLI.

To add the package:

1. Open your code’s root directory Use the folder you’d normally run directly (e.g. terraform init/apply or helm install).

2. Publish with the CLI Run from that directory:

   bricks blueprint publish

   This generates bricks.json and publishes the artifact to the Bluebricks catalog.

3. Verify in Bluebricks Go to the Artifacts page in the Bluebricks app to view your newly published artifact and continue to the next step.

Each added package receives an auto-generated ID, [package_name]_[short_hash], which you can edit if deterministic references are required.

4

Configure properties and references

After a package is added, it will appear as a card in the list on the right side of the wizard and display the following:

• Properties (props): Required configuration inputs

• Outputs: Values produced after execution

Properties accept pointer references only:

• inputs.

• data.

• secrets.

Data references

Use outputs from other packages:

vpc_id: data.vpc.vpc_id

You can paste full data. references directly.

Secret references

Reference secrets from your secret manager:

db_password: secrets.db_password

5

Define inputs

Inputs define the global variables of your blueprint. They are declared once at the root level of the blueprint and can be reused across multiple packages.

Inputs appear in the right-side configuration panel and form the deployer interface.

To define an input:

1. Click + Inputs

2. Choose from the inputs associated with the selected packages

   1. You can also create new input fields by clicking Create new input

3. Configure the input field type and value for each input

Input fields type

You can change the input field type by selecting the type icon (e.g., ) in the input field and choosing from the following types:

Type and icon	Description
Default	A pre-filled value used if the deployer does not provide one.
Allowed values	A list of permitted values. Deployers must choose from this list.
Required	Indicates whether the input must be provided. If not set, the input is optional unless no default is defined.

Input example:

inputs:
  region:
    type: string
    description: AWS region
    allowed_values:
      - us-east-1
      - us-west-2

All defined inputs are reflected under the inputs object in the generated JSON.

6

Define outputs

Outputs expose values from your blueprint to environments.

outputs:
  app_server_ip:
    description: Public IP of the app server
    value: data.app_server.public_ip

Only expose outputs that environments or external systems need.

7

Create and publish

When the blueprint is ready, click Create and publish.

Blueprints are immutable once published. Any change requires creating a new version.

When publishing a new version:

• The version becomes selectable in the version switcher

• The latest published version is tagged as Latest

• Outdated child package versions are visually indicated

Create a blueprint via CLI

You can also create and publish blueprints entirely from the command line using Bricks CLI.

Prerequisites

• Bricks CLI installed and authenticated (bricks login)

• At least one published package to compose

1

Initialize a blueprint

bricks blueprint init

The CLI walks you through creating a bricks.json with a name, version, and description.

2

Add packages

bricks blueprint add @bluebricks/terraform_aws_vpc
bricks blueprint add @bluebricks/terraform_aws_subnet

To pin a specific version, append it to the package name:

bricks blueprint add @bluebricks/terraform_aws_vpc@1.2.0

To remove a package:

bricks blueprint remove @bluebricks/terraform_aws_vpc

3

Configure dependencies

Edit bricks.json and use Data.* references to wire package outputs to inputs. Bluebricks resolves these references to build a directed acyclic graph (DAG) and determines execution order automatically. Packages run in parallel where possible.

For details on DAG execution, see Parallel Execution.

4

Publish the blueprint

bricks blueprint publish

Updating and versioning

After publishing, you can bump the version and update nested packages:

bricks blueprint bump --patch
bricks blueprint update --all
bricks blueprint publish

To update a specific package only:

bricks blueprint update @bluebricks/terraform_aws_vpc

You can also define blueprints using bricks.yaml for a slimmer syntax with auto-populated props and outputs. See Publish with bricks.yaml.

Example blueprint

This example blueprint shows how a simple application stack is defined in YAML. It includes basic metadata, a required region input, and three packages that provision a VPC, database, and app server. Values are passed between components using inputs, secrets, and shared data references, and the blueprint finishes by exposing the app server’s public IP as an output.

name: my_app_stack
version: 1.0.0
description: Deploys a VPC, database, and app server
tags: [app, vpc, database, server]

inputs:
  region:
    type: string
    allowed_values:
      - us-east-1
      - us-west-2

packages:
  - name: vpc
    version: 1.0.0
    props:
      region: inputs.region
      cidr_block: 10.0.0.0/16

  - name: database
    version: 1.0.0
    props:
      region: inputs.region
      db_user: admin
      db_password: secrets.db_password
      vpc_id: data.vpc.vpc_id

  - name: app_server
    version: 1.0.0
    props:
      db_host: data.database.endpoint
      db_user: admin
      db_password: secrets.db_password

outputs:
  app_server_ip:
    description: Public IP of the app server
    value: data.app_server.public_ip

Source-based packages (Git)

Blueprints can reference packages directly from Git repositories instead of the Bluebricks registry. This supports Git-first workflows and private infrastructure modules.

Required fields

packages:
  - name: s3
    source: git::https://github.com/org/repo.git?ref=v1.0.0
    native:
      type: terraform
      path: examples/account-public-access

Native fields

Field	Description
type	terraform, opentofu, helm, bicep, generic, cloudformation
path	Root execution path inside the repository

Supported URL formats

Public HTTPS:

git::https://github.com/org/repo.git
git::https://github.com/org/repo.git//subdir?ref=branch

Private SSH (CLI only):

git::ssh://[e-mail]/org/repo.git
git::ssh://[e-mail]/org/repo.git//subdir?ref=branch

Advanced publishing options

The sections above cover the standard workflow. The Bricks CLI also provides flags for more control over how blueprints are prepared, bumped, and updated.

Preparing a blueprint from existing IaC

Use bricks blueprint prepare to generate a bricks.json from existing infrastructure code. This is useful when you have an IaC project and want to turn it into a Bluebricks artifact without restructuring your code manually.

bricks blueprint prepare

Key flags:

• --iac-type: set the IaC type explicitly instead of choosing interactively (terraform, opentofu, helm, cloudformation, bicep). Useful in CI/CD where interactive prompts are unavailable

• --refactor: refactor the existing IaC code in place to match the Bluebricks artifact structure

# Prepare a Terraform project (skip the interactive prompt)
bricks blueprint prepare --iac-type terraform

# Prepare and restructure code in place
bricks blueprint prepare --refactor

If you publish without a bricks.json, the CLI auto-detects .tf files as OpenTofu. Run prepare with --iac-type terraform first if you need Terraform specifically.

Recursive bumping

When a blueprint contains nested packages, use --recursive (-r) to bump all nested packages to their latest published versions in one step:

bricks blueprint bump --patch --recursive

Without --recursive, only the blueprint's own version is bumped.

Advanced update options

bricks blueprint update supports additional flags for fine-grained control:

• --no-bump: update package content without bumping the parent blueprint version

• --overwrite: overwrite the blueprint's bricks.json props and outputs from a recently updated artifact

• --major / --minor / --patch: control which segment of the parent version is bumped

• --yes (-y): skip interactive approval

# Update a package without bumping the blueprint version
bricks blueprint update @bluebricks/terraform_aws_vpc --no-bump

# Update and overwrite props/outputs from the updated artifact
bricks blueprint update @bluebricks/terraform_aws_vpc --overwrite

# Update all packages with a minor version bump, skip confirmation
bricks blueprint update --all --minor --yes

All flags are documented in the CLI Reference. The examples above cover when and why to use each option.

See also

• Publish with bricks.yaml: simplified YAML-based publishing with auto-populated props

• Blueprint Composition Patterns: architectural patterns, dependency management, and output strategies

• Using expr: expression language for dynamic configuration in bricks.json

• Parallel Execution: how Bluebricks resolves the DAG and runs packages in parallel