# 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.

<figure><img src="/files/GyhzKsH8vfPcdseMAhJU" alt=""><figcaption><p>Bluebricks Environments Controller Architecture</p></figcaption></figure>

***

### **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 Collection
* 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 collection 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

{% hint style="info" %}
**No Kubernetes? No problem!** If you don't have a Kubernetes cluster available, try [Orchestrator in a Box](/docs/organization-and-security/bluebricks-self-hosted-runner/orchestrator-in-a-box.md) to easily deploy a lightweight K3s-based environment on a single VM.
{% endhint %}

### 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:

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

**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`

{% hint style="info" %}
Before proceeding, check the chart [README](/docs/organization-and-security/bluebricks-self-hosted-runner/bdc-helm-chart.md) for detailed information about configuring values.
{% endhint %}

### Review the chart `values.yaml`

```bash
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:

```bash
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:

```bash
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.

### Sizing and tuning

Adjust these values based on your cluster size and deployment volume. For the full list of configurable values, see the [BDC Helm Chart](/docs/organization-and-security/bluebricks-self-hosted-runner/bdc-helm-chart.md) reference.

#### Parallel workers

Control how many deployments BDC processes concurrently by setting `--max-concurrent-reconciles`:

```yaml
command:
  args:
    - "start"
    - "operator"
    - "--controllers=tasks"
    - "--max-concurrent-reconciles"
    - "4"  # default: 3
```

#### Runner resources

Set CPU and memory for the Bricks Runner pods that execute IaC operations:

```yaml
bricksRunner:
  cm:
    resources:
      requests:
        cpu: "500m"
        memory: "1024Mi"
      limits:
        cpu: "1000m"
        memory: "2048Mi"
```

#### Storage

Configure the persistent volume size for the storage manager:

```yaml
bbxStorageManager:
  storage:
    size: "30Gi"  # 10Gi minimum, 100Gi+ for high-volume clusters
```

#### Sizing guidelines

| Cluster size         | Workers | Runner memory | Storage |
| -------------------- | ------- | ------------- | ------- |
| Small (< 10 nodes)   | 2-3     | 1024Mi        | 10Gi    |
| Medium (10-50 nodes) | 4-8     | 1024Mi        | 30Gi    |
| Large (50+ nodes)    | 8-16    | 2048Mi        | 100Gi+  |

### Monitoring logs and 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/organization-and-security/bluebricks-self-hosted-runner.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.