Publish with bricks.yaml

Publish blueprints using bricks.yaml format for simplified syntax, multi-document support, and YAML-native features.

Why bricks.yaml?

bricks.yaml provides a slimmer, more maintainable alternative to bricks.json:

• Simplified syntax - Only specify what you need to change

• Auto-populated fields - Props and outputs inherited from packages

• Multi-document support - Publish multiple blueprints from one file

• YAML features - Anchors, aliases, and merge keys for reusable configuration

• Higher priority - When both files exist, YAML takes precedence

Example comparison:

Original bricks.json: 346 lines Equivalent bricks.yaml: 30 lines

Basic Format

Minimal Blueprint

name: web_application
version: 1.0.0
packages:
  - name: terraform_aws_vpc
    version: 3.0.0

Required fields:

• name - Blueprint name

• version - Blueprint version (semver)

• packages - Non-empty list of packages (at least one)

Note: All field names are lowercase: name, version, packages, inputs, outputs, props

Complete Blueprint

name: web_infrastructure
version: 1.0.0
description: Web application infrastructure on AWS
tags:
  - aws
  - production

inputs:
  region:
    type: string
    default: us-east-1
    description: AWS region
  vpc_cidr:
    type: string
    default: 10.0.0.0/16

packages:
  - id: network
    name: terraform_aws_vpc
    version: 3.0.0
    props:
      cidr_block: inputs.vpc_cidr
      region: inputs.region

  - id: database
    name: terraform_aws_rds
    version: 2.1.0
    props:
      vpc_id: data.network.vpc_id
      subnet_ids: data.network.private_subnet_ids

outputs:
  vpc_id:
    value: data.network.vpc_id
    description: VPC identifier
  db_endpoint:
    value: data.database.endpoint
    description: Database endpoint

Package Configuration

Auto-Populated Props

You only need to specify props you want to change or override. All other props from the package definition are automatically included.

packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      region: inputs.region
      # All other props (bucket_name, encryption, etc.)
      # are automatically included from package definition

When to specify props:

• Override default values

• Connect to other packages via data references

• Use blueprint inputs

• Set hardcoded values

Explicit Package IDs

Specify the id field when:

• Using the same package multiple times

• Referencing package outputs in other packages

• Ensuring predictable output references

packages:
  - id: api_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      function_name: api-handler

  - id: worker_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      function_name: worker-handler

  - id: scheduler_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      function_name: scheduler-handler

Without explicit IDs, the CLI generates IDs automatically, making it harder to predict output references.

Auto-Populated Outputs

Package outputs are automatically included. You only need to specify outputs in the blueprint if you want to:

• Override output values

• Add conditional outputs

• Change output names

• Add additional outputs not in the package

outputs:
  # Only specify if you need to override or add conditions
  vpc_id:
    value: data.network.vpc_id
    condition: inputs.create_vpc

If you don't need to modify outputs, omit the outputs section entirely.

Value References

Data References

Reference outputs from other packages using data.<package_id>.<output_key>:

packages:
  - id: vpc
    name: terraform_aws_vpc
    version: 3.0.0

  - id: subnet
    name: terraform_aws_subnet
    version: 2.0.0
    props:
      vpc_id: data.vpc.vpc_id
      availability_zone: data.vpc.availability_zones

Important: Use lowercase data, not Data.

For detailed information on how data references create dependencies and DAG execution order, see How to Create Blueprints.

Input References

Reference blueprint inputs using inputs.<input_key>:

inputs:
  environment:
    type: string
    default: dev
  region:
    type: string
    default: us-east-1

packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      bucket_name: inputs.environment
      region: inputs.region

Important: Use lowercase inputs, not Inputs.

String Values

How values are interpreted:

Simple references (no quotes needed):

props:
  vpc_id: data.vpc.vpc_id          # Data reference
  region: inputs.region             # Input reference
  function_name: execute            # Plain string

Strings with special characters (use quotes):

props:
  function_name: 'execute-api'      # Dash requires quotes
  bucket_name: 'my-app-logs'        # Dash requires quotes

