docs: Refactored and cleaned up docs (argoproj#1856)

panicboat · Dec 16, 2019 · 4b96172 · 4b96172
1 parent 6ba4598
commit 4b96172
Show file tree

Hide file tree

Showing 18 changed files with 231 additions and 236 deletions.
diff --git a/Branding Assets.md b/Branding Assets.md
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 # Argoproj - Get stuff done with Kubernetes
 
-![Argo Image](argo.png)
+![Argo Image](docs/assets/argo.png)
 
 ## Quickstart
 ```bash
@@ -47,9 +47,9 @@ Argo Workflows is an open source container-native workflow engine for orchestrat
 * Argo Workflows puts a cloud-scale supercomputer at your fingertips!
 
 ## Documentation
-* [Get started here](demo.md)
+* [Get started here](docs/getting-started.md)
 * [How to write Argo Workflow specs](examples/README.md)
-* [How to configure your artifact repository](ARTIFACT_REPO.md)
+* [How to configure your artifact repository](docs/configure-artifact-repository.md)
 
 ## Features
 * DAG or Steps based declaration of workflows

diff --git a/argo-logo600.png b/argo-logo600.png
diff --git a/CONTRIBUTING.md → docs/CONTRIBUTING.md b/CONTRIBUTING.md → docs/CONTRIBUTING.md
diff --git a/docs/README.md b/docs/README.md
@@ -1,10 +1,19 @@
 # Argo Documentation
 
-## [Getting Started](../demo.md)
+### Getting Started
 
-## Features
+For set-up information and running your first Workflows, please see our [Getting Started](getting-started.md) guide.
+
+### Documentation
+
+For detailed examples about what Argo can do, please see our [Argo Workflows: Documentation by Example](../examples/README.md) page.
+
+### Features
+Some use-case specific documentation is available:
+* [Architecture](architecture.md)
 * [Controller Configuration](workflow-controller-configmap.yaml)
 * [RBAC](workflow-rbac.md)
+* [Releasing](releasing.md)
 * [REST API](rest-api.md)
-* [Workflow Variables](variables.md)
 * [Workflow Executors](workflow-executors.md)
+* [Workflow Variables](variables.md)
diff --git a/ARCHITECTURE.md → docs/architecture.md b/ARCHITECTURE.md → docs/architecture.md
@@ -2,10 +2,10 @@
 
 ## Argo Workflow Overview
 
-![diagram](overview.jpeg)
+![diagram](assets/overview.jpeg)
 
 
 ## Workflow controller architecture
 
-![diagram](architecture.jpeg)
+![diagram](assets/architecture.jpeg)
 
diff --git a/architecture.jpeg → docs/assets/architecture.jpeg b/architecture.jpeg → docs/assets/architecture.jpeg
diff --git a/argo.png → docs/assets/argo.png b/argo.png → docs/assets/argo.png
diff --git a/overview.jpeg → docs/assets/overview.jpeg b/overview.jpeg → docs/assets/overview.jpeg
diff --git a/ARTIFACT_REPO.md → docs/configure-artifact-repository.md b/ARTIFACT_REPO.md → docs/configure-artifact-repository.md
diff --git a/demo.md → docs/getting-started.md b/demo.md → docs/getting-started.md
@@ -1,57 +1,99 @@
-# Argo Getting Started
+# Getting Started
 
 To see how Argo works, you can run examples of simple workflows and workflows that use artifacts.
 For the latter, you'll set up an artifact repository for storing the artifacts that are passed in
 the workflows. Here are the requirements and steps to run the workflows.
 
-## Requirements
-* Installed Kubernetes 1.9 or later
-* Installed [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
-* Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`).
+## 0. Requirements
+* Kubernetes 1.9 or later
+* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+* Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`)
 
-## 1. Download Argo
+## 1. Download the Argo CLI
 
-Download the latest Argo binary version from https://github.com/argoproj/argo/releases/latest.
+### Mac
 
-Also available in Mac Homebrew:
-```
+Available via `brew`
+```sh
 brew install argoproj/tap/argo
 ```
+And via `curl`
+```sh
+# Download the binary
+curl -sLO https://github.com/argoproj/argo/releases/download/v2.4.3/argo-darwin-amd64
+
+# Make binary executable
+chmod +x argo-darwin-amd64
 
-Also you can use this command to install for Linux 
+# Move binary to path
+mv ./argo-darwin-amd64 /usr/local/bin/argo
 
+# Test installation
+argo version
 ```
