Git Repository Folder Structure

Recommended folder structure for managing Bluebricks artifacts, blueprints, and environment configurations in a Git repository.

The following Git repository folder structure represents Bluebricks' best practice for managing infrastructure development using Separation of Concerns (SoC) principles.

.
├── bluebricks/                          # Bluebricks specific files
│   ├── blueprints/                      # Business logic implementations
│   │   ├── <blueprint_name>/
│   │   │   ├── bricks.json              # Blueprint definition
│   │   └── ...
│   ├── artifacts/                       # Reusable components
│   │   ├── <artifact_name>/
│   │   │   ├── bricks.json              # Artifact definition (metadata, dependencies, etc.)
│   │   │   ├── src/                     # Source code (e.g., Terraform, Helm charts, CloudFormation Stacks)
│   │   │   │   └── terraform/
│   │   │   │       ├── main.tf
│   │   │   │       ├── outputs.tf
│   │   │   │       └── variables.tf
│   │   └── ...
│   ├── environments/                    # Encapsulating folder for environment configuration 
│   │   ├── dev/
│   │   │   ├── <environment_name>.yaml   # Environment declarative file 
│   │   │   └── ...
│   │   ├── staging/
│   │   │   ├── <environment_name>.yaml   # Environment declarative file 
│   │   │   └── ...
│   │   ├── prod/
│   │   │   ├── <environment_name>.yaml   # Environment declarative file 
│   │   │   └── ...

Explanation of Key Directories

• bluebricks/blueprints/: Contains the blueprints that define specific infrastructure or application environments. Each blueprint has its own directory and a bricks.json file defining its composition.

  • bricks.json (Blueprint): Defines the blueprint's name, description, version, and the Artifacts it uses.

• bluebricks/artifacts/: Contains reusable Artifacts that can be used across multiple blueprints. Each package has its own directory and a bricks.json file.

  • bricks.json (Artifact): Defines the package's metadata (name, description, version), dependencies on other artifacts, and any configurable properties.

  • src/: Contains the implementation of the package, typically using Infrastructure-as-Code tools like Terraform or Helm.

• environments/: Contains environment-specific configurations and manifests for deploying blueprints. This directory is used for GitOps pull-based environments to different environments.

  • <environment_name>.yaml: Declarative file for managing the configuration fed by a environment.

bricks.json Structure (Examples)

Terraform AWS Launch Template Artifact:

bluebricks/artifacts/terraform-aws-launch-template/bricks.json

{
  "name": "terraform_aws_launch_template",
  "description": "Creates an AWS Launch Template.",
  "version": "1.2.0",
  "native": {
    "type": "terraform",
    "path": "./src/terraform"
  },
  "props": { /* ... */ },
  "outs": { /* ... */ }
}

AWS Launch Template Blueprint:

bluebricks/blueprints/launch_template_s3/bricks.json

{
  "name": "@bluebricks/launch_template_s3",
  "description": "EC2 Launch Template and S3 bucket.",
  "version": "1.2.0",
  "packages": [
    {
      "name": "random_output",
      "version": "1.0.4",
      "props": { /* ... */ }
    },
    {
      "name": "terraform_aws_launch_template",
      "version": "1.2.0", // Explicitly specifying the desired version
      "props": { /* ... */ }
    },
    {
      "name": "terraform_aws_s3_new",
      "version": "1.0.1",
      "props": { /* ... */ }
    }
  ],
  "props": { /* ... */ },
  "outs": { /* ... */ }
}