New Quickstart guide

[kannon92]

Hello,

We have a discussion going on about the audience of the quickstart guide.
I wanted to give a few examples of quickstarts in the open source community.

Airflow Quickstart

Argo Workflows

Kubeflow Pipelines

Volcano Quickstart

Kubeflow has their quickstart guide as a user guide and then they go into much more detail on deployment.

Kubeflow Local Deployments
Kubeflow Cloud Deployments

Some interesting things to gather from open source docs:

1. It is typical that people use code blocks rather than scripts. Some even have copy clipboard functionality embedded in the markdown. You don't see people giving you a script to run.
2. Local deployment is usually lightly touched on. Kind, minikube, k3s are mostly developer ways of testing/running kubernetes locally. They usually have their own special charts/workflows for deployment that is different from production.
3. Guides for walking through deployments on different kubernetes cloud providers.
4. Volcano uses a youtube video for showing deployment which could be useful for us also.

I propose a new quickstart guide with the following layout.

Local Development

• Use of docker-compose and kind/k3s/Minikube
• Close to our development practice as possible
• @richscott is working on this for cleaning up our docker-compose files and aiming to make this more stable for different OS
• IMO kind/Minikube/k3s are pretty fickle ways of deploying kubernetes so I think we should make this the dev way of deployment.

Cloud Deployment

• Provide ways to deploy armada onto a stable kubernetes cluster (AWS, GCP, Azure, etc)
• Ideally, this would be a multi cluster kubernetes environment.
• MVP could be use of Dejan's terraform repo
• The common paradigm for kubernetes applications is to just use an existing cluster and install your charts onto that. We are primary used for multi cluster scheduling so we may need to show examples of creating multiple clusters in these cloud deployments.

Simple User Walkthrough of queue creation, submiting jobs, watching events

[c-rindi]

Thanks for this start, @kannon92.
Adding @dans77777 to join the conversation and effort next week.
I also have some reference links for general "writing good documentation" best practices, that might be a useful resource:

• https://opensource.com/article/20/3/documentation
• https://documentation.divio.com/

[richscott]

Re guides for "local" versus "cloud deployments": I think we should expect that many potential Armada users may be using on-site hardware, with privately hosted and administered K8S clusters. A Helm chart should be usable whatever the underlying K8S hosting entity is, whether it be K8S on local iron, or AWS EKS, etc. The interesting/hard parts about Armada configuration are more about wiring up Pulsar properly, Redis, the Armada server and executor(s), etc.

The core goal of Armada is to allow efficient, coordinated deployment of giant sets of jobs - sets that are so large that a single K8S cluster cannot scale to handle them - so, the target audience will likely be large, well-staffed K8S-running orgs.

Re docs - I've rarely seen Google Docs used as anything more than initial authoring (then exported to other "open" format) tools for OSS projects. Markdown, AsciiDoc, and the other usual suspects are much more popular.