# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/packages/artifacts-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.