Blueprint Composition Patterns

Common patterns for composing blueprints, managing package dependencies, and structuring outputs effectively.

Overview

Blueprints compose multiple packages into deployable infrastructure stacks. This page covers proven patterns for structuring those compositions, managing dependencies between packages, and controlling outputs.

For the basics of creating blueprints, see Creating Blueprints. For dynamic expressions within blueprints, see Using expr.

Composition patterns

Layered architecture

Stack packages in layers: infrastructure, platform, then application. Each layer depends on the one below it.

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_vpc",
      "id": "infrastructure_vpc"
    },
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "infrastructure_subnet",
      "props": {
        "vpc_id": {
          "value": "Data.infrastructure_vpc.vpc_id"
        }
      }
    },
    {
      "name": "@bluebricks/helm_nginx",
      "id": "platform_nginx",
      "props": {
        "cluster_name": {
          "value": "Data.infrastructure_subnet.cluster_name"
        }
      }
    },
    {
      "name": "@bluebricks/helm_myapp",
      "id": "application_myapp",
      "props": {
        "nginx_endpoint": {
          "value": "Data.platform_nginx.endpoint"
        }
      }
    }
  ]
}

This gives you clear separation of concerns, predictable dependency flow, and easy maintenance.

Hub and spoke

A central package provides shared resources to multiple consumers.

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_vpc",
      "id": "hub_vpc"
    },
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "spoke_web",
      "props": {
        "vpc_id": { "value": "Data.hub_vpc.vpc_id" }
      }
    },
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "spoke_db",
      "props": {
        "vpc_id": { "value": "Data.hub_vpc.vpc_id" }
      }
    },
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "spoke_cache",
      "props": {
        "vpc_id": { "value": "Data.hub_vpc.vpc_id" }
      }
    }
  ]
}

Spoke packages run in parallel since they share the same dependency. This pattern works well for shared networking, centralized databases, or common security groups.

Microservices composition

Each service is a separate package with shared infrastructure dependencies.

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_vpc",
      "id": "shared_vpc"
    },
    {
      "name": "@bluebricks/helm_user_service",
      "id": "user_service",
      "props": {
        "vpc_id": { "value": "Data.shared_vpc.vpc_id" }
      }
    },
    {
      "name": "@bluebricks/helm_order_service",
      "id": "order_service",
      "props": {
        "vpc_id": { "value": "Data.shared_vpc.vpc_id" },
        "user_service_url": { "value": "Data.user_service.endpoint" }
      }
    },
    {
      "name": "@bluebricks/helm_payment_service",
      "id": "payment_service",
      "props": {
        "vpc_id": { "value": "Data.shared_vpc.vpc_id" },
        "order_service_url": { "value": "Data.order_service.endpoint" }
      }
    }
  ]
}

Services with no cross-dependency run in parallel. Services that consume another service's output run after their dependency completes.

Environment-specific composition

Use blueprint inputs to configure the same blueprint differently per collection.

{
  "props": {
    "environment": {
      "type": "string",
      "description": "Environment name"
    },
    "instance_count": {
      "type": "number",
      "description": "Number of instances"
    }
  },
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_instance",
      "id": "web_instances",
      "props": {
        "count": { "value": "Props.instance_count" },
        "environment": { "value": "Props.environment" }
      }
    }
  ]
}

Install the same blueprint into different collections with different values:

# Development collection
bricks install my_blueprint --collection dev --props '{"environment":"dev","instance_count":1}'

# Production collection
bricks install my_blueprint --collection prod --props '{"environment":"prod","instance_count":3}'

Dependency management patterns

Explicit dependencies with version pinning

Pin specific package versions for stability and reproducibility.

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_vpc",
      "id": "vpc",
      "version": "1.2.0"
    },
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "subnet",
      "version": "1.1.0",
      "props": {
        "vpc_id": { "value": "Data.vpc.vpc_id" }
      }
    }
  ]
}

Conditional dependencies

Use expressions to control package behavior based on configuration. For a full reference on expression syntax, see Using expr.

{
  "props": {
    "enable_monitoring": {
      "type": "bool",
      "default": true
    }
  },
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_instance",
      "id": "web_server"
    },
    {
      "name": "@bluebricks/helm_prometheus",
      "id": "monitoring",
      "props": {
        "target_instance": { "value": "Data.web_server.private_ip" },
        "enabled": { "value": "Props.enable_monitoring" }
      }
    }
  ]
}

Output management patterns

Aggregated outputs

Combine outputs from multiple packages into a single blueprint output.

{
  "outs": {
    "web_endpoints": {
      "value": "Data.web_server.endpoint + ',' + Data.api_server.endpoint",
      "type": "string",
      "description": "All web endpoints"
    },
    "database_info": {
      "value": "Data.database.connection_string",
      "type": "string",
      "description": "Database connection"
    }
  }
}

Conditional outputs

Bluebricks only executes components whose outputs are actually needed. Use conditional outputs to control which packages run.

{
  "outs": {
    "monitoring_url": {
      "value": "Props.enable_monitoring ? Data.monitoring.url : 'Monitoring disabled'",
      "type": "string",
      "description": "Monitoring dashboard URL"
    }
  }
}

If enable_monitoring is false, the monitoring component is not executed. This follows Bluebricks' output-driven execution model: props flow down, data flows up based on actual requirements.

Structured outputs

Organize outputs into logical groups for clarity.

{
  "outs": {
    "infrastructure": {
      "value": "Data.vpc.vpc_id",
      "type": "string",
      "description": "VPC ID"
    },
    "application": {
      "value": "Data.web_app.url",
      "type": "string",
      "description": "Application URL"
    },
    "monitoring": {
      "value": "Data.monitoring.dashboard_url",
      "type": "string",
      "description": "Monitoring dashboard"
    }
  }
}

Best practices

• Choose packages that complement each other and verify compatibility

• Minimize dependencies and avoid circular references

• Use clear, descriptive naming conventions for package IDs

• Provide sensible defaults for blueprint inputs

• Test blueprint composition locally before publishing

• Pin package versions for production blueprints

Anti-patterns to avoid

Circular dependencies

// BAD: Circular dependency
{
  "packages": [
    {
      "name": "package_a",
      "props": { "value": "Data.package_b.output" }
    },
    {
      "name": "package_b",
      "props": { "value": "Data.package_a.output" }
    }
  ]
}

Deep dependency chains

// BAD: Long sequential chain prevents parallelism
{
  "packages": [
    {"name": "pkg1"},
    {"name": "pkg2", "props": {"dep": "Data.pkg1.out"}},
    {"name": "pkg3", "props": {"dep": "Data.pkg2.out"}},
    {"name": "pkg4", "props": {"dep": "Data.pkg3.out"}},
    {"name": "pkg5", "props": {"dep": "Data.pkg4.out"}}
  ]
}

Prefer hub-and-spoke or layered patterns to maximize parallel execution.

Unclear output references

// BAD: Ambiguous reference
{
  "outs": {
    "result": {
      "value": "Data.pkg.out",
      "type": "string"
    }
  }
}

Use descriptive output names that indicate what the value represents.

See also

• Creating Blueprints: step-by-step guide for the UI wizard and CLI

• Using expr: expression language for dynamic configuration

• Parallel Execution: how Bluebricks resolves the DAG and runs packages in parallel