Inputs & Outputs

How inputs and outputs define the interface of every package in Bluebricks

Every package in Bluebricks has an interface defined by inputs and outputs. Inputs are the values a package needs to run: a region, a CIDR block, a cluster name, a database password. Outputs are the values a package produces after execution: a VPC ID, an endpoint URL, a connection string.

This interface makes packages composable. One package's output can feed into another package's input, and Bluebricks handles the wiring, ordering, and execution automatically.

This page explains how inputs and outputs work across all layers of Bluebricks, from native IaC code to runtime environments.

The data flow model

Inputs and outputs flow through four layers:

Layer 1: Native IaC code is the infrastructure code you write: Terraform variables, Helm values, CloudFormation parameters, or scripts. This is where inputs and outputs originate.

Layer 2: Artifact is the bricks.json manifest. Its props and outs fields define the package's external interface. Bluebricks auto-discovers these from your native code when you publish.

Layer 3: Blueprint wires packages together. It connects outputs from one package to inputs of another, passes blueprint-level properties down to packages, and references secrets.

Layer 4: Environment + Collection is where Bluebricks resolves values at runtime. Collection properties, secrets, context references, output references, and deployer overrides supply the concrete values.

Inputs

An input is any value a package needs to execute. In bricks.json, inputs are declared in the props object.

How native code maps to inputs

Each IaC tool defines inputs differently at the native level. Bluebricks maps them all to the same props interface:

IaC Tool	Native input construct	Example
Terraform/OpenTofu	variable blocks in .tf files	variable "region" { type = string }
Helm	Keys in values.yaml	replicaCount: 1
CloudFormation	Parameters section in the template	Parameters: VpcCidr: Type: String
Generic	No native construct; props defined in bricks.json only	N/A
Bicep	param declarations	param location string

When you publish an artifact, Bluebricks reads your native code and auto-populates the props section in bricks.json.

How inputs get their values

Inside a blueprint, each package input can receive its value from five sources:

1. Hardcoded value

A fixed value set directly in the blueprint definition:

# UI / YAML
props:
  instance_type: t3.medium

2. Blueprint-level input

A value passed down from the blueprint's own inputs:

# UI / YAML
props:
  region: inputs.region

3. Another package's output

A value produced by a sibling package. This creates a dependency in the execution graph:

# UI / YAML
props:
  vpc_id: data.network_stack.vpc_id

4. Secret

A sensitive value stored in the target collection's secret store:

# UI / YAML
props:
  db_password: secrets.db_password

5. Collection property or context reference

Values that come from the collection or environment at runtime:

• Collection properties: matched by key name. When a blueprint input key matches a collection property name, Bluebricks injects the collection's value automatically

• Context references: dynamic placeholders like ${{bricks.collection.slug}} or ${{bricks.environment.slug}} that resolve at runtime

See Properties, Secrets, and Using Context References.

How inputs are delivered at runtime

Each IaC tool receives inputs through a different mechanism:

IaC Tool	Delivery mechanism	Details
Terraform/OpenTofu	0_bbx_props.auto.tfvars	All props and secrets written to a single auto-vars file. Mark secrets sensitive = true in HCL.
Helm	Merged into Helm values	Props become Helm values; secrets are merged separately and never shown in diffs.
CloudFormation	CloudFormation Parameters	Each prop/secret becomes a ParameterKey/ParameterValue pair. Use NoEcho: true for secrets.
Generic	JSON files + environment variables	Props in /workspace/vars.json. Secrets in /workspace/secrets.json. Both also set as env vars.

Outputs

An output is a value that a package produces after execution. In bricks.json, outputs are declared in the outs object.

How native code maps to outputs

IaC Tool	Native output construct	How Bluebricks captures outputs
Terraform/OpenTofu	output blocks in .tf files	terraform output -json after apply
Helm	No auto-generated outputs (coming soon)	Manually defined in bricks.json
CloudFormation	Outputs section in the template	DescribeStacks API after apply
Generic	/workspace/outputs.json written by your script	File parsed after container exits

Referencing outputs downstream

Once a package produces outputs, other packages in the same blueprint can reference them using Data references:

# UI / YAML syntax
vpc_id: data.network_stack.vpc_id

