Brigade: Fun in 5 minutes tutorial?

[mattfarina]

@technosophos asked me to file this.

Can I get a tutorial that tells one how to:

1. Install brigade
2. Install Kashti
3. Do something with brigade and see the result

All in 5 minutes or less on average.

[dgkanatsios]

is the idea about something like this?

• (assume user has set up a K8s cluster with helm/tiller)
• install Brigade (Kashti included) via helm
• run brig project create with default values
• kubectl to the cluster to see the created secrets
• run brig run with a small brigade.js file like

const { events, Job } = require("brigadier")
events.on("exec", () => {
  var job = new Job("do-nothing", "alpine:3.8")
  job.tasks = [
    "echo Hello",
    "echo World"
  ]

  job.run()
})

• kubectl to the cluster to see the worker and the job pods
• (possibly) view the job In Kashti

WDYT?

[radu-matei]

Yes, that would also work great with #748.

[dgkanatsios]

WDYT? Also, what would be the appropriate documentation page for it? Maybe replace the Quickstart on the README with this?

Brigade Quickstart - Fun with Brigade in 5'!

Install Brigade into your cluster:

# add Brigade chart repo
helm repo add brigade https://azure.github.io/brigade
# install Brigade - this also installs Kashti
helm install -n brigade brigade/brigade

You need to install brig command line client. You can use brig to create/update/delete new brigade Projects, run Builds etc. To get brig, navigate to the Releases page and then download the appropriate client for your platform. For example, if you're using Linux or WSL, you can do:

wget -O brig https://github.com/Azure/brigade/releases/download/v0.19.0/brig-linux-amd64
chmod +x brig
mv brig ~/bin

Let's now create a simple Project. Feel free to modify or leave all options at their defaults (just press Enter on every interactive prompt). Your project will have the name deis/empty-testbed.

brig project create

View the newly created project:

brig project list

Output would be something like:

NAME                    ID                                                              REPO
deis/empty-testbed      brigade-830c16d4aaf6f5490937ad719afd8490a5bcbef064d397411043ac  github.com/deis/empty-testbed

You can also do a kubectl get secret to view the Project Secret

NAME                                                             TYPE                                  DATA   AGE
brigade-830c16d4aaf6f5490937ad719afd8490a5bcbef064d397411043ac   brigade.sh/project                    24     2m
...
other Secrets
...

Let's run a Brigade Build. Create a new file called brigade.js with the following content:

const { events, Job } = require("brigadier")
events.on("exec", () => {
  var job = new Job("do-nothing", "alpine:3.8")
  job.tasks = [
    "echo Hello",
    "echo World"
  ]

  job.run()
})

Create the Build using the command:

brig run deis/empty-testbed -f brigade.js

Do not forget to replace deis-emptytestbed with the name of your project.

If you see an output similar to the following, then your Brigade Build was run successfully!

Event created. Waiting for worker pod named "brigade-worker-01d0w5vdwgk7razcy9t4b6rk0f".
Build: 01d0w5vdwgk7razcy9t4b6rk0f, Worker: brigade-worker-01d0w5vdwgk7razcy9t4b6rk0f
prestart: no dependencies file found
prestart: loading script from /etc/brigade/script
[brigade] brigade-worker version: 0.19.0
[brigade:k8s] Creating secret do-nothing-01d0w5vdwgk7razcy9t4b6rk0f
[brigade:k8s] Creating pod do-nothing-01d0w5vdwgk7razcy9t4b6rk0f
[brigade:k8s] Timeout set at 900000
[brigade:k8s] Pod not yet scheduled
[brigade:k8s] default/do-nothing-01d0w5vdwgk7razcy9t4b6rk0f phase Pending
[brigade:k8s] default/do-nothing-01d0w5vdwgk7razcy9t4b6rk0f phase Succeeded
done

You can also see this Project/Build/output combination in Kashti as well. To connect, you need to port-forward from your local machine to the relevant Kubernetes Service.

kubectl port-forward service/brigade-kashti 8000:80

Then, you can navigate to http://localhost:8000 to see Kashti dashboard with your Project and Build.

To cleanup:

# delete project
brig  project delete deis/empty-testbed
# remove Brigade
helm delete brigade --purge

[squillace]

I don't want "build" used here. The precise thing you run is a job, so let's use that.

That said, I don't like the quickstart version. I'd love to start with something like this instead, and then work up complexity in five-minute increments. :-)

[squillace]

God, I hate that Build in the middle of the output. :-( What a distracting, misleading output. I know why it's there, though.

[technosophos]

Actually, what you create is a _build_ and it is composed of _jobs_. We were between "build" and "task" and ended up using "build" because of the CI connotations, even though "task" is closer to the ETL language.

[technosophos]

It might be useful to show the output of build project create just so that users can see at a glance what the prompts look like.

[technosophos]

I think this is excellent!

[squillace]

@technosophos I put a -1 on the Build language, as it's actually formally defined as a _run_ of a job, which is PERFECT and generic. BUT: as you can imagine, this is not the biggest problem. :-)

[vdice]

@dgkanatsios minor revision: first command should read helm repo add brigade https://azure.github.io/brigade-charts. Otherwise, looks good to me!

Also perhaps add the follow-logs option and/or check the 'do-nothing' pod logs to see the echo statements?

[dgkanatsios]

Thanks everybody, will add it to README.md and PR tomorrow!

[dgkanatsios]

PR here: https://github.com/Azure/brigade/pull/769

thanks @vdice, follow logs is not yet into released version of brig, so we can revert to 'kubectl get logs' for the time being and then update it when we release next version.