> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/packages/artifacts-overview.md).

# Artifacts

You already have infrastructure code: Terraform modules, Helm charts, CloudFormation templates. Artifacts are how that code becomes standardized, versioned building blocks that others can discover and reuse without needing to read the source.

Artifacts wrap a single IaC component with a thin metadata layer (`bricks.json`) that declares the component's inputs, outputs, and native tooling. Your code stays untouched. Bluebricks reads the metadata, catalogs the artifact, and makes it available for composition into [blueprints](/docs/orchestration/packages/blueprints-overview.md).

## What an artifact contains

Every artifact has two parts: the IaC code you already wrote, and a `bricks.json` file that describes it.

The metadata defines:

* **Name and version**: a unique identifier and a semantic version (MAJOR.MINOR.PATCH). Every published version is immutable.
* **Inputs (props)**: the variables your component accepts. These become the interface that blueprint builders wire values into.
* **Outputs (outs)**: the values your component produces after execution, such as resource IDs, endpoints, or connection strings. Blueprints can pass these as inputs to other packages.
* **Native technology**: which IaC tool runs the code (Terraform, Helm, CloudFormation, Bicep, or Generic).

The artifact itself doesn't change how your code works. If you can run `terraform plan` or `helm install` against it today, it will work the same way inside Bluebricks.

<details>

<summary>Example: bricks.json for a Terraform artifact</summary>

```jsonc
{
  "name": "aws_vpc",                       // Unique artifact name (underscores, not hyphens)
  "description": "Creates a VPC with public and private subnets",
  "version": "1.2.0",                      // Semantic version (immutable once published)
  "native": {
    "type": "terraform",                   // IaC tool: terraform | opentofu | helm | cloudformation | bicep | generic
    "path": "."                            // Path to the IaC code relative to bricks.json
  }
  // Inputs (props) and outputs (outs) are auto-detected from variables.tf and outputs.tf
  // for Terraform/OpenTofu artifacts. Other types declare them explicitly.
}
```

A typical artifact repository:

```
aws_vpc/
├── bricks.json          # Artifact metadata
├── main.tf              # Infrastructure definitions
├── variables.tf         # Input variables → become artifact props
├── outputs.tf           # Output values → become artifact outs
└── versions.tf          # Provider versions
```

</details>

## Supported IaC types

Artifacts support six IaC technologies:

* **Terraform / OpenTofu**: root modules with standard `variables.tf` and `outputs.tf` files
* **Helm**: Helm charts with `values.yaml` inputs
* **CloudFormation**: templates with parameters and outputs
* **Bicep**: Bicep files with parameters
* **Generic**: container-based execution for anything that doesn't fit the above categories

Each type maps its native input/output conventions to the artifact's props and outs, so blueprint builders get a consistent interface regardless of the underlying tool.

## How artifacts fit into blueprints

An artifact is not directly deployable. It represents a single component, not a complete stack.

To deploy infrastructure, you compose one or more artifacts into a [blueprint](/docs/orchestration/packages/blueprints-overview.md). The blueprint wires their inputs and outputs together, sets defaults, and exposes only the properties a deployer needs to provide. Bluebricks resolves the dependency order and runs each artifact's native tool in sequence.

This separation keeps artifacts focused and reusable. A single `aws_vpc` artifact can appear in a networking blueprint, a full-stack application blueprint, and a sandbox blueprint, each wiring it differently without duplicating code.