Detection order:

1. inputs.* pattern → Input reference

2. data.* pattern → Data reference

3. Expression matching → Expression

4. Fallback → String literal

YAML Features

Anchors and Aliases

Define configuration once with anchors (&name) and reuse with aliases (*name):

name: shared_configuration
version: 1.0.0

common_settings: &defaults
  region: us-east-1
  timeout: 300
  retries: 3

packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      <<: *defaults
      bucket_name: application-data

  - name: terraform_aws_dynamodb
    version: 1.8.0
    props:
      <<: *defaults
      table_name: application-state

Merge Keys

Combine multiple configurations with merge keys (<<):

name: merged_settings
version: 1.0.0

base_config: &base
  timeout: 300
  retries: 3

monitoring_config: &monitoring
  logging_enabled: true
  metrics_enabled: true

packages:
  - name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: [*base, *monitoring]
      function_name: api-handler

Anchors with Package Repetition

Use anchors when repeating the same package:

name: multi_lambda
version: 1.0.0

inputs:
  runtime:
    type: string
    default: python3.11

packages:
  - &lambda_base
    id: api_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      runtime: inputs.runtime
      function_name: api-handler

  - <<: *lambda_base
    id: worker_lambda
    props:
      function_name: worker-handler

  - <<: *lambda_base
    id: scheduler_lambda
    props:
      function_name: scheduler-handler

Note: When overriding props with anchors, you replace the entire props object. To merge props, use nested anchors:

lambda_props: &common_props
  runtime: inputs.runtime
  timeout: 300

packages:
  - id: api_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: *common_props
      function_name: api-handler

  - id: worker_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: *common_props
      function_name: worker-handler

Input Configuration

Input Types

Define blueprint inputs with types, defaults, and constraints:

inputs:
  environment:
    type: string
    default: dev
    description: Deployment environment
    allowed_values:
      - dev
      - staging
      - prod

  instance_count:
    type: number
    default: 2
    description: Number of instances

  enable_monitoring:
    type: bool
    default: true
    description: Enable CloudWatch monitoring

  region:
    type: string
    description: AWS region (required - no default)

Without default: Input is required at deployment time

With default: Input is optional, uses default if not provided

Allowed Values

Restrict input values to specific options:

inputs:
  instance_type:
    type: string
    default: t3.micro
    allowed_values:
      - t3.micro
      - t3.small
      - t3.medium
      - t3.large

Multi-Document YAML

Publish multiple blueprints from a single file using document separators (---):

name: vpc_blueprint
version: 1.0.0
packages:
  - name: terraform_aws_vpc
    version: 3.0.0
    props:
      cidr_block: inputs.vpc_cidr

---

name: database_blueprint
version: 2.0.0
packages:
  - name: terraform_aws_rds
    version: 2.1.0
    props:
      engine: postgres
      instance_class: inputs.db_instance_class

---

name: storage_blueprint
version: 1.5.0
packages:
  - name: terraform_aws_s3
    version: 2.5.0
    props:
      bucket_name: inputs.bucket_name

Each document is published as a separate blueprint.

Publishing

Publish your blueprint using the standard command:

bricks blueprint publish

File Priority:

When both bricks.yaml and bricks.json exist, YAML takes precedence:

Warning: Both bricks.json and bricks.yaml found. Using bricks.yaml (higher priority).

For more details on publishing workflows, see How to Create Blueprints.

Multi-Document Publishing

$ bricks blueprint publish

Publishing 3 blueprint(s) from bricks.yaml...

Blueprints to be published:
  - [1/3] vpc_blueprint@1.0.0
  - [2/3] database_blueprint@2.0.0
  - [3/3] storage_blueprint@1.5.0

[1/3] Preparing to publish slim blueprint: vpc_blueprint@1.0.0
[1/3] Published slim blueprint: vpc_blueprint@1.0.0

[2/3] Preparing to publish slim blueprint: database_blueprint@2.0.0
[2/3] Published slim blueprint: database_blueprint@2.0.0

