docs: Improve quickstart flow and installation docs. Fixes argoproj#9398

(argoproj#9421) * docs: Improve quickstart flow and installation docs. Fixes argoproj#9398 Signed-off-by: Tim Collins <[email protected]> * docs: Improve quickstart flow and installation docs. Fixes argoproj#9398 Signed-off-by: Tim Collins <[email protected]> * docs: Link user to configuration options Signed-off-by: Tim Collins <[email protected]> * docs: Clarify headings Signed-off-by: Tim Collins <[email protected]> * docs: Address feedback Signed-off-by: Tim Collins <[email protected]> * docs: Improve argo-serve patch explanation Signed-off-by: Tim Collins <[email protected]> Signed-off-by: Tim Collins <[email protected]>
aarushisoni · Aug 26, 2022 · e90d937 · e90d937
1 parent ff41099
commit e90d937
Show file tree

Hide file tree

Showing 3 changed files with 81 additions and 20 deletions.
diff --git a/.spelling b/.spelling
@@ -141,6 +141,7 @@ instantiator
 instantiators
 jenkins
 k3d
+k3s
 k8s-jobs
 kube
 kubelet
@@ -151,6 +152,7 @@ memoized
 memoizing
 mentee
 mentees
+minikube
 mutex
 namespace
 namespaces

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,28 +1,40 @@
 # Installation
 
-## Argo on Desktop
+## Non-production installation
 
-Use the [quick-start manifests](quick-start.md).
+If you just want to try out Argo Workflows in a non-production environment (including on desktop via minikube/kind/k3d etc) follow the [quick-start guide](quick-start.md).
 
-## Argo in Production
+## Production installation
 
-Determine your base installation option.
+### Installation Methods
 
-* A **cluster install** will watch and execute workflows in all namespaces.
-* A **namespace install** only executes workflows in the namespace it is installed in (typically `argo`).
-* A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).
+#### Official release manifests
 
