# Inputs & Outputs 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 ToolNative input constructExample
Terraform/OpenTofuvariable blocks in .tf filesvariable "region" { type = string }
HelmKeys in values.yamlreplicaCount: 1
CloudFormationParameters section in the templateParameters: VpcCidr: Type: String
GenericNo native construct; props defined in bricks.json onlyN/A
Bicepparam declarationsparam 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: ```yaml # UI / YAML props: instance_type: t3.medium ``` #### 2. Blueprint-level input A value passed down from the blueprint's own inputs: ```yaml # 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: ```yaml # UI / YAML props: vpc_id: data.network_stack.vpc_id ``` #### 4. Secret A sensitive value stored in the target collection's secret store: ```yaml # 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](https://bluebricks.co/docs/core-concepts/collections/properties), [Secrets](https://bluebricks.co/docs/core-concepts/collections/secrets), and [Using Context References](https://github.com/bluebricks-dev/Bluebricks-Documentation/blob/main/core-concepts/deployments/using-context-references.md). ### How inputs are delivered at runtime Each IaC tool receives inputs through a different mechanism:
IaC ToolDelivery mechanismDetails
Terraform/OpenTofu0_bbx_props.auto.tfvarsAll props and secrets written to a single auto-vars file. Mark secrets sensitive = true in HCL.
HelmMerged into Helm valuesProps become Helm values; secrets are merged separately and never shown in diffs.
CloudFormationCloudFormation ParametersEach prop/secret becomes a ParameterKey/ParameterValue pair. Use NoEcho: true for secrets.
GenericJSON files + environment variablesProps 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 ToolNative output constructHow Bluebricks captures outputs
Terraform/OpenTofuoutput blocks in .tf filesterraform output -json after apply
HelmNo auto-generated outputs (coming soon)Manually defined in bricks.json
CloudFormationOutputs section in the templateDescribeStacks API after apply
Generic/workspace/outputs.json written by your scriptFile parsed after container exits
### Referencing outputs downstream Once a package produces outputs, other packages in the same blueprint can reference them using `Data` references: ```yaml # UI / YAML syntax vpc_id: data.network_stack.vpc_id ``` The reference format is: ``` Data.. │ │ │ │ │ └── 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](https://github.com/bluebricks-dev/Bluebricks-Documentation/blob/main/core-concepts/deployments/using-outputs-references.md). ## 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: ```yaml # UI / YAML db_password: secrets.db_password ``` Each IaC tool delivers secrets through a different mechanism:
IaC ToolHow secrets are deliveredBest practice
Terraform/OpenTofuIncluded in 0_bbx_props.auto.tfvarsMark variables sensitive = true in HCL
HelmMerged into values separately from propsNever shown in rendered diffs
CloudFormationPassed as ParametersUse NoEcho: true in template
GenericWritten to /workspace/secrets.json (0600 permissions) + set as env varsNever print(os.environ)
See [Secrets](https://bluebricks.co/docs/core-concepts/collections/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. {% @mermaid/diagram content="flowchart LR VPC\["VPC
outs: vpc\_id"] -- "Data ref" --> Subnet\["Subnet
outs: subnet\_id"] -- "Data ref" --> App\["App Server"]" %} 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](https://expr-lang.org/) 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:
Conceptbricks.json syntaxUI / YAML syntax
Blueprint-level inputProps.regioninputs.region
Package output referenceData.pkg_id.output_keydata.pkg_id.output_key
Secret referenceSecrets.db_passwordsecrets.db_password
Hardcoded string"'us-east-1'"us-east-1
Hardcoded number1414
Both syntaxes are [expr](https://expr-lang.org/) 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):** ```yaml 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.