You are viewing docs for Brigade v2. Click here for v1 docs.

Brigade Docs

Brigade: Event-driven scripting for Kubernetes.

A Brigade Quickstart

This QuickStart presents a comprehensive introduction to Brigade. You will install Brigade with default configuration on a local, development-grade cluster, create a project and an event, watch Brigade handle that event, then clean up.

⚠️ Note that the default configuration is appropriate only for evaluating Brigade on a local, development-grade cluster and is not appropriate for any shared cluster – especially a production one. See our Deployment Guide for instructions suitable for shared or production clusters.

Prerequisites

Create a KinD Cluster

If you do not already have a local, development-grade cluster, we recommend using KinD. KinD runs an entire Kubernetes cluster locally within a Docker container. (Minikube also works well for local development, but isn’t covered in this guide.)

  1. Ensure that Docker is running on your machine. For example, docker ps should return a list of running containers.

  2. Install KinD. See the KinD documentation for full installation instructions. Below are instructions for common environments:

    Linux

    $ curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.11.1/kind-linux-amd64
$ chmod +x ./kind
$ mv ./kind /usr/local/bin

    macOS with Homebrew

    $ brew install kind

    Windows

    > mkdir -force $env:USERPROFILE\bin
> (New-Object Net.WebClient).DownloadFile("https://kind.sigs.k8s.io/dl/v0.11.1/kind-windows-amd64", "$ENV:USERPROFILE\bin\kind.exe")
> $env:PATH+=";$env:USERPROFILE\bin"

    The script above downloads kind.exe and adds it to your PATH for the current session. Add the following line to your PowerShell Profile if you want to make the change permanent:

    > $env:PATH+=";$env:USERPROFILE\bin"

  3. Create a Kubernetes cluster by running the following command:

    $ kind create cluster

  4. Verify that you can connect to the cluster using kubectl:

    $ kubectl cluster-info

Install Brigade

Install the Brigade CLI

In general, the Brigade CLI, brig, can be installed by downloading the appropriate pre-built binary from our releases page to a directory on your machine that is included in your PATH environment variable. On some systems, it is even easier than this. Below are instructions for common environments:

Linux

$ curl -Lo /usr/local/bin/brig https://github.com/brigadecore/brigade/releases/download/v2.2.0/brig-linux-amd64
$ chmod +x /usr/local/bin/brig

macOS

The popular Homebrew package manager provides the most convenient method of installing the Brigade CLI on a Mac:

$ brew install brigade-cli

Alternatively, you can install manually by directly downloading a pre-built binary:

$ curl -Lo /usr/local/bin/brig https://github.com/brigadecore/brigade/releases/download/v2.2.0/brig-darwin-amd64
$ chmod +x /usr/local/bin/brig

Windows

> mkdir -force $env:USERPROFILE\bin
> (New-Object Net.WebClient).DownloadFile("https://github.com/brigadecore/brigade/releases/download/v2.2.0/brig-windows-amd64.exe", "$ENV:USERPROFILE\bin\brig.exe")
> $env:PATH+=";$env:USERPROFILE\bin"

The script above downloads brig.exe and adds it to your PATH for the current session. Add the following line to your PowerShell Profile if you want to make the change permanent:

> $env:PATH+=";$env:USERPROFILE\bin"

Install Server-Side Components

To install server-side components on your local, development-grade cluster:

  1. Enable Helm’s experimental OCI support:

    POSIX

    $ export HELM_EXPERIMENTAL_OCI=1

    PowerShell

    > $env:HELM_EXPERIMENTAL_OCI=1

  2. Run the following commands to install Brigade with default configuration:

    $ helm install brigade \
    oci://ghcr.io/brigadecore/brigade \
    --version v2.2.0 \
    --create-namespace \
    --namespace brigade \
    --wait \
    --timeout 300s

    ⚠️ Installation and initial startup may take a few minutes to complete and it is normal for components to restart repeatedly until their own network-bound dependencies are up and running.

    If the deployment fails, proceed to the troubleshooting section.

Port Forwarding

Since you are running Brigade locally, use port forwarding to make the Brigade API available via the local network interface:

POSIX

$ kubectl --namespace brigade port-forward service/brigade-apiserver 8443:443 &>/dev/null &

PowerShell

> kubectl --namespace brigade port-forward service/brigade-apiserver 8443:443 *> $null

Trying It Out

Log into Brigade

To authenticate to Brigade as the root user, you first need to acquire the auto-generated root user password:

POSIX

$ export APISERVER_ROOT_PASSWORD=$(kubectl get secret --namespace brigade brigade-apiserver --output jsonpath='{.data.root-user-password}' | base64 --decode)

PowerShell

> $env:APISERVER_ROOT_PASSWORD=$(kubectl get secret --namespace brigade brigade-apiserver --output jsonpath='{.data.root-user-password}' | base64 --decode)

Then:

POSIX

$ brig login --insecure --server https://localhost:8443 --root --password "${APISERVER_ROOT_PASSWORD}"

PowerShell