[3/3] Preparing to publish slim blueprint: storage_blueprint@1.5.0
[3/3] Published slim blueprint: storage_blueprint@1.5.0

Summary:
  - [1/3] vpc_blueprint@1.0.0: Published successfully
  - [2/3] database_blueprint@2.0.0: Published successfully
  - [3/3] storage_blueprint@1.5.0: Published successfully

Validation During Publish

The CLI validates your YAML during publish:

Missing version:

Error: blueprint 1: missing 'version' property

Invalid package version:

[1/1] Failed to publish slim blueprint: my_blueprint@1.0.0
Error: Could not find artifact helm_argo_cd version 1.0.1

Invalid output reference:

Error: output key 'endpoint' not found in package 'database'

Malformed YAML:

Error: failed to parse bricks.yaml: yaml: line 15: did not find expected key

Development Workflow

Finding Packages

Search for packages to add to your blueprint:

# Search for packages by keyword
bricks bp search -q "vpc"
bricks bp search -q "s3"
bricks bp search -q "lambda"

# Results show package names and latest versions
# Example output:
# terraform_aws_vpc@3.0.0
# terraform_aws_vpc_peering@1.2.0
# terraform_aws_s3@2.5.0

Inspecting Package Details

Get package information before adding to your blueprint:

# Get full package details including version, props, and outputs
bricks bp get terraform_aws_vpc

Example output:

Package: terraform_aws_vpc
Latest Version: 3.0.0
Description: AWS VPC Terraform module

Props:
  - cidr_block (string, required)
  - region (string, default: us-east-1)
  - enable_dns (bool, default: true)
  - tags (map, optional)

Outputs:
  - vpc_id (string)
  - subnet_ids (list)
  - availability_zones (list)

Viewing Props and Outputs

Check available props and outputs for a specific version:

# View all props with defaults
bricks blueprint get props terraform_aws_vpc@3.0.0

# View all outputs
bricks blueprint get outs terraform_aws_vpc@3.0.0

Building Your YAML

Use the information from bricks bp get to construct your blueprint:

Step 1: Search and identify packages

bricks bp search -q "vpc"
bricks bp search -q "rds"

Step 2: Get package details

bricks bp get terraform_aws_vpc
bricks bp get terraform_aws_rds

Step 3: Create bricks.yaml

name: my_infrastructure
version: 1.0.0

inputs:
  region:
    type: string
    default: us-east-1

packages:
  - id: vpc
    name: terraform_aws_vpc
    version: 3.0.0
    props:
      region: inputs.region
      # Only specify props you want to override
      # All other props from 'bricks bp get' are auto-included

  - id: database
    name: terraform_aws_rds
    version: 2.1.0
    props:
      vpc_id: data.vpc.vpc_id
      # Reference outputs shown in 'bricks blueprint get outs'

Step 4: Verify references

# Ensure output keys exist before referencing
bricks blueprint get outs terraform_aws_vpc@3.0.0
# Verify 'vpc_id' is listed

# Check if prop names match
bricks blueprint get props terraform_aws_rds@2.1.0
# Verify 'vpc_id' is a valid prop

Iterative Development

Build your blueprint incrementally:

# 1. Start with minimal blueprint
cat > bricks.yaml << 'EOF'
name: test_blueprint
version: 1.0.0
packages:
  - name: terraform_aws_vpc
    version: 3.0.0
EOF

# 2. Test publish
bricks blueprint publish

# 3. View the generated full blueprint
bricks bp describe test_blueprint > bricks.json
# This shows the "fat" version with all auto-populated props and outputs

# 4. Add more packages iteratively
# Search for next package
bricks bp search -q "s3"

# Get details
bricks bp get terraform_aws_s3

# Add to bricks.yaml
# ... edit file ...

# 5. Publish again
bricks blueprint publish

# 6. View updated blueprint
bricks bp describe test_blueprint > bricks.json

Viewing Generated Blueprint

