Blueprints

Blueprints are the core of Bluebricks, allowing you to define and manage your infrastructure templates. Blueprints compose one or more artifacts (or other blueprints) and define how they work together.

Complete Example: bricks.yaml

Below is a copy-paste-ready example of a blueprint that demonstrates data references, secret references, and hardcoded/user-provided props:

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 an global input
      cidr_block: 10.0.0.0/16 # Hardcoded value

  - name: database
    version: 1.0.0
    props:
      region: inputs.region #Reference to an 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.databse.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

Validation Rules

• Blueprint (name): Must start with a letter or underscore, and contain only letters, numbers, and underscores.

• inputs and output names: Must start with a letter or underscore, and contain only letters, numbers, and underscores.

• No spaces or special characters are allowed in names.

• Version: Must follow semantic versioning (MAJOR.MINOR.PATCH), e.g., 1.0.0.

Key Fields

• name: Blueprint identifier

• version: Semantic version (required)

• description: Human-readable description

• packages: List of referenced artifacts/blueprints

• inputs: Input parameters for the blueprint

• outputs: Output values exposed by the blueprint

Properties Options

Properties defined the input variables that the blueprint will use and how they will be used, including restrictions or origin of variable (from another package).

inputs fields:

• Property name: defines the name of the property as it will be used throughout the code and/or during environment run.

• type: The data type of the property

• description: Human-readable description

• default: Default value if exist for the property, this value will be used if not supplied during environment run

• allowed_values: List of values that are allowed to be used. During install, the supplied variable will be verified against this list. The app will list only these options on the environment page.

inputs structure:

inputs:
  input_name:
    type: data type # Optional
    description: Human-readable description # a description of the input
    defualt: value # Optional
    allowed_values: #Optional
      - value1
      - value2

Bluebricks app allowed values example:

Allowed values selection

Source-Based Packages

In addition to using packages published to the Bluebricks package registry, Blueprints can also reference source-based packages - packages that are pulled directly from a Git repository outside of the Bluebricks registry. This allows you to consume version-controlled IaC from its original source while still benefiting from Bluebricks orchestration, visibility, and environment workflows.

Source-based packages are useful when you want to keep infrastructure code in an external repository, use internal modules that aren’t published to the registry, or adopt a Git-first workflow where Bluebricks consumes packages directly from source.

To define a source-based package in a Blueprint, you’ll need to add the following fields:

• source: the Git source URL of the package code

• native: describes the package type and where the code lives inside the repository:

  • type: the type of package, aligned with the native artifact types Bluebricks supports (Terraform, OpenTofu, Helm, Bicep, Generic, CloudFormation)

  • path: the path to the root execution path inside the repository (i.e terraform root module, helm chart location, etc..)

This allows Bluebricks to fetch the package directly from Git, understand how to execute it, and treat it like any other package in the Blueprint—while keeping the source of truth in your repository.

Supported URLs

• Public git URL: git::https://github.com/hashicorp/terraform.git

  • Supported also with subdirectory and ref: git::https://github.com/hashicorp/terraform.git//subdir?ref={branch, tag, commit}

  • Could be defined in the app as well as using CLI

Source-Based Package example

name: aws_s3
version: 1.0.0
description: create an s3 bucket
packages:
  - name: s3
    source: git::https://github.com/terraform-aws-modules/terraform-aws-s3-bucket.git?ref=v5.10.0
    native:
      type: terraform
      path: examples/account-public-access