Publish a Terraform Module

Convert your existing Terraform module into a Bluebricks package in 3 simple steps.

Prerequisites

• Bluebricks CLI installed

• Authenticated (bricks login)

• Existing Terraform module with .tf files

Quick Start

You have a Terraform module. Let's publish it.

Step 1: Prepare

Navigate to your Terraform directory and run:

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

This creates:

• bricks.json with auto-detected variables and outputs

• Original .tf files remain in place (no copying by default)

Step 2: Publish

bricks blueprint publish

Done. Your module is now available to your organization.

What Just Happened?

Prepare Command

bricks blueprint prepare creates a basic package structure locally:

1. Creates bricks.json with minimal metadata:

   • native.type: "terraform"

   • native.path: "." (current directory, no copying)

   • Package name and version

2. Keeps your .tf files in place (no copying by default)

That's it - no API calls, no parsing yet. Just a flat structure.

Publish Command

bricks blueprint publish is where the magic happens:

1. Creates a zip archive of your package

2. Resolves external module references (if --resolve-modules enabled)

3. Uploads to Bluebricks platform (POST /v1/package)

4. Bluebricks control plane enriches the metadata:

   • Parses variables.tf → converts to props in bricks.json

   • Parses outputs.tf → converts to outs in bricks.json

   • Detects provider requirements and dependencies

   • Validates Terraform syntax

5. Stores enriched package with full metadata

6. Makes it available to your organization

The Bluebricks control plane does the heavy lifting - parsing, validation, and enrichment all happen during publish.

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:

1. Finds all modules referenced with ../

2. Copies them to bricks_modules/ directory

3. Updates references to point to ./bricks_modules/

4. 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 will warn 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"
  }
}

State Management

Important: No backend.tf Required

Bluebricks automatically manages state using its built-in HTTP backend.

Do not include backend.tf or backend configuration blocks in your Terraform code.

If your Terraform includes backend configuration:

# Remove this - not needed
terraform {
  backend "s3" {
    bucket = "my-state-bucket"
    key    = "terraform.tfstate"
  }
}

Simply remove the entire backend block. Bluebricks handles state storage, locking, and versioning automatically.

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

State in Bluebricks

When you run a Bluebricks package:

1. Plan: Bluebricks downloads current state, runs terraform plan

2. Apply: Runs terraform apply, captures new state

3. Store: Uploads state to Bluebricks (HTTP backend)

4. Lock: Uses locking to prevent concurrent modifications

State is automatically managed - you don't need to configure remote backends.

Example: Publishing a VPC Module

You have a VPC module:

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

Publish it:

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

Use it:

bricks run vpc_module --props-file properties.json --dry
bricks run vpc_module --props-file properties.json --apply

Example: Publishing with Local Modules

Your module references other local modules:

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

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

Publish it:

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

Bluebricks automatically:

• Detects ../common/networking reference

• Copies networking module to bricks_modules/common/networking/

• Updates your main.tf to use ./bricks_modules/common/networking

• Packages everything together

Your published module is now self-contained.

Example: Migrating Existing Infrastructure

You have live infrastructure managed by Terraform:

cd production-vpc
terraform show  # Verify state exists

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

Now Bluebricks manages your infrastructure:

• State is stored in Bluebricks

• Locking prevents conflicts

• Full history and audit trail

• Team collaboration enabled

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

Variables and Outputs Mapping

How Variables Become Props

Your variables.tf:

variable "vpc_cidr" {
  type        = string
  default     = "10.0.0.0/16"
  description = "VPC CIDR block"
}

variable "enable_nat" {
  type        = bool
  default     = true
  description = "Enable NAT gateway"
}

variable "availability_zones" {
  type        = list(string)
  description = "AZ list"
}

Becomes props in bricks.json:

{
  "props": {
    "vpc_cidr": {
      "type": "string",
      "default": "10.0.0.0/16",
      "description": "VPC CIDR block"
    },
    "enable_nat": {
      "type": "bool",
      "default": true,
      "description": "Enable NAT gateway"
    },
    "availability_zones": {
      "type": "list",
      "description": "AZ list"
    }
  }
}

Override with properties.json:

{
  "vpc_cidr": "10.10.0.0/16",
  "enable_nat": false,
  "availability_zones": ["us-east-1a", "us-east-1b"]
}

How Outputs Become Outs

Your outputs.tf:

output "vpc_id" {
  value       = aws_vpc.main.id
  description = "VPC ID"
}

output "subnet_ids" {
  value       = aws_subnet.private[*].id
  description = "Private subnet IDs"
}

Becomes outs in bricks.json:

{
  "outs": {
    "vpc_id": {
      "type": "string",
      "description": "VPC ID"
    },
    "subnet_ids": {
      "type": "list",
      "description": "Private subnet IDs"
    }
  }
}

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

Module Design:

• Keep modules focused and reusable

• Define all variables in variables.tf

• Document all outputs in outputs.tf

• Use semantic versioning

Publishing:

• Test locally before publishing

• Use --resolve-modules for portability

• Include state for migrations

• Version your packages properly

State Management:

• Let Bluebricks manage state (don't configure remote backends)

• Use --state when migrating existing infrastructure

• Bluebricks handles locking automatically

Variables:

• Provide defaults for optional variables

• Use clear descriptions

• Use proper types (string, number, bool, list, map)

See also

• How to Set Terraform/OpenTofu Version -- pin a specific engine version

• How to Work Locally with Remote State -- download state config for local debugging

• Creating Blueprints -- compose artifacts into blueprints

• Packages overview -- artifact types and packaging concepts