Create a CloudFormation Artifact

Convert existing AWS CloudFormation templates into Bluebricks packages.

Prerequisites

• Bluebricks CLI installed

• Authenticated with Bluebricks (bricks login)

• Existing CloudFormation template (JSON format)

• AWS account with appropriate IAM permissions

Quick Start

1. Prepare your CloudFormation template:

   • Must be named bluebricks.json

   • Must be in JSON format (YAML not supported)

2. Run blueprint prepare:

   # Option 1: In-place (keeps original files)
   bricks blueprint prepare --source . --iac-type cloudformation
   
   # Option 2: With output directory (copies files to src/cloudformation/)
   bricks blueprint prepare --source . --output ./dist --iac-type cloudformation

3. Verify the generated package:

   ls -la
   # In-place: Shows bricks.json + original files
   # With output: Shows bricks.json + src/cloudformation/ directory

4. Publish the package:

   bricks blueprint publish

That's it! Your CloudFormation template is now a Bluebricks package ready for deployment.

Template Requirements

File naming:

• Template must be named exactly bluebricks.json

• Must be in JSON format (not YAML)

File handling:

• Files are copied to src/cloudformation/ when using the --output flag

• In-place preparation keeps files in their original location

Example structure:

my-cloudformation/
└── bluebricks.json    # Your CloudFormation template

Example bluebricks.json:

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "VPC infrastructure",
  "Parameters": {
    "VpcCidr": {
      "Type": "String",
      "Default": "10.0.0.0/16",
      "Description": "CIDR block for the VPC"
    },
    "Environment": {
      "Type": "String",
      "Default": "development",
      "Description": "Environment name"
    }
  },
  "Resources": {
    "VPC": {
      "Type": "AWS::EC2::VPC",
      "Properties": {
        "CidrBlock": { "Ref": "VpcCidr" },
        "EnableDnsHostnames": true,
        "Tags": [
          {
            "Key": "Name",
            "Value": { "Fn::Sub": "${Environment}-vpc" }
          }
        ]
      }
    }
  },
  "Outputs": {
    "VpcId": {
      "Description": "ID of the VPC",
      "Value": { "Ref": "VPC" }
    }
  }
}

What Happens

Bluebricks automatically:

• Analyzes your CloudFormation template

• Extracts Parameters and maps them to props

• Extracts Outputs and maps them to outs

• Generates optimized bricks.json

• Copies template to src/cloudformation/ when using the --output flag

Generated Package Structure

After preparation (in-place):

my-cloudformation/
├── bricks.json           # Generated metadata
└── bluebricks.json       # Original template remains

After preparation (with output directory):

my-cloudformation/
├── bricks.json           # Generated metadata
└── src/
    └── cloudformation/    # Your template (copied)
        └── bluebricks.json

Example generated bricks.json:

{
  "name": "vpc-infrastructure",
  "version": "0.1.0",
  "description": "VPC infrastructure",
  "native": {
    "type": "cloudformation",
    "path": "./src/cloudformation"
  },
  "props": {
    "VpcCidr": {
      "type": "string",
      "default": "10.0.0.0/16",
      "description": "CIDR block for the VPC"
    },
    "Environment": {
      "type": "string",
      "default": "development",
      "description": "Environment name"
    },
    "cf_stack_name": {
      "type": "string",
      "description": "Optional name for the CloudFormation stack"
    }
  },
  "outs": {
    "VpcId": {
      "type": "string",
      "description": "ID of the VPC"
    }
  }
}

Test Your Package

# Dry run (plan only)
bricks run . --dry --props-file properties.json

# Apply to AWS
bricks run . --apply --props-file properties.json

See also

• How to Connect AWS -- connect your AWS account to Bluebricks

• Packages overview -- artifact types and packaging concepts

• How to Create Blueprints -- compose artifacts into blueprints