Bluebricks Self Hosted Runner

The Bluebricks-Deployment-Controller Overview

Bluebricks Deployments Controller (BDC) is a Kubernetes operator that manages and orchestrates the lifecycle of Infrastructure as Code (IaC) tasks. It continuously watches for new Task’s Custom Resources Definition (CRD), creates runner pods to handle the installation or uninstallation, and monitors the job status. BDC schedules and manages the underlying job logic automatically.

Bluebricks Deployments Controller Architecture

---

How it Operates

BDC reads Task specifications and uses the necessary Bricks Runner containers to perform the operations:

• Fetches Pending tasks from Bluebricks API according to the assigned Environment

• Watches for new or updated Task resources in the cluster.

• Creates Kubernetes jobs or pods to install or remove IaC components.

• Tracks job logs and statuses, storing errors and progress details.

• Cleans up old jobs or leftover resources once tasks are finished.

---

Bricks Runner

Bricks Runner is a container that spawns on each triggered job and executes the IaC instructions provided by BDC. It receives environment configuration and runs the appropriate commands for planning or applying the infrastructure changes.

It is designed to:

• Execute IaC Runs according to the bricks.json manifest

• Report success, failure, or errors back to BDC so it can update Task statuses.

---

Installing Bluebricks Deployments Controller

No Kubernetes? No problem! If you don't have a Kubernetes cluster available, try Orchestrator in a Box to easily deploy a lightweight K3s-based environment on a single VM.

Prerequisites

1. Helm (v3.8 or later) is recommended for native OCI registry support.

2. Access to a Kubernetes cluster with the correct permissions.

3. Minimum Kubernetes version 1.28

4. (Optional) A custom values.yaml file to override default chart settings.

Basic Installation

Use the following Helm command to install the BDC chart from the OCI registry:

helm repo add bbx-helm-repo https://storage.googleapis.com/bluebricks-helm-public

helm install bdc https://storage.googleapis.com/bluebricks-helm-public/helm/bluebricks-deployments-controller:0.1.36

Explanation:

• bdc is the release name. You can change it to anything you prefer.

• oci://europe-docker.pkg.dev/bbx-registry-prod/helm/bluebricks-deployments-controller

---

Before proceeding, check the chart README for detailed information about configuring values.

---

Review the chart values.yaml

helm show values \\
	  \\
	 > values.yaml

Customizing with a values.yaml

To customize values (e.g., resource limits, environment variables, or other chart-specific settings), you can download or create a values.yaml file locally. Then install with:

helm install bdc \\
  oci://europe-docker.pkg.dev/bbx-registry-prod/helm/bluebricks-deployments-controller:1.0.33 \\
  -f values.yaml

Upgrading the Release

If you want to apply updates, simply run an upgrade command:

helm upgrade bdc \\
  oci://europe-docker.pkg.dev/bbx-registry-prod/helm/bluebricks-deployments-controller:1.0.33 \\
  -f values.yaml

---

Container Images

Both BDC and Bricks images are hosted in the same container registry. By default, these images are built as multi-architecture (also referred to as “fat binaries”), supporting both ARM (arm64) and Intel (amd64) platforms.

BDC Image

• Source: ghcr.io/bluebricks-dev/bdctl

• Purpose: Runs the Kubernetes operator that watches for Task CRDs, creates runner jobs, and manages IaC lifecycle tasks.

• Multi-Platform: Single image tag that supports both amd64 and arm64.

Bricks Runner Image

• Source: ghcr.io/bluebricks-dev/bricks

• Purpose: Executes the actual IaC instructions (e.g., installs or removes infrastructure) when a BDC job is triggered.

• Multi-Platform: Single image tag that supports both amd64 and arm64.

If you need to override any of these container image references (for example, to pin a specific version or use a private registry), you can set the appropriate fields in your values.yaml file when installing or upgrading with Helm. The chart’s defaults point to the multi-architecture images in the public registry.

---

Monitoring Logs & Metrics

BDC includes the following ways to gain insight into deployments and jobs:

• Logs

  • Use “kubectl logs -f job/ -n ” to watch real-time logs.

  • Preview job progress or troubleshoot errors directly from the running container.

  • Log level is controlled by the LOG_LEVEL environment variable

• Metrics

  • An HTTP metrics endpoint runs on the operator’s pod (using the built-in metrics server).

  • Integrate with tools like Prometheus or Grafana to gather performance and usage metrics.

Security

We continuously maintain and improve the security posture of the Bluebricks Deployments Controller and Bricks Runner. Each chart release undergoes regular checks following a 3-layer method:

1. Code Scanning: Automated scanning of the codebase to detect and remediate vulnerabilities early in the development cycle.

2. Image Scanning: Periodic scanning of container images to identify outdated dependencies or known security issues.

3. Chart Misconfiguration Scanning: Validation and lint checks of Helm chart configurations to minimize deployment risks and misconfigurations.