# Creating Blueprints

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

<figure><img src="/files/MLHyAkgxkusqBt8M4Rd2" alt=""><figcaption></figcaption></figure>

## How to create a blueprint

#### **Prerequisites**:

To create a blueprint, you need at least one [package](/docs/orchestration/packages.md).

{% hint style="info" %}
If you are using a [GitOps environment](/docs/orchestration/environments/gitops-environments.md), 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.
{% endhint %}

{% stepper %}
{% step %}
**Open the blueprint creation wizard**

1. Go to the [Packages](https://app.bluebricks.co/packages) page in Bluebricks
2. Click **Create blueprint**
   {% endstep %}

{% step %}
**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
  {% endstep %}

{% step %}
**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](/docs/integrations/github.md) (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:

<details>

<summary>Create an artifact directly from the Bluebricks app</summary>

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

</details>

<details>

<summary>Create an artifact with the bricks CLI</summary>

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:

   ```bash
   bricks blueprint publish
   ```

   This generates `bricks.json` and publishes the artifact to the Bluebricks catalog.
3. **Verify in Bluebricks**\
   Go to the [Artifacts](https://app.bluebricks.co/packages?tab=artifact) page in the Bluebricks app to view your newly published artifact and continue to the next step.

</details>

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

{% step %}
**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:

```yaml
vpc_id: data.vpc.vpc_id
```

You can paste full `data.` references directly.

**Secret references**

Reference secrets from your secret manager:

```yaml
db_password: secrets.db_password
```

{% endstep %}

{% step %}
**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

<figure><img src="/files/Yd3cYki9TyzUDAO7wKyo" alt=""><figcaption></figcaption></figure>

**Input fields type**

You can change the input field type by selecting **the type icon** (e.g., ![](/files/vyPeR3fCyjAmSzeOAA2X)) in the input field and choosing from the following types:

<table><thead><tr><th width="176.6875">Type and icon</th><th>Description</th></tr></thead><tbody><tr><td><img src="/files/gTNMqGqczbR3XZZ3Uhaz" alt="" data-size="line"> Default</td><td>A pre-filled value used if the deployer does not provide one.</td></tr><tr><td><img src="/files/oAiKcIcHf8awSanrF3kq" alt="" data-size="line"> Allowed values</td><td>A list of permitted values. Deployers must choose from this list.</td></tr><tr><td><img src="/files/bDS9rg2skhZC9YoTd1Jr" alt="" data-size="line"> Required</td><td>Indicates whether the input must be provided. If not set, the input is optional unless no <code>default</code> is defined.</td></tr></tbody></table>

**Input example**:

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

{% hint style="info" %}
All defined inputs are reflected under the `inputs` object in the generated JSON.
{% endhint %}
{% endstep %}

{% step %}
**Define outputs**

Outputs expose values from your blueprint to environments.

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

{% hint style="warning" %}
Only expose outputs that environments or external systems need.
{% endhint %}
{% endstep %}

{% step %}
**Create and publish**

When the blueprint is ready, click **Create and publish**.

{% hint style="info" %}
Blueprints are immutable once published. Any change requires creating a new version.
{% endhint %}

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
  {% endstep %}
  {% endstepper %}

## Create a blueprint via CLI

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

### Prerequisites

* Bricks CLI [installed](/docs/bricks-cli/bricks-cli.md) and [authenticated](/docs/bricks-cli/authentication.md) (`bricks login`)
* At least one published [package](/docs/orchestration/packages.md) to compose

{% stepper %}
{% step %}
**Initialize a blueprint**

```bash
bricks blueprint init
```

The CLI walks you through creating a `bricks.json` with a name, version, and description.
{% endstep %}

{% step %}
**Add packages**

```bash
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:

```bash
bricks blueprint add @bluebricks/terraform_aws_vpc@1.2.0
```

To remove a package:

```bash
bricks blueprint remove @bluebricks/terraform_aws_vpc
```

{% endstep %}

{% step %}
**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](/docs/orchestration/runs/parallel-execution.md).
{% endstep %}

{% step %}
**Publish the blueprint**

```bash
bricks blueprint publish
```

{% endstep %}
{% endstepper %}

### Updating and versioning

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

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

To update a specific package only:

```bash
bricks blueprint update @bluebricks/terraform_aws_vpc
```

{% hint style="info" %}
You can also define blueprints using `bricks.yaml` for a slimmer syntax with auto-populated props and outputs. See [Publish with bricks.yaml](/docs/orchestration/packages/blueprints-overview/publish-with-bricks-yaml.md).
{% endhint %}

## 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.

```yaml
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

```yaml
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

<table><thead><tr><th width="122.82421875">Field</th><th width="607.8046875">Description</th></tr></thead><tbody><tr><td>type</td><td>terraform, opentofu, helm, bicep, generic, cloudformation</td></tr><tr><td>path</td><td>Root execution path inside the repository</td></tr></tbody></table>

#### 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://git@github.com/org/repo.git
git::ssh://git@github.com/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.

```bash
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

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

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

{% hint style="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.
{% endhint %}

### Recursive bumping

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

```bash
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

```bash
# 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
```

{% hint style="info" %}
All flags are documented in the [CLI Reference](/docs/bricks-cli/cli-reference/bricks_blueprint.md). The examples above cover when and why to use each option.
{% endhint %}

## See also

* [Publish with bricks.yaml](/docs/orchestration/packages/blueprints-overview/publish-with-bricks-yaml.md): simplified YAML-based publishing with auto-populated props
* [Blueprint Composition Patterns](/docs/orchestration/packages/blueprints-overview/blueprint-composition-patterns.md): architectural patterns, dependency management, and output strategies
* [Using expr](/docs/orchestration/packages/blueprints-overview/expr.md): expression language for dynamic configuration in `bricks.json`
* [Parallel Execution](/docs/orchestration/runs/parallel-execution.md): how Bluebricks resolves the DAG and runs packages in parallel


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/packages/blueprints-overview/creating-blueprints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.