Getting Started

This guide installs Armada on your laptop and runs your first job. You'll use Kind, which runs a small Kubernetes cluster inside Docker; and the Armada Operator, which installs Armada into that cluster with one command.

By the end, you'll have Armada running, a job that has finished, and its output on your screen.

Time needed: about 10 minutes, most of it waiting for the install.

What you'll be working with

Armada — a batch job scheduler that runs jobs across many Kubernetes clusters. You give it jobs, and it decides which cluster and node each one runs on, and when, sharing the machines fairly between teams.
Job — a Kubernetes pod that runs to completion. The pod can have more than one container.
Queue — where jobs wait, and what controls each team's access to the cluster: Armada shares resources fairly between queues and can limit how much each one runs at once. Each team usually has one.
armadactl — the command-line tool you use to talk to Armada.
Lookout — Armada's web interface for finding, following and managing jobs.

Before you start

Prerequisites

Make sure you have these running on your machine:

Docker Desktop - or another Docker engine
kubectl - Command-line tool for Kubernetes
Helm - Package manager for Kubernetes
Kind - For creating a local Kubernetes cluster
Make - Build automation tool
Go (v1.21 or later) - Required for the quickstart automation script

Start Docker and give it enough memory

Armada runs inside Docker, so Docker must be running the whole time you use Armada. Armada's supporting services use about 6 GB of memory before you run anything.

In Docker Desktop, open Settings → Resources and set memory to at least 8 GB, then make sure Docker is running.

Check everything at once:

docker info > /dev/null && echo "Docker is running"
kubectl version --client
helm version
kind version
go version

Ready when: you see Docker is running and a version for each tool, with Go at 1.21 or later.

Make sure no old install is in the way

The install creates a Kind cluster called armada (kubectl calls it kind-armada).

kind get clusters

Ready when: it prints No kind clusters found.

If it lists armada, delete the old install first. From the armada-operator folder you installed from before:

make kind-delete-cluster

Or, from anywhere:

kind delete cluster --name armada

1. Install Armada

Download the Armada Operator

mkdir -p ~/armada-guide
cd ~/armada-guide
git clone https://github.com/armadaproject/armada-operator.git
cd armada-operator

Run the install

make kind-all

This one command:

Creates a Kind cluster called armada
Installs the services Armada depends on (PostgreSQL, Pulsar, and Redis)
Installs Armada
Installs armadactl into ~/bin
Writes ~/.armadactl.yaml, which points armadactl at your new install (localhost:30002)

This takes about 10 minutes, longer the first time while images download. It’s finished when a line ends in condition met and you get your prompt back. If you already have a ~/.armadactl.yaml, back it up first — the install replaces it.

2. Check Armada is running

kubectl get pods -n armada

Success: you see these pods, most of them Running:

Output

armada-event-ingester-... 1/1 Running
armada-executor-... 1/1 Running
armada-lookout-... 1/1 Running
armada-lookout-ingester-... 1/1 Running
armada-lookout-migration-... 0/1 Completed
armada-scheduler-... 1/1 Running
armada-scheduler-ingester-... 1/1 Running
armada-scheduler-migration-... 0/1 Completed
armada-server-... 1/1 Running

Now check that armadactl can reach Armada:

armadactl get queues

Success: it prints no line containing error:

Output

apiVersion: armadaproject.io/v1beta1
kind: Queue
[]

Wait two minutes before Step 3. After its pods start, Armada takes a little time to learn how much CPU and memory the cluster has. A job submitted before then is rejected with exceeds the total limit.

3. Run your first job

Create a queue

armadactl create queue example

Response: Created queue example

Wait about 10 seconds before submitting. Armada checks for new queues every 10 seconds — submitting to a brand-new queue straight away fails with could not find queue.

Submit a job

This command submits the example job and automatically captures its ID into a variable called JOB_ID so you can reference it in later commands.

JOB_ID=$(armadactl submit dev/quickstart/example-job.yaml | awk '{print $5}')
echo "Job ID: $JOB_ID"

Response: Job ID: <JOB_ID>

JOB_ID only lasts in this terminal window. If you open a new one, set it again: JOB_ID=<JOB-ID> (with your own ID). This job starts a small Linux container that prints Hello Armada and exits.

Watch the job

armadactl watch example job-set-1

Response:

Output

Watching job set job-set-1
Month day time | Queued: 0, Leased: 0, ... | JobSubmittedEvent, job id: <job-id>
Month day time | Queued: 1, Leased: 0, ... | JobQueuedEvent, job id: <job-id>
Month day time | Queued: 0, Leased: 1, ... | JobLeasedEvent, job id: <job-id>
Month day time | Queued: 0, Leased: 0, Pending: 1, ... | JobPendingEvent, job id: <job-id> pod: 0
Month day time | Queued: 0, Leased: 0, ..., Succeeded: 1, ... | JobSucceededEvent, job id: <job-id> pod: 0

The job moves through: Queued → Leased → Pending → Running → Succeeded. A short job can finish before Armada reports it as Running, so you may not see that line.

watch keeps running after the job finishes. Press Ctrl-C to stop it.

4. See the job's output

kubectl logs -n default armada-$JOB_ID-0

Response: Hello Armada

Run this within a few minutes of the job succeeding. Armada deletes finished pods about three minutes after the job ends, and their output goes with them. If you see pods "armada-[job-id]-0" not found, the pod is already gone. Submit a new job and run kubectl logs immediately after watch shows JobSucceededEvent.

5. Open Lookout

Open http://localhost:30000 in your browser.

Success: your job appears in the list, in queue example. Click it to see its details, the YAML you submitted, and its run history.

On a laptop install, Lookout’s Logs tab shows TypeError: Failed to fetch. That’s expected — it needs a log service the laptop install doesn’t include. Use kubectl logs from Step 4 instead.

Keeping your install working

Keep Docker running. If Docker quits or restarts, the Kind cluster comes back but Armada doesn't recover. Reinstall it — see Troubleshooting.
Your setup is reset by a reinstall. Queues and job history are lost, so recreate any queues you need.

Clean up

When you're done, delete the cluster and everything in it:

cd ~/armada-guide/armada-operator
make kind-delete-cluster

Response: Deleted nodes: [...]

Troubleshooting

Still have questions?

Ask in the #armada channel on CNCF Slack or browse the community page.

Join #armada on Slack

Community page

Docker isn't running — failed to connect to the docker API

node(s) already exist for a cluster with the name "armada"

command not found: armadactl

The connection to the server localhost:8080 was refused from kubectl

connection refused from armadactl

relation "queue" does not exist

could not find queue "example"

watch says the job set does not exist

Job is rejected with exceeds the total limit

Job is rejected with insufficient resources available

kubectl logs says the pod was NotFound

Lookout Logs tab shows TypeError: Failed to fetch

zsh: no such file or directory: job-id

kubectl logs says pods "armada--0" not found

Commands fail after Docker or your computer restarted

On this page