Blueprint Composition Patterns

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

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: terraform_aws_vpc
    id: infrastructure_vpc
    version: 1.0.0

  - name: terraform_aws_subnet
    id: infrastructure_subnet
    version: 1.0.0
    props:
      vpc_id: !expr data.infrastructure_vpc.vpc_id

  - name: helm_nginx
    id: platform_nginx
    version: 1.0.0
    props:
      cluster_name: !expr data.infrastructure_subnet.cluster_name

  - name: helm_myapp
    id: application_myapp
    version: 1.0.0
    props:
      nginx_endpoint: !expr 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: terraform_aws_vpc
    id: hub_vpc
    version: 1.0.0

  - name: terraform_aws_subnet
    id: spoke_web
    version: 1.0.0
    props:
      vpc_id: !expr data.hub_vpc.vpc_id

  - name: terraform_aws_subnet
    id: spoke_db
    version: 1.0.0
    props:
      vpc_id: !expr data.hub_vpc.vpc_id

  - name: terraform_aws_subnet
    id: spoke_cache
    version: 1.0.0
    props:
      vpc_id: !expr 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: terraform_aws_vpc
    id: shared_vpc
    version: 1.0.0

  - name: helm_user_service
    id: user_service
    version: 1.0.0
    props:
      vpc_id: !expr data.shared_vpc.vpc_id

  - name: helm_order_service
    id: order_service
    version: 1.0.0
    props:
      vpc_id: !expr data.shared_vpc.vpc_id
      user_service_url: !expr data.user_service.endpoint

  - name: helm_payment_service
    id: payment_service
    version: 1.0.0
    props:
      vpc_id: !expr data.shared_vpc.vpc_id
      order_service_url: !expr 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.

name: my_blueprint
version: 1.0.0

inputs:
  environment:
    type: string
    description: Environment name
  instance_count:
    type: number
    description: Number of instances

packages:
  - name: terraform_aws_instance
    id: web_instances
    version: 1.0.0
    props:
      count: !expr inputs.instance_count
      environment: !expr inputs.environment

Install the same blueprint into different collections with different values:

# Development collection
bricks install my_blueprint --collection dev --props-file props-dev.yaml

# Production collection
bricks install my_blueprint --collection prod --props-file props-prod.yaml

Dependency management patterns

Explicit dependencies with version pinning

Pin specific package versions for stability and reproducibility.

packages:
  - name: terraform_aws_vpc
    id: vpc
    version: 1.2.0

  - name: terraform_aws_subnet
    id: subnet
    version: 1.1.0
    props:
      vpc_id: !expr 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.

name: my_blueprint
version: 1.0.0

inputs:
  enable_monitoring:
    type: bool
    default: true

packages:
  - name: terraform_aws_instance
    id: web_server
    version: 1.0.0

  - name: helm_prometheus
    id: monitoring
    version: 1.0.0
    props:
      target_instance: !expr data.web_server.private_ip
      enabled: !expr inputs.enable_monitoring

Output management patterns

Aggregated outputs

Combine outputs from multiple packages into a single blueprint output.

outputs:
  web_endpoints:
    value: !expr "data.web_server.endpoint + ',' + data.api_server.endpoint"
    description: All web endpoints
  database_info:
    value: !expr data.database.connection_string
    description: Database connection

Conditional outputs

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

outputs:
  monitoring_url:
    value: !expr "inputs.enable_monitoring ? data.monitoring.url : 'Monitoring disabled'"
    description: Monitoring dashboard URL

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

Structured outputs

Organize outputs into logical groups for clarity.

outputs:
  infrastructure:
    value: !expr data.vpc.vpc_id
    description: VPC ID
  application:
    value: !expr data.web_app.url
    description: Application URL
  monitoring:
    value: !expr data.monitoring.dashboard_url
    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

# DON'T: Circular dependency
packages:
  - name: package_a
    version: 1.0.0
    props:
      value: !expr data.package_b.output

  - name: package_b
    version: 1.0.0
    props:
      value: !expr data.package_a.output

Deep dependency chains

# DON'T: Long sequential chain prevents parallelism
packages:
  - name: pkg1
    id: pkg1
    version: 1.0.0
  - name: pkg2
    id: pkg2
    version: 1.0.0
    props:
      dep: !expr data.pkg1.out
  - name: pkg3
    id: pkg3
    version: 1.0.0
    props:
      dep: !expr data.pkg2.out
  - name: pkg4
    id: pkg4
    version: 1.0.0
    props:
      dep: !expr data.pkg3.out
  - name: pkg5
    id: pkg5
    version: 1.0.0
    props:
      dep: !expr data.pkg4.out

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

Unclear output references

# DON'T: Ambiguous reference
outputs:
  result:
    value: !expr data.pkg.out
    description: Result

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