After publishing, view the full hydrated blueprint:

# Generate full bricks.json with all props and outputs
bricks bp describe my_blueprint > bricks.json

This shows:

• All props - Including defaults from packages

• All outputs - Including auto-populated outputs

• Generated IDs - For packages without explicit IDs

• Full resolution - How inputs and data references resolve

Example comparison:

Your bricks.yaml (30 lines):

name: web_infrastructure
version: 1.0.0
packages:
  - id: vpc
    name: terraform_aws_vpc
    version: 3.0.0
    props:
      region: inputs.region

Generated bricks.json (346 lines):

{
  "name": "web_infrastructure",
  "version": "1.0.0",
  "packages": [
    {
      "id": "vpc",
      "name": "terraform_aws_vpc",
      "version": "3.0.0",
      "props": {
        "region": {
          "value": "Props.region"
        },
        "cidr_block": {
          "value": "Props.cidr_block",
          "type": "string",
          "default": "10.0.0.0/16"
        },
        "enable_dns_hostnames": {
          "value": "Props.enable_dns_hostnames",
          "type": "bool",
          "default": true
        }
        // ... all other props auto-populated
      }
    }
  ],
  "outs": {
    "vpc_id": {
      "value": "Data.vpc.vpc_id",
      "type": "string"
    }
    // ... all outputs auto-populated
  }
}

Migration from bricks.json

Lazy Migration Approach

You don't need to migrate all blueprints at once:

1. Keep existing bricks.json files working

2. Create new blueprints with bricks.yaml

3. Migrate gradually as you update blueprints

Converting Existing Blueprints

Manual conversion:

1. Create new bricks.yaml file

2. Copy name, version, description, tags

3. Define inputs from props

4. List packages (only override props as needed)

5. Add outputs only if customizing

6. Test with bricks blueprint publish

Keep reference:

my-blueprint/
├── bricks.json          # Keep for reference (ignored)
└── bricks.yaml          # Used by CLI (takes precedence)

What Gets Converted

bricks.yaml is converted to bricks.json server-side:

# View generated bricks.json
bricks blueprint describe my_blueprint > blueprint.json

All package props and outputs are hydrated automatically.

See also

• Creating Blueprints -- blueprint concepts and web UI wizard

• How to Create Blueprints -- CLI-based blueprint creation

• How to Publish with CLI -- standard CLI publishing workflow

YAML-Specific Best Practices

Use Anchors for Repeated Configuration

Extract common settings to avoid repetition:

common_aws: &aws
  region: us-east-1
  availability_zones: 3

common_tags: &tags
  project: web-app
  managed_by: bluebricks

packages:
  - name: terraform_aws_vpc
    version: 3.0.0
    props:
      <<: *aws
      tags:
        <<: *tags
        component: network

  - name: terraform_aws_rds
    version: 2.1.0
    props:
      <<: *aws
      tags:
        <<: *tags
        component: database

Multi-Document for Environments

Use document separators for environment-specific blueprints:

defaults: &common
  packages:
    - name: terraform_aws_vpc
      version: 3.0.0
    - name: terraform_aws_rds
      version: 2.1.0

---
name: application_dev
version: 1.0.0
<<: *common
inputs:
  environment:
    default: development

---
name: application_prod
version: 1.0.0
<<: *common
inputs:
  environment:
    default: production

Props Merging with Anchors

Use nested anchors to merge props properly:

# Define common props
lambda_props: &common_props
  runtime: inputs.runtime
  timeout: 300

packages:
  - id: api_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: *common_props
      function_name: api-handler

  - id: worker_lambda
    name: terraform_aws_lambda
    version: 1.4.0
    props:
      <<: *common_props
      function_name: worker-handler

Only Specify What Changes

Minimize YAML by relying on auto-populated props:

packages:
  # Package has 20+ props, only override 2
  - name: terraform_aws_rds
    version: 2.1.0
    props:
      vpc_id: data.vpc.vpc_id
      instance_class: inputs.instance_class
      # All other props auto-populated from package