Skip to content

Commit

Permalink
Update getting started guide with v2.2.0 instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@jessesuen
jessesuen committed Aug 30, 2018
1 parent af636dd commit 36fd194
Showing 1 changed file with 56 additions and 45 deletions.
101 changes: 56 additions & 45 deletions demo.md
View file
Original file line number Diff line number Diff line change
@@ -1,79 +1,85 @@
# Argo 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.
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.8 or later
* Installed the [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool
* 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`).

## 1. Download Argo

On Mac:
```
$ brew install argoproj/tap/argo
brew install argoproj/tap/argo
```
On Linux:
```
$ curl -sSL -o /usr/local/bin/argo https://github.com/argoproj/argo/releases/download/v2.1.1/argo-linux-amd64
$ chmod +x /usr/local/bin/argo
curl -sSL -o /usr/local/bin/argo https://github.com/argoproj/argo/releases/download/v2.2.0/argo-linux-amd64
chmod +x /usr/local/bin/argo
```

## 2. Install the Controller and UI
```
$ argo install
kubectl create ns argo
kubectl apply -n argo -f https://raw.githubusercontent.com/argoproj/argo/v2.2.0/manifests/install.yaml
```
NOTE:
* On GKE with RBAC enabled, you may need to grant your account the ability to create new cluster roles
NOTE: On GKE, you may need to grant your account the ability to create new clusterroles
```
$ kubectl create clusterrolebinding YOURNAME-cluster-admin-binding --clusterrole=cluster-admin [email protected]
kubectl create clusterrolebinding YOURNAME-cluster-admin-binding --clusterrole=cluster-admin [email protected]
```
* The subsequent instructions below assume the installation of argo into the `kube-system` namespace (the default behavior). A different namespace can be chosen using the `argo install --namespace <name>` flag, in which case you should substitute `kube-system` with your chosen namespace in the examples below.

## 3. Configure the service account to run workflows (required for RBAC clusters)
For clusters with RBAC enabled, the 'default' service account is too limited to do any kind of meaningful work. Run the following command to grant admin privileges to the 'default' service account in the namespace 'default':
For clusters with RBAC enabled, the 'default' service account is too limited to support features
like artifacts, outputs, access to secrets, etc... Run the following command to grant admin
privileges to the 'default' service account in the namespace 'default':
```
$ kubectl create rolebinding default-admin --clusterrole=admin --serviceaccount=default:default
kubectl create rolebinding default-admin --clusterrole=admin --serviceaccount=default:default
```
NOTE: You can also submit workflows using a different service account using the `argo submit --serviceaccount <name>` flag.

## 4. Run Simple Example Workflows
```
$ argo submit https://raw.githubusercontent.com/argoproj/argo/master/examples/hello-world.yaml
$ argo submit https://raw.githubusercontent.com/argoproj/argo/master/examples/coinflip.yaml
$ argo submit https://raw.githubusercontent.com/argoproj/argo/master/examples/loops-maps.yaml
$ argo list
$ argo get xxx-workflow-name-xxx
$ argo logs xxx-pod-name-xxx #from get command above
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
argo list
argo get xxx-workflow-name-xxx
argo logs xxx-pod-name-xxx #from get command above
```

You can also run workflows directly with kubectl. However, the Argo CLI offers extra features that kubectl does not, such as YAML validation, workflow visualization, and overall less typing.
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, and overall less typing.
```
$ 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
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 availabe [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) 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).
```
$ brew install kubernetes-helm # mac
$ helm init
$ helm install stable/minio --name argo-artifacts --set service.type=LoadBalancer
brew install kubernetes-helm # mac
helm init
helm install stable/minio --name argo-artifacts --set service.type=LoadBalancer
```

Login to the Minio UI using a web browser (port 9000) after exposing obtaining the external IP using `kubectl`.
```
$ kubectl get service argo-artifacts-minio -o wide
kubectl get service argo-artifacts-minio -o wide
```
On Minikube:
```
$ minikube service --url argo-artifacts-minio
minikube service --url argo-artifacts-minio
```

NOTE: When minio is installed via Helm, it uses the following hard-wired default credentials,
Expand All @@ -85,9 +91,10 @@ 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-minio) and secret (argo-artifacts-minio) created by the helm install:
Edit the workflow-controller config map to reference the service name (argo-artifacts-minio) and
secret (argo-artifacts-minio) created by the helm install:
```
$ kubectl edit configmap workflow-controller-configmap -n kube-system
kubectl edit cm -n argo workflow-controller-configmap
...
data:
config: |
Expand All @@ -109,47 +116,51 @@ data:
key: secretkey
```

The Minio secret is retrived 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.
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.

## 7. Run a workflow which uses artifacts
```
$ argo submit https://raw.githubusercontent.com/argoproj/argo/master/examples/artifact-passing.yaml
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:
By default, the Argo UI service is not exposed with an external IP. To access the UI, use one of the
following methods:

#### Method 1: kubectl port-forward
Run:
```
$ kubectl port-forward $(kubectl get pods -n kube-system -l app=argo-ui -o jsonpath='{.items[0].metadata.name}') -n kube-system 8001:8001
kubectl -n argo port-forward deployment/argo-ui 8001:8001
```
Then visit: https://127.0.0.1:8001/
Then visit: https://127.0.0.1:8001

#### Method 2: kubectl proxy
Run:
```
$ kubectl proxy
kubectl proxy
```
Then visit: https://127.0.0.1:8001/api/v1/namespaces/kube-system/services/argo-ui/proxy/
Then visit: https://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: Use a LoadBalancer
#### Method 3: Expose a LoadBalancer

Update the argo-ui service to be of type `LoadBalancer`.
```
$ kubectl patch svc argo-ui -n kube-system -p '{"spec": {"type": "LoadBalancer"}}'
kubectl patch svc argo-ui -n argo -p '{"spec": {"type": "LoadBalancer"}}'
```
Then wait for the external IP to be made available:
```
$ kubectl get svc argo-ui -n kube-system
kubectl get svc argo-ui -n argo
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
argo-ui LoadBalancer 10.19.255.205 35.197.49.167 80:30999/TCP 1m
```

NOTE: On Minikube, you won't get an external IP after updating the service -- it will always show `pending`. Run the following command to determine the Argo UI URL:
NOTE: On Minikube, you won't get an external IP after updating the service -- it will always show
`pending`. Run the following command to determine the Argo UI URL:
```
$ minikube service -n kube-system --url argo-ui
minikube service -n argo --url argo-ui
```

0 comments on commit 36fd194

Please sign in to comment.