Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update website to include better quickstart #3719

Merged
merged 1 commit into from
Jun 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 11 additions & 15 deletions _data/settings.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,26 +25,22 @@ blog_settings:
# Should we display a narrow grid of other posts at the bottom of each blog post?
read_more: "yes"

# Setup your navigation below – how to use the icons:
# Setup your navigation below – how to use the icons:
# 1. See all the icons available here https://demos.creative-tim.com/argon-design-system-pro/docs/1.0/foundation/icons.html
# 2. Get the name of the icon e.g basket, then prefix with ni to make ni-basket.
# 3. Add a color of the icon - text-primary, text-success, text-info, text-danger, text-warning and text-default all work!
# 2. Get the name of the icon e.g basket, then prefix with ni to make ni-basket.
# 3. Add a color of the icon - text-primary, text-success, text-info, text-danger, text-warning and text-default all work!
menu_settings:
menu_items:
- title: 'Design'
url: '/design/'
- title: 'Documentation'
submenu_items:
- title: 'Development'
url: '/developer'
- title: 'Quickstart'
url: '/quickstart'
- title: 'User Guide'
url: '/user'
- title: 'Production Install'
url: '/production-install'
url: '/user'
- title: 'Libraries'
url: '/libraries'
- title: 'Demo'
url: '/demo'
- title: 'Contribute'
url: '/contribute'

Expand All @@ -59,7 +55,7 @@ contact_settings:

social_settings:
facebook_url: ''
discussions_url: 'https://github.com/G-Research/armada/discussions'
discussions_url: 'https://github.com/armadaproject/armada/discussions'
twitter_url: 'https://twitter.com/oss_gr'
instagram_url: ''
youtube_url: ''
Expand All @@ -68,14 +64,14 @@ social_settings:
gitter_url: ''
dribbble_url: ''
behance_url: ''
github_url: 'https://github.com/G-Research/armada'
github_url: 'https://github.com/armadaproject/armada'
reddit_url: ''
linkedin_url: ''
slack_url: 'https://cloud-native.slack.com/archives/C03T9CBCEMC'

authors:

advanced_settings:
analytics_code: 'G-SKPDW30VNF'
header_js:
footer_js:
analytics_code: 'G-SKPDW30VNF'
header_js:
footer_js:
134 changes: 4 additions & 130 deletions quickstart.md
Original file line number Diff line number Diff line change
@@ -1,133 +1,7 @@
# Armada Quickstart
# Quickstart

The purpose of this guide is to install a minimal local Armada deployment for testing and evaluation purposes.
Easiest way to install **Armada** is by using the **Armada Operator**, a Kubernetes operator that manages the lifecycle of **Armada components**.

## Pre-requisites
The operator is available in the [Armada Operator repository](https://github.com/armadaproject/armada-operator).

- Git
- Docker (Docker Desktop recommended for local development on Windows/OSX)
- Helm v3.5+
- Kind v0.11.1+
- Kubectl

## Installation
This guide will install Armada on 3 local Kubernetes clusters; one server and two executor clusters.

You should then clone this repository and step into it:

```bash
git clone https://github.com/G-Research/armada.git
cd armada
```

All commands are intended to be run from the root of the repository.

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.

### One-click Setup

To install Armada and all its dependencies you can use this script:
https://github.com/G-Research/armada/blob/master/docs/local/setup.sh

Likewise this script will remove the Armada components from your system:
https://github.com/G-Research/armada/blob/master/docs/local/destroy.sh


## Usage
Create queues, submit some jobs and monitor progress:

### Queue Creation
```bash
./armadactl create queue queue-a --priorityFactor 1
./armadactl create queue queue-b --priorityFactor 2
```
For queues created in this way, user and group owners of the queue have permissions to:
- submit jobs
- cancel jobs
- reprioritize jobs
- watch queue

For more control, queues can be created via `armadactl create`, which allows for setting specific permission; see the following example.

```bash
./armadactl create -f ./docs/quickstart/queue-a.yaml
./armadactl create -f ./docs/quickstart/queue-b.yaml
```


### Job Submission
```
./armadactl submit ./docs/quickstart/job-queue-a.yaml
./armadactl submit ./docs/quickstart/job-queue-b.yaml
```

Watch individual queues:

```bash
./armadactl watch queue-a job-set-1
```
```bash
./armadactl watch queue-b job-set-1
```

Log in to the Grafana dashboard at [http://localhost:30001](http://localhost:30001) using the default credentials of `admin` / `prom-operator`.
Navigate to the Armada Overview dashboard to get a view of jobs progressing through the system.

Try submitting lots of jobs and see queues get built and processed:

```bash
for i in {1..50}
do
./armadactl submit ./docs/quickstart/job-queue-a.yaml
./armadactl submit ./docs/quickstart/job-queue-b.yaml
done
```

## Example output:

CLI:

```bash
$ ./armadactl watch queue-a job-set-1
Watching job set job-set-1
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
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
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
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
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
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
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
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
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
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
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
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
```


### Grafana Configuration

Run the following commands to setup Grafana in your environment:

```bash
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}'
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}'
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"
```

Grafana:

![Armada Grafana dashboard](./quickstart/grafana-screenshot.png "Armada Grafana dashboard")

Note that the jobs in this demo simply run the `sleep` command so do not consume many resources.

### Lookout Configuration

Armada Lookout UI can be configured by doing the following:

```bash
kubectl port-forward svc/armada-lookout 8080:8080
```
Then access it by opening [http://localhost:8080](http://localhost:8080) in your browser.

![Lookout UI](./quickstart/lookout.png "Lookout UI")
Follow the [Quickstart](https://github.com/armadaproject/armada-operator?tab=readme-ov-file#quickstart) to create your first Armada cluster.
5 changes: 0 additions & 5 deletions quickstart/executor-cluster-monitoring-values.yaml

This file was deleted.

22 changes: 0 additions & 22 deletions quickstart/executor-prometheus-values.yaml

This file was deleted.

11 changes: 0 additions & 11 deletions quickstart/executor-values.yaml

This file was deleted.

Loading