> brig login --insecure --server https://localhost:8443 --root --password "$env:APISERVER_ROOT_PASSWORD"

The --insecure flag instructs brig login to ignore the self-signed certificate used by our local installation of Brigade.

If the brig login command hangs or fails, double-check that port-forwarding for the brigade-apiserver service was successfully completed in the previous section.

Create a Project

A Brigade project pairs event subscriptions with worker (event handler) configuration.

  1. Rather than create a project definition from scratch, we’ll accelerate the process using the brig init command:

    $ mkdir first-project
$ cd first-project
$ brig init --id first-project

    This will create a project definition similar to the following in .brigade/project.yaml. It subscribes to exec events emitted from a source named brigade.sh/cli. (This type of event is easily created using the CLI, so it is great for demo purposes.) When such an event is received, the embedded script is executed. The script itself branches depending on the source and type of the event received. For an exec event from the source named brigade.sh/cli, this script will spawn and execute a simple “Hello World!” job. For any other type of event, this script will do nothing.

    apiVersion: brigade.sh/v2
kind: Project
metadata:
  id: first-project
description: My new Brigade project
spec:
  eventSubscriptions:
    - source: brigade.sh/cli
      types:
        - exec
workerTemplate:
  logLevel: DEBUG
  defaultConfigFiles:
  brigade.ts: |
    import { events, Job } from "@brigadecore/brigadier"
        
    // Use events.on() to define how your script responds to different events. 
    // The example below depicts handling of "exec" events originating from
    // the Brigade CLI.
        
    events.on("brigade.sh/cli", "exec", async event => {
        let job = new Job("hello", "debian:latest", event)
        job.primaryContainer.command = ["echo"]
        job.primaryContainer.arguments = ["Hello, World!"]
        await job.run()
    })

    events.process()

  2. The previous command only generated a project definition from a template. We still need to upload this definition to Brigade to complete project creation:

    $ brig project create --file .brigade/project.yaml

  3. To see that Brigade now knows about this project, use brig project list:

    $ brig project list

ID              DESCRIPTION                             AGE
first-project   My new Brigade project                  1m

Create an Event

With our project defined, we are now ready to manually create an event and watch Brigade handle it:

$ brig event create --project first-project --follow

Below is example output:

Created event "2cb85062-f964-454d-ac5c-526cdbdd2679".

Waiting for event's worker to be RUNNING...
2021-08-10T16:52:01.699Z INFO: brigade-worker version: v2.2.0
2021-08-10T16:52:01.701Z DEBUG: writing default brigade.ts to /var/vcs/.brigade/brigade.ts
2021-08-10T16:52:01.702Z DEBUG: using npm as the package manager
2021-08-10T16:52:01.702Z DEBUG: path /var/vcs/.brigade/node_modules/@brigadecore does not exist; creating it
2021-08-10T16:52:01.702Z DEBUG: polyfilling @brigadecore/brigadier with /var/brigade-worker/brigadier-polyfill
2021-08-10T16:52:01.703Z DEBUG: compiling brigade.ts with flags --target ES6 --module commonjs --esModuleInterop
2021-08-10T16:52:04.210Z DEBUG: running node brigade.js
2021-08-10T16:52:04.360Z [job: hello] INFO: Creating job hello
2021-08-10T16:52:06.921Z [job: hello] DEBUG: Current job phase is SUCCEEDED

⚠️ By default, Brigade’s scheduler scans for new projects every thirty seconds. If Brigade is slow to handle your first event, this may be why.

Cleanup

If you want to keep your Brigade installation, run the following command to remove the example project created in this QuickStart:

$ brig project delete --id first-project

Otherwise, you can remove all resources created in this QuickStart by either:

  • Deleting the KinD cluster that you created at the beginning with kind delete cluster --name kind-kind OR
  • Preserving the cluster and uninstalling Brigade with helm delete brigade -n brigade

Next Steps

You now know how to install Brigade on a local, development-grade cluster, define a project, and manually create an event. Continue on to the Read Next document where we suggest more advanced topics to explore.

Troubleshooting

Installation Does Not Complete Successfully

A common cause for failed Brigade deployments is low disk space on the cluster node. In a local, development-grade cluster on macOS or Windows, this could be because insufficient disk space is allocated to Docker Desktop, or the space allocated is nearly full. If this is the case, it should be evident by examining logs from Brigade’s MongoDB or ActiveMQ Artemis pods. If the logs include messages such as “No space left on device” or “Disk Full!”, then you need to free up disk space and retry the installation. Running docker system prune is one way to recover disk space.

After you have freed up disk space, remove the bad installation, and then retry using the following commands:

$ helm uninstall brigade -n brigade
$ helm install brigade \
    oci://ghcr.io/brigadecore/brigade \
    --version v2.2.0 \
    --namespace brigade \
    --wait \
    --timeout 300s

Login Command Hangs

If the brig login command hangs, check that you included the --insecure (or -k) flag. This flag is required because the default configuration utilized by this QuickStart makes use of a self-signed certificate.