-curl -sSL -o /usr/local/bin/argo https://github.com/argoproj/argo/releases/download/v2.4.2/argo-linux-amd64
-chmod +x /usr/local/bin/argo
+
+### Linux
+
+Available via `curl`
+```sh
+# Download the binary
+curl -sLO https://github.com/argoproj/argo/releases/download/v2.4.3/argo-linux-amd64
+
+# Make binary executable
+chmod +x argo-darwin-amd64
+
+# Move binary to path
+mv ./argo-darwin-amd64 /usr/local/bin/argo
+
+# Test installation
+argo version
 ```
 
+### Binaries
+
+You can download the latest and previous Argo binaries from our [releases page](https://github.com/argoproj/argo/releases/).
+
 ## 2. Install the Controller and UI
-```
+```sh
 kubectl create namespace argo
-kubectl apply -n argo -f https://raw.githubusercontent.com/argoproj/argo/stable/manifests/install.yaml
-```
-NOTE: On GKE, you may need to grant your account the ability to create new clusterroles
+kubectl apply -n argo -f https://raw.githubusercontent.com/argoproj/argo/v2.4.3/manifests/install.yaml
 ```
+NOTE: On GKE, you may need to grant your account the ability to create new `clusterrole`s
+```sh
 kubectl create clusterrolebinding YOURNAME-cluster-admin-binding --clusterrole=cluster-admin --user=YOUREMAIL@gmail.com
 ```
 
-## 3. Configure the service account to run workflows
+## 3. Configure the service account to run Workflows
 
-To run all of the examples in this guide, the 'default' service account is too limited to support
-features such as artifacts, outputs, access to secrets, etc... For demo purposes, run the following
-command to grant admin privileges to the 'default' service account in the namespace 'default'. Make sure you are on the 'default' namespace before running them.
-```
-kubectl create rolebinding default-admin --clusterrole=admin --serviceaccount=default:default
-```
-For the bare minimum set of privileges which a workflow needs to function, see
-[Workflow RBAC](docs/workflow-rbac.md). You can also submit workflows which run with a different
-service account using:
-```
+### Roles, RoleBindings, and ServiceAccounts
+
+In order for Argo to support features such as artifacts, outputs, access to secrets, etc. it needs to communicate with Kubernetes resources
+using the Kubernetes API. To communicate with the Kubernetes API, Argo uses a `ServiceAccount` to authenticate itself to the Kubernetes API.
+You can specify which `Role` (i.e. which permissions) the `ServiceAccount` that Argo uses by binding a `Role` to a `ServiceAccount` using a `RoleBinding`
+
+Then, when submitting Workflows you can specify which `ServiceAccount` Argo uses using:
+
+```sh
 argo submit --serviceaccount <name>
 ```
 
-## 4. Run Simple Example Workflows
+When no `ServiceAccount` is provided, Argo will use the `default` `ServiceAccount` from the namespace from which it is run, which will almost always have insufficient privileges by default.
+
+For more information about granting Argo the necessary permissions for your use case see [Workflow RBAC](workflow-rbac.md).
+
+### Granting admin privileges
+
+For the purposes of this demo, we will grant the `default` `ServiceAccount` admin privileges (i.e., we will bind the `admin` `Role` to the `default` `ServiceAccount` of the current namespace):
+
+```sh
+kubectl create rolebinding default-admin --clusterrole=admin --serviceaccount=default:default
 ```
+
+**Note that this will grant admin privilages to the `default` `ServiceAccount` in the namespace that the command is run from, so you will only be able to
+run Workflows in the namespace where the `RoleBinding` was made.**
+
+## 4. Run Sample Workflows
+```sh
 argo submit --watch https://raw.githubusercontent.com/argoproj/argo/master/examples/hello-world.yaml
 argo submit --watch https://raw.githubusercontent.com/argoproj/argo/master/examples/coinflip.yaml
 argo submit --watch https://raw.githubusercontent.com/argoproj/argo/master/examples/loops-maps.yaml
@@ -60,27 +102,28 @@ argo get xxx-workflow-name-xxx
 argo logs xxx-pod-name-xxx #from get command above
 ```
 
-Make sure you run these examples while on the `default` namespace (since we granted admin privileges only within `default` on the previous step).
+Additional examples and more information about the CLI are available on the [Argo Workflows by Example](../examples/README.md) page.
 
-You can also create workflows directly with kubectl. However, the Argo CLI offers extra features
-that kubectl does not, such as YAML validation, workflow visualization, parameter passing, retries
+You can also create Workflows directly with `kubectl`. However, the Argo CLI offers extra features
+that `kubectl` does not, such as YAML validation, workflow visualization, parameter passing, retries
 and resubmits, suspend and resume, and more.
-```
+```sh
 kubectl create -f https://raw.githubusercontent.com/argoproj/argo/master/examples/hello-world.yaml
 kubectl get wf
 kubectl get wf hello-world-xxx
 kubectl get po --selector=workflows.argoproj.io/workflow=hello-world-xxx --show-all
 kubectl logs hello-world-yyy -c main
 ```
 
-Additional examples are available [here](https://github.com/argoproj/argo/blob/master/examples/README.md).
 
 ## 5. Install an Artifact Repository
 
-Argo supports S3 (AWS, GCS, Minio) as well as Artifactory as artifact repositories. This tutorial
-uses Minio for the sake of portability. Instructions on how to configure other artifact repositories
-are [here](https://github.com/argoproj/argo/blob/master/ARTIFACT_REPO.md).
-```
+Argo supports S3 (AWS, GCS, Minio) and Artifactory as artifact repositories. Instructions on how to configure artifact repositories are available on the [Configuring your Artifact Repository](configure-artifact-repository.md) page.
+
+This tutorial uses Minio for the sake of portability.
+
+Install Minio:
+```sh
 helm install stable/minio \
   --name argo-artifacts \
   --set service.type=LoadBalancer \
@@ -91,28 +134,32 @@ helm install stable/minio \
 ```
 
 Login to the Minio UI using a web browser (port 9000) after exposing obtaining the external IP using `kubectl`.
-```
+```sh
 kubectl -n argo get service argo-artifacts -o wide
 ```
 On Minikube:
-```
+```sh
 minikube -n argo service --url argo-artifacts
 ```
 
 NOTE: When minio is installed via Helm, it uses the following hard-wired default credentials,
 which you will use to login to the UI:
-* AccessKey: AKIAIOSFODNN7EXAMPLE
-* SecretKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+* AccessKey: `AKIAIOSFODNN7EXAMPLE`
+* SecretKey: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
 
 Create a bucket named `my-bucket` from the Minio UI.
 
 ## 6. Reconfigure the workflow controller to use the Minio artifact repository
 
-Edit the workflow-controller config map to reference the service name (argo-artifacts) and
-secret (argo-artifacts) created by the helm install:
-```
+Edit the `workflow-controller` `ConfigMap` to reference the service name (`argo-artifacts`) and
+secret (`argo-artifacts`) created by the Helm install:
+
+Edit the `workflow-controller` `ConfigMap`:
+```sh
 kubectl edit cm -n argo workflow-controller-configmap
-...
+```
+Add the following:
+```yaml
 data:
   config: |
     artifactRepository:
@@ -133,35 +180,35 @@ data:
           key: secretkey
 ```
 
-NOTE: the Minio secret is retrieved from the namespace you use to run workflows. If Minio is
+NOTE: the Minio secret is retrieved from the namespace you use to run Workflows. If Minio is
 installed in a different namespace then you will need to create a copy of its secret in the
-namespace you use for workflows.
+namespace you use for Workflows.
 
 ## 7. Run a workflow which uses artifacts
-```
+```sh
 argo submit https://raw.githubusercontent.com/argoproj/argo/master/examples/artifact-passing.yaml
 ```
 
 ## 8. Access the Argo UI
 
 By default, the Argo UI service is not exposed with an external IP. To access the UI, use one of the
-following methods:
+following:
 
-#### Method 1: kubectl port-forward
+### Method 1: kubectl port-forward
 ```
 kubectl -n argo port-forward deployment/argo-ui 8001:8001
 ```
 Then visit: http://127.0.0.1:8001
 
-#### Method 2: kubectl proxy
+### Method 2: kubectl proxy
 ```
 kubectl proxy
 ```
 Then visit: http://127.0.0.1:8001/api/v1/namespaces/argo/services/argo-ui/proxy/
 
 NOTE: artifact download and webconsole is not supported using this method
 
-#### Method 3: Expose a LoadBalancer
+### Method 3: Expose a LoadBalancer
 Update the argo-ui service to be of type `LoadBalancer`.
 ```
 kubectl patch svc argo-ui -n argo -p '{"spec": {"type": "LoadBalancer"}}'

diff --git a/docs/rest-api.md b/docs/rest-api.md
@@ -19,7 +19,7 @@ CRUD operation on custom resource objects.
 ### Golang 
 
 A kubernetes Workflow clientset library is auto-generated under [argoproj/argo/pkg/client](https://github.com/argoproj/argo/tree/master/pkg/client) and can be imported by golang
-applications. See the [golang code example](example-golang/main.go) on how to make use of this client.
+applications. See the [golang code example](../examples/example-golang/main.go) on how to make use of this client.
 
 ### Python
 The python kubernetes client has libraries for interacting with custom objects. See: https://github.com/kubernetes-client/python/blob/master/kubernetes/docs/CustomObjectsApi.md

diff --git a/ROADMAP.md → docs/roadmap.md b/ROADMAP.md → docs/roadmap.md