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.

1

Open the blueprint creation wizard

1. Go to the packages page in Bluebricks

2. Click Create blueprint

2

Enter metadata

Fill out the the fields:

• Name – Unique within your organization

  • Names should start with a letter and contain only letters, numbers, 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 package:

1. In the packages field, click + Add then click New Package

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

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

4. Click Create package

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 bprint 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

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://[email protected]/org/repo.git
git::ssh://[email protected]/org/repo.git//subdir?ref=branch