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.

Sign up for GitHub

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

Jump to bottom

docs: Update Getting Started #3099

Merged
merged 2 commits into from Jun 8, 2020
Merged

docs: Update Getting Started #3099

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f8af861
docs: Update Getting Started
yunhailuo May 25, 2020
1868b16
docs: clarify MinIO installation
yunhailuo May 26, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
38 changes: 20 additions & 18 deletions docs/getting-started.md
View file
Open in desktop
Expand Up @@ -8,6 +8,7 @@ the workflows. Here are the requirements and steps to run the workflows.
* 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`)
* [Helm](https://helm.sh/docs/intro/quickstart/) (Optional): this tutorial uses helm to install MinIO, if you are going to use it (to try out "artifact-passing" for example).

## 1. Download the Argo CLI

Expand Down Expand Up @@ -54,20 +55,20 @@ For more information about granting Argo the necessary permissions for your use
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
kubectl create rolebinding default-admin --clusterrole=admin --serviceaccount=argo:default -n argo
```

**Note that this will grant admin privileges 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
argo list
argo get xxx-workflow-name-xxx
argo logs xxx-pod-name-xxx #from get command above
argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo/master/examples/hello-world.yaml
argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo/master/examples/coinflip.yaml
argo submit -n argo --watch https://raw.githubusercontent.com/argoproj/argo/master/examples/loops-maps.yaml
argo list -n argo
argo get xxx-workflow-name-xxx -n argo
argo logs xxx-pod-name-xxx -n argo #from get command above
```

Additional examples and more information about the CLI are available on the [Argo Workflows by Example](../examples/README.md) page.
Expand All @@ -76,11 +77,11 @@ You can also create Workflows directly with `kubectl`. However, the Argo CLI off
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
kubectl create -n argo -f https://raw.githubusercontent.com/argoproj/argo/master/examples/hello-world.yaml
kubectl get wf -n argo
kubectl get wf hello-world-xxx -n argo
kubectl get po -n argo --selector=workflows.argoproj.io/workflow=hello-world-xxx
kubectl logs hello-world-yyy -c main -n argo
```


Expand All @@ -93,28 +94,29 @@ This tutorial uses Minio for the sake of portability.
Install Minio:
```sh
helm install argo-artifacts stable/minio \
-n argo \
--set service.type=LoadBalancer \
--set defaultBucket.enabled=true \
--set defaultBucket.name=my-bucket \
--set persistence.enabled=false \
--set fullnameOverride=argo-artifacts
```

Login to the Minio UI using a web browser (port 9000) after exposing obtaining the external IP using `kubectl`.
Assuming Minio was installed into the "argo" namespace, the following `kubectl` command will expose the Minio UI. Login to the Minio UI using a web browser (port 9000).
```sh
kubectl get service argo-artifacts -o wide
kubectl get service argo-artifacts -o wide -n argo
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assumes the user has installed Minio into the Argo namespace, which isn't a safe assumption. Not that it's wrong, but we should add context here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree- I think the guide should probably be for installing into the argo namespace, but should state this at the start.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the comment @ntwrkguru . I'm trying to update the document to have everything installed into the argo namespace as stated at the very beginning. Just to clarify, where should this be clarified? Like

5. Install an Artifact Repository
...
Install Minio into the argo namespace:

?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a blurb, like:

 Assuming Minio was installed into the "argo" namespace, the following `kubectl` command will expose the Minio UI. Login to the Minio UI using a web browser (port 9000).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you. Pushed one commit. I assume PRs will be squashed merged? Or should I squash myself?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alexec Were there other "getting started" guides that need to be addressed? Ideally, there would be 1 guide that then could link into the examples or focus areas for more details.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think links could be useful. Just a summary here in case it's helpful. The document currently has

Are there any other documents useful for getting-started?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not that really stand out. I'll follow the guide later and see if I can offer suggestions.

```
On Minikube:
```sh
minikube service --url argo-artifacts
minikube service --url argo-artifacts -n argo
```

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`

Create a bucket named `my-bucket` from the Minio UI.
There should be a bucket named `my-bucket`. If not create one from the Minio UI.

## 6. Reconfigure the workflow controller to use the Minio artifact repository

Expand All @@ -131,7 +133,7 @@ data:
artifactRepository: |
s3:
bucket: my-bucket
endpoint: argo-artifacts.default:9000
endpoint: argo-artifacts:9000
insecure: true
# accessKeySecret and secretKeySecret are secret selectors.
# It references the k8s secret named 'argo-artifacts'
Expand All @@ -152,7 +154,7 @@ 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
argo submit -n argo https://raw.githubusercontent.com/argoproj/argo/master/examples/artifact-passing.yaml
```

## 8. Access the Argo UI
Expand Down