Blueprint Composition Patterns

Learn common patterns for composing blueprints and managing package dependencies effectively.

Prerequisites

Understanding of blueprints and packages
Familiarity with Data.* references
Experience with package management

Composition Patterns

1. Layered Architecture

Pattern: Stack packages in layers (infrastructure → platform → application)

{
  "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"
        }
      }
    }
  ]
}

Benefits:

Clear separation of concerns
Predictable dependency flow
Easy to understand and maintain

2. Hub and Spoke

Pattern: 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"
        }
      }
    }
  ]
}

Benefits:

Shared infrastructure resources
Cost optimization
Centralized network management

3. Microservices Composition

Pattern: Each service is a separate package with shared 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"
        }
      }
    }
  ]
}

Benefits:

Service independence
Clear service boundaries
Scalable architecture

4. Environment-Specific Composition

Pattern: Same blueprint with different configurations per environment

{
  "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"
        }
      }
    }
  ]
}

Usage:

# 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}'

Benefits:

Single blueprint for multiple environments
Environment-specific configuration
Consistent architecture

Dependency Management Patterns

1. Explicit Dependencies

Pattern: Clearly define all package dependencies

{
  "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"
        }
      }
    }
  ]
}

2. Conditional Dependencies

Pattern: Use expressions for conditional package behavior

{
  "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"
        }
      }
    }
  ]
}

3. Version Pinning

Pattern: Pin specific package versions for stability

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_vpc",
      "id": "vpc",
      "version": "1.2.0"  // Pinned version
    },
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "subnet",
      "version": "1.1.0"  // Pinned version
    }
  ]
}

Output Management Patterns

1. Aggregated Outputs

Pattern: Combine outputs from multiple packages

{
  "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"
    }
  }
}

2. Conditional Outputs

Pattern: Control execution based on configuration - Bluebricks only executes components whose outputs are actually needed

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

How it works:

If enable_monitoring is false, the monitoring component is NOT executed
This follows Bluebricks' output-driven execution model
Only components providing needed outputs are deployed
Props flow down, data flows up based on actual requirements

3. Structured Outputs

Pattern: Organize outputs into logical groups

{
  "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"
    }
  }
}

Expression Language Patterns

Bluebricks uses the expr-lang expression language to enable dynamic configurations and advanced composition patterns.

1. Dynamic Resource Naming

Pattern: Generate unique resource names using expressions

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_s3",
      "id": "data_bucket",
      "props": {
        "bucket_name": {
          "value": "now().Format('02012006030405') + '_' + Props.environment + '_data_bucket'"
        }
      }
    }
  ]
}

Benefits:

Prevents naming conflicts
Includes timestamp for uniqueness
Environment-specific naming

2. Conditional Package Configuration

Pattern: Use ternary operators for environment-specific settings

{
  "props": {
    "environment": {
      "type": "string",
      "default": "dev"
    }
  },
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_instance",
      "id": "web_server",
      "props": {
        "instance_type": {
          "value": "Props.environment == 'prod' ? 'm5.xlarge' : 't3.medium'"
        },
        "monitoring_enabled": {
          "value": "Props.environment == 'prod' ? true : false"
        }
      }
    }
  ]
}

3. Null Coalescing for Fallbacks

Pattern: Provide fallback values using the ?? operator

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_subnet",
      "id": "web_subnet",
      "props": {
        "vpc_id": {
          "value": "Props.vpc_id ?? Data.shared_vpc.vpc_id"
        },
        "availability_zone": {
          "value": "Props.az ?? 'us-west-2a'"
        }
      }
    }
  ]
}

4. String Manipulation and Concatenation

Pattern: Build complex strings from multiple sources

{
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_route53",
      "id": "dns_record",
      "props": {
        "domain_name": {
          "value": "Props.service_name + '.' + Props.environment + '.' + Props.base_domain"
        },
        "description": {
          "value": "'DNS record for ' + Props.service_name + ' in ' + Props.environment"
        }
      }
    }
  ]
}

5. Array and Object Access

Pattern: Access nested properties and array elements

{
  "props": {
    "network_config": {
      "type": "object",
      "default": {
        "subnets": ["subnet-abc", "subnet-def"],
        "security_groups": ["sg-123", "sg-456"]
      }
    }
  },
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_instance",
      "id": "app_server",
      "props": {
        "subnet_id": {
          "value": "Props.network_config.subnets[0]"
        },
        "security_group_ids": {
          "value": "Props.network_config.security_groups"
        }
      }
    }
  ]
}

6. Mathematical Operations

Pattern: Perform calculations for resource sizing

{
  "props": {
    "base_instance_count": {
      "type": "number",
      "default": 2
    },
    "environment": {
      "type": "string",
      "default": "dev"
    }
  },
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_instance",
      "id": "web_servers",
      "props": {
        "count": {
          "value": "Props.environment == 'prod' ? Props.base_instance_count * 2 : Props.base_instance_count"
        },
        "cpu_credits": {
          "value": "Props.environment == 'prod' ? 'unlimited' : 'standard'"
        }
      }
    }
  ]
}

7. Complex Conditional Logic

Pattern: Use multiple conditions for sophisticated logic

