Orchestrator in a Box

Bluebricks Orchestrator in a Box (OIB) provides a streamlined solution for deploying the Bluebricks Self-Hosted Runner on a single VM using a lightweight Kubernetes environment.

Overview

The Orchestrator in a Box solution creates a lightweight Kubernetes environment using K3s, which runs inside Docker containers using k3d, and then deploys the Bluebricks Deployments Controller. This makes it ideal for:

• Environments with limited Kubernetes expertise

• Simpler deployments with minimal infrastructure requirements

• Quick setup for testing or evaluation purposes

• Resource-constrained environments

Orchestrator in a Box Infrastrcture

System Requirements

• Operating System: Ubuntu Linux (20.04+ recommended)

• Resources:

  • 4 GB RAM minimum (8GB+ recommended)

  • 20 GB storage minimum

  • 2 CPUs minimum

• Software Requirements:

  • Docker Engine

  • curl

• Network Requirements:

  • Complies with Bluebricks Network Access Requirements

    • If using a proxy, ensure environment variables are set (HTTP_PROXY and HTTPS_PROXY)

Installation

Download and Prepare Installation Files

curl -O https://brickscli.s3.eu-west-1.amazonaws.com/releases/latest/orchestrator-in-a-box/install.sh
curl -O https://brickscli.s3.eu-west-1.amazonaws.com/releases/latest/orchestrator-in-a-box/config.yaml
chmod +x install.sh

Execute the Installation Script

./install.sh

The installation script will:

1. Check system prerequisites

2. Install k3d (if not already installed)

3. Create a single-node K3s cluster inside Docker

4. Install the required Kubernetes components

5. Deploy the Bluebricks Orchestrator using Helm

6. Configure the Kubernetes environment

7. Display access information

Configure the self-hosted Orchestrator

The configuration includes setting up the collection, generating a static authentication token, and establishing communication between the Bluebricks Control Plane and the Orchestrator in a Box.

Create a Collection

This collection will be used to manage the deployments handled by your self-hosted orchestrator. Follow the 'Create a Collection' article to connect the self-hosted Orchestrator you created.

At this point, go to https://app.bluebricks.co/collections and validate that the created collection is listed. If listed, proceed to generate your Static Auth Token.

Generate Static Auth Token

The Static Auth Token is a one-time activity that generates a unique token to be used by the Orchestreator in a Box. This token will be registered in Bluebricks Control Plane and ensure secure communication.

Fetch JWT from Bricks CLI

You're going to use Bluebricks API, which is protected by a JWT. We'll use the assigned JWT that was created when you logged in to bricks.

If you haven't signed into bricks CLI already, please open your terminal and type bricks login. If you haven't installed the bricks CLI, please refer to this article.

Once signed in, fetch your JWT by typing the following command:

cat ~/.bricks/credentials.yaml | grep 'token:' | awk '{print $3}'

Call Bluebricks API

Open a terminal and execute the following API request using curl to generate the Static Auth Token

curl https://api.bluebricks.co/api/v1/cloud \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --data '{
  "name": "<DISPLAY_NAME>",
  "accountId": "<UNIQUE_NAME>",
  "collection": "<COLLECTION_SLUG>",
  "provider": "self-hosted"
}'

Be sure to replace the placeholders with your data as described below:

Placeholder	Replace with	Note
<YOUR_BEARER_TOKEN>	JWT that was fetched in the previous step.
<DISPLAY_NAME>	A friendly name that will be used later to identify your OIB
<UNIQUE_NAME>	A lowercase with no spaces name to identify your OIB in scripts and API calls
<COLLECTION_SLUG>	The slug of the created collection from the previouse steps	Collection slug is listed on Bluebricks Control Plane on Collections Page

The response shall include a static_auth_token value, which you'll use to authenticate your orchestrator:

{
  "id": "cloud-xxxx",
  "static_auth_token": "YourOrchestratorAuthToken",
  "name": "my-orchestrator-in-a-box",
  "status": "active"
}

Assign Identity to the OIB

Use the following install.sh script to add the generated Static Auth Token

/install.sh --orchestrator-token "YourOrchestratorAuthToken"

Verifying Installation

After installation completes, you can verify the orchestrator is running by checking the Kubernetes pods:

export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get pods -n bluebricks

You should see pods running the Bluebricks orchestrator components.

• Check the logs using the following command:

kubectl logs -n bluebricks deployment/bluebricks-deployments-controller-bdc

You can also use the Kubernetes dashboard if it was enabled during installation:

export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl proxy

Then access the dashboard at: http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

Using kubectl with the K3s Cluster

Interact with your K3s cluster using the following commands:

export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get nodes
kubectl get namespaces

Customization

Using a Custom Configuration

You can customize the K3s cluster and orchestrator deployment by editing the config.yaml file before installation, or by providing a custom configuration file:

./install.sh --config-file my-custom-config.yaml

Advanced Options

Options:
  -h, --help                 Show this help message
  --config-file FILE         Values configuration file
  --orchestrator-token TOKEN Orchestrator API token for Bluebricks API integration
  --k3s-version VERSION      K3s version to install
  --namespace NAMESPACE      Kubernetes namespace to install the orchestrator
  --release-name NAME        Helm release name
  --uninstall                Uninstall Orchestrator in a Box

Uninstallation

To completely remove the orchestrator and K3s cluster, execute the following command.

./install.sh --uninstall

Uninstallation script will do the following:

1. Uninstall the orchestrator Helm release

2. Delete the K3s cluster

3. Remove the kubeconfig file

4. Clean up any temporary files

Troubleshooting

Connectivity Problems

If the orchestrator cannot connect to the Bluebricks API, verify your network settings and ensure the required domains are whitelisted.

Authentication Failures

Double-check that you're using the correct Static Auth Token.

Resource Constraints

If the K3s cluster or orchestrator pods are terminating unexpectedly, check system resources to ensure the VM has adequate memory and CPU available.

Docker is not Running

Ensure Docker is running before starting the installation by running docker info

Port Conflicts

If ports 6443 (Kubernetes API) or 8080 are already in use, you might need to modify the configuration.

Kubernetes Errors

If you encounter Kubernetes-related errors:

export KUBECONFIG="$HOME/.kube/orchestrator-in-a-box-config"
kubectl get events --sort-by=.metadata.creationTimestamp

Support

For issues related to Orchestrator in a Box, please get in touch with the Bluebricks support team.