The reference format is:

Data.<package_id>.<output_key>
  │       │            │
  │       │            └── The output name from the source package's outs
  │       └────────────── The package ID within the blueprint
  └────────────────────── The Data object (runtime output store)

During planning, output values appear as "known after apply" placeholders. After apply, Bluebricks captures and stores the real values.

Cross-environment output references

You can also reference outputs across environments. If a foundational environment (e.g., a shared VPC) produces outputs, dependent environments can consume them. See Using Output References.

Secrets

Secrets are inputs that carry sensitive data: API keys, passwords, tokens. They behave like regular inputs but with additional protections:

• Stored in the collection's secret store, encrypted at rest

• Never shown in logs, diffs, or UI fields

• Injected only at runtime within the secure execution context

• Wiped from the runner after execution completes

In a blueprint, you reference secrets using the Secrets keyword:

# UI / YAML
db_password: secrets.db_password

Each IaC tool delivers secrets through a different mechanism:

IaC Tool	How secrets are delivered	Best practice
Terraform/OpenTofu	Included in 0_bbx_props.auto.tfvars	Mark variables sensitive = true in HCL
Helm	Merged into values separately from props	Never shown in rendered diffs
CloudFormation	Passed as Parameters	Use NoEcho: true in template
Generic	Written to /workspace/secrets.json (0600 permissions) + set as env vars	Never print(os.environ)

See Secrets for how to create and manage secrets at the collection level.

Package-to-package wiring

When one package's input references another package's output via a Data reference, Bluebricks creates an implicit dependency between them. These dependencies form a directed acyclic graph (DAG) that determines execution order.

In this example:

• Subnet depends on VPC because its vpc_id input references Data.vpc.vpc_id

• App Server depends on Subnet because it references Data.subnet.subnet_id

Bluebricks resolves this graph at plan time and executes packages in the correct order: parallel where there are no dependencies, sequential where one package needs another's output.

The Data reference is an expr expression, so you can manipulate values. For example, select the first subnet from a list with data.vpc.private_subnets[0], or use a fallback with data.vpc.vpc_id ?? inputs.fallback_vpc_id.

Syntax quick reference

Bluebricks uses two equivalent syntaxes depending on context:

Concept	bricks.json syntax	UI / YAML syntax
Blueprint-level input	Props.region	inputs.region
Package output reference	Data.pkg_id.output_key	data.pkg_id.output_key
Secret reference	Secrets.db_password	secrets.db_password
Hardcoded string	"'us-east-1'"	us-east-1
Hardcoded number	14	14

Both syntaxes are expr expressions. The capitalized form (Props, Data, Secrets) appears in bricks.json. The lowercase form (inputs, data, secrets) appears in the UI and YAML configurations.

End-to-end example

This example shows a blueprint with two packages: a Terraform VPC and a Helm application. The VPC output flows into the Helm chart input, and secrets are pulled from the collection.

Blueprint YAML (UI-generated):

name: webapp_stack
version: 1.0.0
description: Deploys networking and a web application

inputs:
  region:
    type: string
    allowed_values:
      - us-east-1
      - eu-west-1
  cluster_name:
    type: string

packages:
  - name: vpc
    version: 2.1.0
    props:
      region: inputs.region
      cidr_block: 10.0.0.0/16

  - name: webapp
    version: 1.3.0
    props:
      cluster_name: inputs.cluster_name
      vpc_id: data.vpc.vpc_id
      subnet_ids: data.vpc.private_subnet_ids
      db_password: secrets.db_password

outputs:
  vpc_id:
    value: data.vpc.vpc_id
  app_endpoint:
    value: data.webapp.endpoint

What happens at runtime:

1. Bluebricks resolves the DAG: vpc has no dependencies, webapp depends on vpc

2. The vpc package runs first. Inputs region and cidr_block are delivered via 0_bbx_props.auto.tfvars.

3. After vpc completes, Bluebricks captures its outputs (vpc_id, private_subnet_ids) via terraform output -json.

4. The webapp package runs next. Its inputs include the VPC outputs (resolved from Data.vpc.*) and the secret db_password (resolved from the collection's secret store).

5. The blueprint's outputs are populated and available to dependent environments.