Brig Init

Last week, we announced the first beta release of Brigade 2. Today, we’re taking a deep dive into an exciting new feature we shipped in that release: the Brigade CLI’s new init command.

Brigade 2 development efforts have been heavily focused on improving Brigade’s UX. A significant pain point from Brigade 1.x that we’ve been intent on improving was the interactive, but onerous project creation process. Since the project’s maintainers are big fans of “infrastructure as code” and because imitation is the sincerest form of flattery, Brigade 2 drew inspiration from Kubernetes and utilizes project definition files that are reminiscent of Kubernetes manifests (but aren’t). Projects can be created and updated by submitting such definitions to Brigade.

While project definitions as source offer an attractive improvement to Brigade, they aren’t without their own all-new frustration. Just how does one author one of these project definitions? We don’t know about you, but most of us on the Brigade team can’t write a Kubernetes manifest from scratch! We generally copy an existing one that’s close to what we need and then modify it. However, we felt we could do better for Brigade 2’s project definitions.

Enter brig init. This new CLI command, reminiscent of git init or helm create, initializes a .brigade/ sub-directory of your current working directory with a project definition file, Brigade script, notes containing next steps, and more.

With this, we hand the rest of the post over to our summer intern, Willie, who developed this feature with guidance from project maintainers.

Generating a Project Definition with Init

First, make sure you have the latest version of Brigade 2 and its CLI installed (v2.0.0-beta.1 as of this writing). More details on how to do so can be found in Brigade 2’s Quickstart Guide.

Once Brigade 2 is up and running on your cluster, you are ready to try the init command! To get started, simply run the following from the root directory of your project:

$ brig init -i <project name>

Note that valid project names must contain only lowercase alphanumeric characters and dashes.

The following files are generated in the .brigade/ sub-directory:

• project.yaml: This is the project definition file. Because no git integration was specified, a brigade.ts (TypeScript) script is embedded within the project definition. The project definition and embedded script both contain commented examples of subscribing to and handling events.

• secrets.yaml: This is a file for defining project secrets. brig init automatically adds this file to your .gitignore, and you should take great care to never commit this file to a public repository.

• NOTES.txt: This file contains next steps for creating a project from your project.yaml file and defining project secrets using your secrets.yaml file.

With these files generated and edited to suit your needs, you can proceed with creating a Brigade 2 project, just as if you’d authored the project definition and script from scratch.

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

Additional Options

While we’ve just covered the simplest use of our new brig init feature, it has a few more tricks up its sleeve. Here are some optional flags you can use:

• --language, -l: Specifies your preferred scripting language. Brigade 2 supports both JavaScript and TypeScript.

• --git, -g: Optionally specifies a git repository where your event handling script will reside. When this flag is used, brig init generates additional files inside the .brigade directory, including a separate script (instead of embedding it in the project definition).

If, for example, you wanted to initialize a new Brigade project using JavaScript and git integration, your command might look like this:

$ brig init -i <project name> -l js -g https://github.com/<org>/<repo>.git

Note that with git integration, the script must be checked into your repository’s master/main branch, because that’s where Brigade will go looking for it.

Closing Thoughts

This new feature closes one of the biggest gaps in Brigade’s UX and the team is excited to have included this in the first beta release. We hope that you’ll find this as useful as we do!

As always, please be sure to let us know of any issues you encounter, and we can also be reached in the #brigade chat on the Kubernetes Slack.