{
  "props": {
    "environment": {
      "type": "string",
      "default": "dev"
    },
    "enable_ssl": {
      "type": "bool",
      "default": true
    }
  },
  "packages": [
    {
      "name": "@bluebricks/terraform_aws_alb",
      "id": "load_balancer",
      "props": {
        "ssl_certificate_arn": {
          "value": "Props.enable_ssl && Props.environment == 'prod' ? Secrets.prod_ssl_cert : (Props.enable_ssl ? Secrets.dev_ssl_cert : '')"
        },
        "health_check_path": {
          "value": "Props.environment == 'prod' ? '/health' : '/dev-health'"
        }
      }
    }
  ]
}

8. Output Aggregation with Expressions

Pattern: Combine multiple outputs using expressions

{
  "outs": {
    "all_endpoints": {
      "value": "Data.web_server.endpoint + ',' + Data.api_server.endpoint + ',' + Data.admin_server.endpoint",
      "type": "string",
      "description": "All service endpoints"
    },
    "database_connection": {
      "value": "'postgresql://' + Secrets.db_username + ':' + Secrets.db_password + '@' + Data.database.endpoint + ':5432/' + Props.database_name",
      "type": "string",
      "description": "Complete database connection string"
    },
    "monitoring_dashboard": {
      "value": "Props.enable_monitoring ? Data.monitoring.dashboard_url : 'Monitoring disabled'",
      "type": "string",
      "description": "Monitoring dashboard URL or status"
    }
  }
}

Best Practices

Package Selection

Choose packages that complement each other
Verify package compatibility
Use stable, well-maintained packages
Consider package performance impact

Dependency Design

Minimize dependencies
Avoid circular references
Use clear naming conventions
Document dependency reasons

Configuration Management

Provide sensible defaults
Use descriptive property names
Validate property values
Document configuration options

Expression Language Best Practices

Use expressions for dynamic values, not static ones
Keep expressions readable and well-documented
Test complex expressions thoroughly
Use null coalescing (??) for safe fallbacks
Leverage built-in functions for string manipulation
Avoid overly complex nested expressions

Testing Strategy

Test blueprint composition locally
Verify all package interactions
Check output references
Validate property flow
Test expression evaluation with different inputs

Anti-Patterns to Avoid

1. Circular Dependencies

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

2. Over-Complex Dependencies

// BAD: Too many dependencies
{
  "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"}}
  ]
}

3. Unclear Output References

// BAD: Unclear reference
{
  "outs": {
    "result": {
      "value": "Data.pkg.out",  // Which output?
      "type": "string"
    }
  }
}

Good night

Blueprint Composition Patterns

Prerequisites

Composition Patterns

1. Layered Architecture

2. Hub and Spoke

3. Microservices Composition

4. Environment-Specific Composition

Dependency Management Patterns

1. Explicit Dependencies

2. Conditional Dependencies

3. Version Pinning

Output Management Patterns

1. Aggregated Outputs

2. Conditional Outputs

3. Structured Outputs

Expression Language Patterns

1. Dynamic Resource Naming

2. Conditional Package Configuration

3. Null Coalescing for Fallbacks

4. String Manipulation and Concatenation

5. Array and Object Access

6. Mathematical Operations

7. Complex Conditional Logic

8. Output Aggregation with Expressions

Best Practices

Package Selection

Dependency Design

Configuration Management

Expression Language Best Practices

Testing Strategy

Anti-Patterns to Avoid

1. Circular Dependencies

2. Over-Complex Dependencies

3. Unclear Output References

See also

Good night

hashtagPrerequisites

hashtagComposition Patterns

hashtag1. Layered Architecture

hashtag2. Hub and Spoke

hashtag3. Microservices Composition

hashtag4. Environment-Specific Composition

hashtagDependency Management Patterns

hashtag1. Explicit Dependencies

hashtag2. Conditional Dependencies

hashtag3. Version Pinning

hashtagOutput Management Patterns

hashtag1. Aggregated Outputs

hashtag2. Conditional Outputs

hashtag3. Structured Outputs

hashtagExpression Language Patterns

hashtag1. Dynamic Resource Naming

hashtag2. Conditional Package Configuration

hashtag3. Null Coalescing for Fallbacks

hashtag4. String Manipulation and Concatenation

hashtag5. Array and Object Access

hashtag6. Mathematical Operations

hashtag7. Complex Conditional Logic

hashtag8. Output Aggregation with Expressions

hashtagBest Practices

hashtagPackage Selection

hashtagDependency Design

hashtagConfiguration Management

hashtagExpression Language Best Practices

hashtagTesting Strategy

hashtagAnti-Patterns to Avoid

hashtag1. Circular Dependencies

hashtag2. Over-Complex Dependencies

hashtag3. Unclear Output References

hashtagSee also

Prerequisites

Composition Patterns

1. Layered Architecture

2. Hub and Spoke

3. Microservices Composition

4. Environment-Specific Composition

Dependency Management Patterns

1. Explicit Dependencies

2. Conditional Dependencies

3. Version Pinning

Output Management Patterns

1. Aggregated Outputs

2. Conditional Outputs

3. Structured Outputs

Expression Language Patterns

1. Dynamic Resource Naming

2. Conditional Package Configuration

3. Null Coalescing for Fallbacks

4. String Manipulation and Concatenation

5. Array and Object Access

6. Mathematical Operations

7. Complex Conditional Logic

8. Output Aggregation with Expressions

Best Practices

Package Selection

Dependency Design

Configuration Management

Expression Language Best Practices

Testing Strategy

Anti-Patterns to Avoid

1. Circular Dependencies

2. Over-Complex Dependencies

3. Unclear Output References

See also