|
1 |
| -# Armada Quickstart |
| 1 | +# Quickstart |
2 | 2 |
|
3 |
| -The purpose of this guide is to install a minimal local Armada deployment for testing and evaluation purposes. |
| 3 | +Easiest way to install **Armada** is by using the **Armada Operator**, a Kubernetes operator that manages the lifecycle of **Armada components**. |
4 | 4 |
|
5 |
| -## Pre-requisites |
| 5 | +The operator is available in the [Armada Operator repository](https://github.com/armadaproject/armada-operator). |
6 | 6 |
|
7 |
| -- Git |
8 |
| -- Docker (Docker Desktop recommended for local development on Windows/OSX) |
9 |
| -- Helm v3.5+ |
10 |
| -- Kind v0.11.1+ |
11 |
| -- Kubectl |
12 |
| - |
13 |
| -## Installation |
14 |
| -This guide will install Armada on 3 local Kubernetes clusters; one server and two executor clusters. |
15 |
| - |
16 |
| -You should then clone this repository and step into it: |
17 |
| - |
18 |
| -```bash |
19 |
| -git clone https://github.com/G-Research/armada.git |
20 |
| -cd armada |
21 |
| -``` |
22 |
| - |
23 |
| -All commands are intended to be run from the root of the repository. |
24 |
| - |
25 |
| -Armada is a resource intensive application due to the need to run multiple Kubernetes clusters - for a local installation you will need at least 16GB of RAM available. |
26 |
| - |
27 |
| -### One-click Setup |
28 |
| - |
29 |
| -To install Armada and all its dependencies you can use this script: |
30 |
| -https://github.com/G-Research/armada/blob/master/docs/local/setup.sh |
31 |
| - |
32 |
| -Likewise this script will remove the Armada components from your system: |
33 |
| -https://github.com/G-Research/armada/blob/master/docs/local/destroy.sh |
34 |
| - |
35 |
| - |
36 |
| -## Usage |
37 |
| -Create queues, submit some jobs and monitor progress: |
38 |
| - |
39 |
| -### Queue Creation |
40 |
| -```bash |
41 |
| -./armadactl create queue queue-a --priorityFactor 1 |
42 |
| -./armadactl create queue queue-b --priorityFactor 2 |
43 |
| -``` |
44 |
| -For queues created in this way, user and group owners of the queue have permissions to: |
45 |
| -- submit jobs |
46 |
| -- cancel jobs |
47 |
| -- reprioritize jobs |
48 |
| -- watch queue |
49 |
| - |
50 |
| -For more control, queues can be created via `armadactl create`, which allows for setting specific permission; see the following example. |
51 |
| - |
52 |
| -```bash |
53 |
| -./armadactl create -f ./docs/quickstart/queue-a.yaml |
54 |
| -./armadactl create -f ./docs/quickstart/queue-b.yaml |
55 |
| -``` |
56 |
| - |
57 |
| - |
58 |
| -### Job Submission |
59 |
| -``` |
60 |
| -./armadactl submit ./docs/quickstart/job-queue-a.yaml |
61 |
| -./armadactl submit ./docs/quickstart/job-queue-b.yaml |
62 |
| -``` |
63 |
| - |
64 |
| -Watch individual queues: |
65 |
| - |
66 |
| -```bash |
67 |
| -./armadactl watch queue-a job-set-1 |
68 |
| -``` |
69 |
| -```bash |
70 |
| -./armadactl watch queue-b job-set-1 |
71 |
| -``` |
72 |
| - |
73 |
| -Log in to the Grafana dashboard at [http://localhost:30001](http://localhost:30001) using the default credentials of `admin` / `prom-operator`. |
74 |
| -Navigate to the Armada Overview dashboard to get a view of jobs progressing through the system. |
75 |
| - |
76 |
| -Try submitting lots of jobs and see queues get built and processed: |
77 |
| - |
78 |
| -```bash |
79 |
| -for i in {1..50} |
80 |
| -do |
81 |
| - ./armadactl submit ./docs/quickstart/job-queue-a.yaml |
82 |
| - ./armadactl submit ./docs/quickstart/job-queue-b.yaml |
83 |
| -done |
84 |
| -``` |
85 |
| - |
86 |
| -## Example output: |
87 |
| - |
88 |
| -CLI: |
89 |
| - |
90 |
| -```bash |
91 |
| -$ ./armadactl watch queue-a job-set-1 |
92 |
| -Watching job set job-set-1 |
93 |
| -Nov 4 11:43:36 | Queued: 0, Leased: 0, Pending: 0, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobSubmittedEvent, job id: 01drv3mey2mzmayf50631tzp9m |
94 |
| -Nov 4 11:43:36 | Queued: 1, Leased: 0, Pending: 0, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobQueuedEvent, job id: 01drv3mey2mzmayf50631tzp9m |
95 |
| -Nov 4 11:43:36 | Queued: 1, Leased: 0, Pending: 0, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobSubmittedEvent, job id: 01drv3mf7b6fd1rraeq1f554fn |
96 |
| -Nov 4 11:43:36 | Queued: 2, Leased: 0, Pending: 0, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobQueuedEvent, job id: 01drv3mf7b6fd1rraeq1f554fn |
97 |
| -Nov 4 11:43:38 | Queued: 1, Leased: 1, Pending: 0, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobLeasedEvent, job id: 01drv3mey2mzmayf50631tzp9m |
98 |
| -Nov 4 11:43:38 | Queued: 0, Leased: 2, Pending: 0, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobLeasedEvent, job id: 01drv3mf7b6fd1rraeq1f554fn |
99 |
| -Nov 4 11:43:38 | Queued: 0, Leased: 1, Pending: 1, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobPendingEvent, job id: 01drv3mey2mzmayf50631tzp9m |
100 |
| -Nov 4 11:43:38 | Queued: 0, Leased: 0, Pending: 2, Running: 0, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobPendingEvent, job id: 01drv3mf7b6fd1rraeq1f554fn |
101 |
| -Nov 4 11:43:41 | Queued: 0, Leased: 0, Pending: 1, Running: 1, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobRunningEvent, job id: 01drv3mf7b6fd1rraeq1f554fn |
102 |
| -Nov 4 11:43:41 | Queued: 0, Leased: 0, Pending: 0, Running: 2, Succeeded: 0, Failed: 0, Cancelled: 0 | event: *api.JobRunningEvent, job id: 01drv3mey2mzmayf50631tzp9m |
103 |
| -Nov 4 11:44:17 | Queued: 0, Leased: 0, Pending: 0, Running: 1, Succeeded: 1, Failed: 0, Cancelled: 0 | event: *api.JobSucceededEvent, job id: 01drv3mf7b6fd1rraeq1f554fn |
104 |
| -Nov 4 11:44:26 | Queued: 0, Leased: 0, Pending: 0, Running: 0, Succeeded: 2, Failed: 0, Cancelled: 0 | event: *api.JobSucceededEvent, job id: 01drv3mey2mzmayf50631tzp9m |
105 |
| -``` |
106 |
| - |
107 |
| - |
108 |
| -### Grafana Configuration |
109 |
| - |
110 |
| -Run the following commands to setup Grafana in your environment: |
111 |
| - |
112 |
| -```bash |
113 |
| -curl -X POST -i http://admin:prom-operator@localhost:30001/api/datasources -H "Content-Type: application/json" -d '{"name":"cluster-0","type":"prometheus","url":"http://'$EXECUTOR_0_IP':30001","access":"proxy","basicAuth":false}' |
114 |
| -curl -X POST -i http://admin:prom-operator@localhost:30001/api/datasources -H "Content-Type: application/json" -d '{"name":"cluster-1","type":"prometheus","url":"http://'$EXECUTOR_1_IP':30001","access":"proxy","basicAuth":false}' |
115 |
| -curl -X POST -i http://admin:prom-operator@localhost:30001/api/dashboards/import --data-binary @./docs/quickstart/grafana-armada-dashboard.json -H "Content-Type: application/json" |
116 |
| -``` |
117 |
| - |
118 |
| -Grafana: |
119 |
| - |
120 |
| - |
121 |
| - |
122 |
| -Note that the jobs in this demo simply run the `sleep` command so do not consume many resources. |
123 |
| - |
124 |
| -### Lookout Configuration |
125 |
| - |
126 |
| -Armada Lookout UI can be configured by doing the following: |
127 |
| - |
128 |
| -```bash |
129 |
| -kubectl port-forward svc/armada-lookout 8080:8080 |
130 |
| -``` |
131 |
| -Then access it by opening [http://localhost:8080](http://localhost:8080) in your browser. |
132 |
| - |
133 |
| - |
| 7 | +Follow the [Quickstart](https://github.com/armadaproject/armada-operator?tab=readme-ov-file#quickstart) to create your first Armada cluster. |
0 commit comments