Creating IaC Packages

Overview

Artifacts are the foundational building blocks in Bluebricks. They package native infrastructure code (Terraform, OpenTofu, Helm, or CloudFormation) or generic execution units (Docker images with custom scripts, Pulumi, Ansible, etc.) into reusable units with a defined interface. Unlike blueprints, which compose multiple artifacts, each artifact represents a self-contained abstraction for a specific resource or capability.

Your code

There are three main characteristics that define an artifact:

• Native Infrastructure Code: Terraform, OpenTofu, Helm, CloudFormation or Bicep code

• Self-contained Logic: Code that you run independently with its native tool (e.g. terraform init/plan/apply, helm install, etc.)

For Terraform or OpenTofu, this means the root module you would normally navigate into and run directly.

• Keep DRY: Use variables for configurable values (e.g., CIDR blocks, regions) that can be managed through Bluebricks, or hard-coded only for values the never change (e.g., fixed tags, account IDs).

Create an artifact

You can create an artifact in two ways: by connecting your repository to Bluebricks and pointing to the directory that contains your code, or by using the CLI publish command.

Connecting your Repository

1. Open Bluebricks web application

2. Go to the Artifacts page (https://app.bluebricks.co/packages?tab=artifact)

3. Click Create Artifact button on the top right

4. Select your Git Provider and Install Bluebricks Syncer to your organization

1. Fill in the information on the side drawer

1. Click the "Create" button

2. After a short loading the page will refresh and you should see the artifact within the table

Best Practices for Artifacts

1. Single Responsibility

Each artifact should have a clear, single purpose:

• ✅ aws_vpc - Creates a VPC with subnets

• ✅ kubernetes_namespace - Creates a K8s namespace with RBAC

• ❌ web_app_stack - Too broad, should be broken down

2. Input Design and Flexibility

✅ Good Practices:

• Use variables for flexibility and reuse

• Validate inputs with type constraints and defaults

• Provide sensible defaults for optional properties

❌ Bad Practices:

• Hard-coding inputs limits configurability

• Relying on external data that may not exist

• Mixing environment-specific details inside artifacts

A typical artifact directory structure:

my_s3_artifact/
├── bricks.json              # Artifact definition
├── terraform/               # Native infrastructure code (or helm/, cloudformation/, etc.)
│   ├── main.tf              # Infrastructure definitions
│   ├── variables.tf         # Input variables
│   ├── outputs.tf           # Output values
│   └── versions.tf          # Provider versions
├── README.md                # Documentation
└── examples/                # Usage examples
    └── basic/
        └── bricks.json