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.

circle-info

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 Packagesarrow-up-right 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:

chevron-rightCreate an artifact directly from the Bluebricks apphashtag

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

chevron-rightCreate an artifact with the bricks CLIhashtag

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:

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

  3. Verify in Bluebricks Go to the Artifactsarrow-up-right 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:

You can paste full data. references directly.

Secret references

Reference secrets from your secret manager:

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:

circle-info

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

6

Define outputs

Outputs expose values from your blueprint to environments.

circle-exclamation
7

Create and publish

When the blueprint is ready, click Create and publish.

circle-info

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

1

Initialize a blueprint

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

2

Add packages

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

To remove a package:

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

Updating and versioning

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

To update a specific package only:

circle-info

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.

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

Native fields

Field
Description

type

terraform, opentofu, helm, bicep, generic, cloudformation

path

Root execution path inside the repository

Supported URL formats

Public HTTPS:

Private SSH (CLI only):

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.

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

circle-info

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:

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

circle-info

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

See also

Last updated

Was this helpful?