CloudFormation

CloudFormation reference: parameter mapping, outputs capture, and AWS authentication

Overview

CloudFormation artifacts let you manage AWS infrastructure using native CloudFormation templates while taking advantage of Bluebricks' orchestration, collection management, and environment automation. You define AWS resources declaratively in JSON or YAML, then deploy and track those changes reliably across collections.

Feature	Details
Template-driven	Supports bluebricks.json or bluebricks.yaml templates
Change-set plan	Plan creates a Change Set that previews adds/updates/deletes without altering resources
Stack apply	Executes the Change Set, waits for stack completion, captures outputs
Outputs capture	Template Outputs become artifact outputs for downstream packages
State-free	CloudFormation stores state, so you don't need backend configuration

For a complete guide to how inputs and outputs work across all IaC tools, see Inputs & Outputs.

Required files and directory structure

A CloudFormation artifact requires a template file named bluebricks.json or bluebricks.yaml:

my-cfn-artifact/
├── bricks.json                    # Artifact manifest
└── template/
    └── bluebricks.json            # CloudFormation template (required name)

The CloudFormation template must be named bluebricks.json or bluebricks.yaml. Other file names are not recognized.

The native.path field in bricks.json points to the template file itself (not the directory).

Example template

A simple VPC template (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" }
    }
  }
}

bricks.json reference

Field	Required	Description
type	Yes	"cloudformation"
path	Yes	Path to the CloudFormation template file (must be bluebricks.json or bluebricks.yaml)
stack_name	No	Custom stack name. Defaults to a sanitized version of the artifact name.

Example bricks.json

{
  "name": "vpc-infrastructure",
  "version": "0.1.0",
  "description": "VPC infrastructure",
  "native": {
    "type": "cloudformation",
    "path": "./template/bluebricks.json"
  },
  "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"
    }
  }
}

How to create this artifact

The only requirement is a CloudFormation template named bluebricks.json or bluebricks.yaml. Point Bluebricks at your template and it handles parameter mapping, change-set workflows, and output capture for you.

You can create a CloudFormation artifact in two ways:

• In the Bluebricks app during blueprint creation: select your repository and the directory containing your template, and Bluebricks generates the artifact automatically

• Via CLI: run bricks blueprint publish from the directory containing your template. See Creating Artifacts for the full workflow

You can also scaffold the bricks.json manifest automatically using the prepare command:

# In-place (keeps original files)
bricks blueprint prepare --source . --iac-type cloudformation

# With output directory (copies files to a separate folder)
bricks blueprint prepare --source . --output ./dist --iac-type cloudformation

The prepare command analyzes your template, extracts Parameters as props and Outputs as outs, and generates a bricks.json manifest.

Test locally

Before publishing, verify the artifact works with a local dry run:

# Plan only (creates a Change Set without applying)
bricks run . --dry

# Apply to AWS
bricks run . --apply

---

The sections below explain how Bluebricks maps your code to inputs, outputs, and operations under the hood. Everything here is optional reading. To get started, head to Creating Blueprints.

Inputs

What becomes an input

CloudFormation Parameters in your template map to props in bricks.json:

Parameters:
  VpcCidr:
    Type: String
    Default: "10.0.0.0/16"
  Environment:
    Type: String

How inputs are delivered at runtime

Blueprint props and secrets map directly to CloudFormation Parameters:

Blueprint field	Parameter example
Prop Environment = "prod"	{ "ParameterKey": "Environment", "ParameterValue": "prod" }
Secret DbPassword	{ "ParameterKey": "DbPassword", "ParameterValue": "" }

Use NoEcho: true on sensitive parameters in your template to hide them from the AWS console.

Outputs

What becomes an output

CloudFormation template Outputs map to outs in bricks.json:

Outputs:
  VpcId:
    Description: ID of the created VPC
    Value: !Ref VPC
  PrivateSubnetIds:
    Value: !Join [ ",", [ !Ref SubnetA, !Ref SubnetB ] ]

How outputs are captured

After a successful apply, Bluebricks calls DescribeStacks to retrieve all stack outputs. During planning, output keys appear as placeholders until apply sets real values.

Referencing outputs downstream

In a blueprint, reference a CloudFormation output from another package using Data.network_stack.VpcId or Data.network_stack.PrivateSubnetIds.

Supported operations

CloudFormation artifacts use Change Sets for safe, predictable deployments:

Operation	What happens	Notes
Plan	Creates a Change Set (bbx-plan-), waits for creation, then describes it to build a JSON plan	If the stack does not exist yet, the Change Set type is CREATE
Apply	Executes the pending Change Set (or creates the stack on first run) and waits for Complete status	If the stack is in a blocked state like UPDATE_ROLLBACK_FAILED, the deploy is halted
Plan Destroy	Creates a DELETE Change Set listing every resource that will be removed	Output list is empty
Apply Destroy	Deletes the stack and waits for DeleteComplete; outputs and state are cleared	Only one Change Set per deploy prevents concurrent modifications

Best practices

• Keep templates focused: one stack per artifact; compose multiple stacks with exports if needed

• Use Parameters for environment-specific data; avoid hard-coding ARNs or IDs

• Tag resources in the template's Tags section for cost and compliance reporting

• Use DeletionPolicy: Retain on data resources if you don't want them deleted with the stack

• Mark sensitive outputs appropriately or avoid emitting secrets via Outputs