Publish a Terraform Module

Convert an existing Terraform module into a Bluebricks package using the prepare and publish CLI workflow

Overview

Convert your existing Terraform module into a Bluebricks package in two steps: prepare locally, then publish to your organization.

Prerequisites

Bricks CLI installed and authenticated (bricks login)
Existing Terraform module with .tf files

How to publish a Terraform module

Prepare your module

Navigate to your Terraform directory and run:

cd /path/to/your-terraform-module
bricks blueprint prepare --source . --iac-type terraform

This creates a bricks.json with auto-detected variables and outputs. Your original .tf files remain in place.

Publish to your organization

bricks blueprint publish

Your module is now available to your organization.

What each command does

bricks blueprint prepare generates a bricks.json in your current directory. No files are moved or copied, and no API calls are made. Your .tf files stay exactly where they are.

bricks blueprint publish uploads your package to Bluebricks. Variables and outputs are auto-discovered from your .tf files, external module references are resolved (if --resolve-modules is enabled), and the package is made available to your organization.

Working with existing modules

Local module references

If your Terraform uses local modules:

module "vpc" {
  source = "../networking/vpc"
}

module "subnets" {
  source = "../networking/subnets"
}

Bluebricks automatically handles this with --resolve-modules (enabled by default):

bricks blueprint publish --resolve-modules

What happens:

Finds all modules referenced with ../
Copies them to bricks_modules/ directory
Updates references to point to ./bricks_modules/
Includes everything in the published package

Your module becomes self-contained and portable.

Disable module resolution

If you don't want to include external modules:

bricks blueprint publish --resolve-modules=false

Bluebricks warns you about external references but won't include them.

Terraform version

Default version: 1.5.7

Specify a different version in bricks.json:

{
  "native": {
    "type": "terraform",
    "path": ".",
    "version": "1.6.5"
  }
}

For the full version limits table and examples, see version pinning.

State management

Bluebricks automatically manages state using its built-in HTTP backend. Do not include backend.tf or backend configuration blocks in your Terraform code.

For details on managed state, locking, and encryption, see Terraform/OpenTofu.

To work locally with remote state for debugging or development, see Develop Terraform Locally.

Publishing with existing state

If you're migrating existing Terraform infrastructure, include your state file:

bricks blueprint publish --state

Requirements:

Place terraform.tfstate in your Terraform directory
Bluebricks packages it with your module
State is stored securely in Bluebricks

Variables and outputs mapping

Variables and outputs are auto-discovered during publish. Bluebricks parses your variables.tf and outputs.tf, then converts them to props and outs in bricks.json. See Terraform/OpenTofu inputs and outputs for the full mapping details and examples.

Examples

Publishing a VPC module

vpc_module/
├── main.tf
├── variables.tf
├── outputs.tf
└── versions.tf

cd vpc_module
bricks blueprint prepare --source . --iac-type terraform
bricks blueprint publish

Publishing with local modules

my-infrastructure/
├── main.tf              # References ../common/networking
├── variables.tf
└── outputs.tf

../common/networking/
├── vpc.tf
├── subnets.tf
└── outputs.tf

cd my-infrastructure
bricks blueprint prepare --source . --iac-type terraform
bricks blueprint publish

Bluebricks automatically detects ../common/networking, copies it to bricks_modules/common/networking/, updates your references, and packages everything together. Your published module is now self-contained.

Migrating existing infrastructure

cd production-vpc
terraform show  # Verify state exists

# Publish with state
bricks blueprint prepare --source . --iac-type terraform
bricks blueprint publish --state

Bluebricks stores your state securely, enables locking to prevent conflicts, and provides a full audit trail.

Common options

Prepare options

bricks blueprint prepare \
  --source ./terraform \
  --iac-type terraform \
  --output ./my-package \
  --package-name my-vpc

--source: Path to Terraform directory
--iac-type: Must be terraform
--output: Where to create package (default: current directory)
--package-name: Custom package name (default: directory name)
--refactor: Create bricks.json without moving files

Publish options

bricks blueprint publish \
  --src ./my-package \
  --resolve-modules=true \
  --state

--src: Package directory (default: current directory)
--resolve-modules: Include external modules (default: true)
--state: Include terraform.tfstate file

Generated package structure

After prepare

my-package/
├── bricks.json          # Package metadata
└── src/
    └── terraform/       # Your .tf files
        ├── main.tf
        ├── variables.tf
        ├── outputs.tf
        └── versions.tf

After publish with --resolve-modules

my-package/
├── bricks.json
└── src/
    └── terraform/
        ├── main.tf
        ├── variables.tf
        ├── outputs.tf
        ├── versions.tf
        └── bricks_modules/     # External modules copied here
            └── common/
                └── networking/
                    ├── vpc.tf
                    └── outputs.tf

Best practices

Test locally before publishing
Use --resolve-modules for portability
Include state with --state when migrating existing infrastructure
Version your packages with semantic versioning