-⚠️ `latest` is tip, not stable. Never run it. Make sure you're using the manifests attached to each Github release. See [this link](https://github.com/argoproj/argo-workflows/releases/latest) for the most recent manifests.
+To install Argo Workflows, navigate to the [releases page](https://github.com/argoproj/argo-workflows/releases/latest) and find the release you wish to use (the latest full release is preferred). Scroll down to the `Controller and Server` section and execute the `kubectl` commands.
 
-⚠️ Double-check you have the right version of your executor configured, it's easy to miss.
+You can use Kustomize to patch your preferred [configurations](managed-namespace.md) on top of the base manifest.
 
 ⚠️ If you are using GitOps, never use Kustomize remote base: this is dangerous. Instead, copy the manifests into your Git repo.
 
+⚠️ `latest` is tip, not stable. Never run it in production.
+
+#### Argo Workflows Helm Chart
+
+You can install Argo Workflows using the community maintained [Helm charts](https://github.com/argoproj/argo-helm).
+
+## Installation options
+
+Determine your base installation option.
+
+* A **cluster install** will watch and execute workflows in all namespaces. This is the default installation option when installing using the official release manifests.
+* A **namespace install** only executes workflows in the namespace it is installed in (typically `argo`). Look for `namespace-install.yaml` in the [release assets](https://github.com/argoproj/argo-workflows/releases/latest).
+* A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).
+
+## Additional installation considerations
+
 Review the following:
 
 * [Security](security.md).
 * [Scaling](scaling.md) and [running at massive scale](running-at-massive-scale.md).
 * [High-availability](high-availability.md)
 * [Disaster recovery](disaster-recovery.md)
-
-Read the [release guide](releases.md) before any major upgrade to be aware of breaking changes.
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -1,31 +1,62 @@
 # Quick Start
 
-To see how Argo Workflows work, you can install it and run examples of simple workflows and workflows that use artifacts.
+To see how Argo Workflows work, you can install it and run examples of simple workflows.
 
-Before you start you need a Kubernetes cluster and `kubectl` set-up
+Before you start you need a Kubernetes cluster and `kubectl` set up to be able to access that cluster. For the purposes of getting up and running, a local cluster is fine. You could consider the following local Kubernetes cluster options:
+
+* [minikube](https://minikube.sigs.k8s.io/docs/)
+* [kind](https://kind.sigs.k8s.io/)
+* [k3s](https://k3s.io/) or [k3d](https://k3d.io/)
+* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+
+⚠️ These instructions are intended to help you get started quickly. They are not suitable in production. For production installs, please refer to [the installation documentation](installation.md) ⚠️
 
 ## Install Argo Workflows
 
-To get started quickly, you can use the quick start manifest which will install Argo Workflows as well as some commonly used components:
+To install Argo Workflows, navigate to the [releases page](https://github.com/argoproj/argo-workflows/releases/latest) and find the release you wish to use (the latest full release is preferred).
+
+Scroll down to the `Controller and Server` section and execute the `kubectl` commands.
+
+Below is an example of the install commands, ensure that you update the command to install the correct version number:
+
+```yaml
+kubectl create namespace argo
+kubectl apply -n argo -f https://github.com/argoproj/argo-workflows/releases/download/v<<ARGO_WORKFLOWS_VERSION>>/install.yaml
+```
 
-⚠️ These manifests are intended to help you get started quickly. They are not suitable in production. They contain hard-coded passwords that are publicly available.
+### Patch argo-server authentication
+
+The argo-server (and thus the UI) defaults to client authentication, which requires clients to provide their Kubernetes bearer token in order to authenticate. For more information, refer to the [Argo Server Auth Mode documentation](argo-server-auth-mode.md). We will switch the authentication mode to `server` so that we can bypass the UI login for now:
 
 ```bash
-kubectl create ns argo
-kubectl apply -n argo -f https://raw.githubusercontent.com/argoproj/argo-workflows/master/manifests/quick-start-postgres.yaml
+kubectl patch deployment \
+  argo-server \
+  --namespace argo \
+  --type='json' \
+  -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/args", "value": [
+  "server",
+  "--auth-mode=server"
+]}]'
+
 ```
 
+### Port-forward the UI
+
 Open a port-forward so you can access the UI:
 
 ```bash
 kubectl -n argo port-forward deployment/argo-server 2746:2746
 ```
 
-This will serve the UI on <https://localhost:2746>
+This will serve the UI on <https://localhost:2746>. Due to the self-signed certificate, you will receive a TLS error which you will need to manually approve.
+
+## Install the Argo Workflows CLI
+
+Next, Download the latest Argo CLI from the same [releases page](https://github.com/argoproj/argo-workflows/releases/latest).
 
-Next, Download the latest Argo CLI from our [releases page](https://github.com/argoproj/argo-workflows/releases/latest).
+## Submitting an example workflow
 
-Finally, submit an example workflow:  
+### Submit an example workflow (CLI)
 
 ```bash
 argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo-workflows/master/examples/hello-world.yaml
@@ -59,5 +90,21 @@ You can also observe the logs of the Workflow run by running the following:
 argo logs -n argo @latest
 ```
 
+### Submit an example workflow (GUI)
+
+* Open a port-forward so you can access the UI:
+
+```bash
+kubectl -n argo port-forward deployment/argo-server 2746:2746
+```
+
+* Navigate your browser to <https://localhost:2746>.
+
+* Click `+ Submit New Workflow` and then `Edit using full workflow options`
+
+* You can find an example workflow already in the text field. Press `+ Create` to start the workflow.
+
+## Trying Workflows without a Kubernetes cluster
+
 💡 If you want to try out Argo Workflows and don't want to set up a Kubernetes cluster, the community is working on a replacement for the old Katacoda course since
 Katacoda was shut down. Please give a thumbs up or comment on [this issue](https://github.com/argoproj/argo-workflows/issues/8899) with your support and feedback.