docs: Make https://argoproj.github.io/argo/ (argoproj#3369)

.github/workflows/gh-pages.yaml

@@ -0,0 +1,28 @@
+name: Deploy
+
+on:
+ push:
+ branches:
+ - mkdocs
+ - master
+
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v1
+ - name: Setup Python
+ uses: actions/setup-python@v1
+ with:
+ python-version: 3.x
+ - name: build
+ run: |
+ pip install mkdocs==1.0.4 mkdocs_material==4.1.1
+ mkdocs build
+ mkdir ./site/.circleci && echo '{version: 2, jobs: {build: {branches: {ignore: gh-pages}}}}' > ./site/.circleci/config.yml
+ - name: deploy
+ uses: peaceiris/[email protected]
+ env:
+ PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
+ PUBLISH_BRANCH: gh-pages
+ PUBLISH_DIR: ./site

.gitignore

@@ -26,3 +26,4 @@ git-ask-pass.sh
 /pkg/apiclient/workflow/workflow.swagger.json
 /pkg/apiclient/workflowarchive/workflow-archive.swagger.json
 /pkg/apiclient/workflowtemplate/workflow-template.swagger.json
+/site/

Makefile

@@ -466,7 +466,7 @@ pkg/apiclient/workflow/workflow.swagger.json: proto
 pkg/apiclient/workflowarchive/workflow-archive.swagger.json: proto
 pkg/apiclient/workflowtemplate/workflow-template.swagger.json: proto
 
-pkg/apiclient/_.secondary.swagger.json: hack/secondaryswaggergen.go pkg/apis/workflow/v1alpha1/openapi_generated.go dist/kubernetes.swagger.json
+pkg/apiclient/_.secondary.swagger.json: hack/secondaryswaggergen.go server/static/files.go pkg/apis/workflow/v1alpha1/openapi_generated.go dist/kubernetes.swagger.json
  go run ./hack secondaryswaggergen
 
 # we always ignore the conflicts, so lets automated figuring out how many there will be and just use that
@@ -489,10 +489,13 @@ api/openapi-spec/swagger.json: dist/kubeified.swagger.json
  swagger validate api/openapi-spec/swagger.json
  go test ./api/openapi-spec
 
+docs/swagger.md:
+ npm install -g swagger-markdown
+ swagger-markdown -i api/openapi-spec/swagger.json -o docs/swagger.md
+
 .PHONY: docs
-docs: swagger
- go run ./hack docgen
- go run ./hack readmegen
+docs: api/openapi-spec/swagger.json docs/swagger.md
+ env ARGO_SECURE=false ARGO_INSECURE_SKIP_VERIFY=false ARGO_SERVER= ARGO_INSTANCEID= go run ./hack docgen
 
 # pre-push
 

README.md

@@ -29,7 +29,7 @@ kubectl apply -n argo -f https://raw.githubusercontent.com/argoproj/argo/stable/
 [Official Argo Workflows user list](USERS.md)
 
 ## Documentation
-* [Get started here](docs/getting-started.md)
+* [Get started here](docs/quick-start.md)
 * [How to write Argo Workflow specs](examples/README.md)
 * [How to configure your artifact repository](docs/configure-artifact-repository.md)
 

docs/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Please [raise an issue in Github](https://github.com/argoproj/argo/issues).
 
 ## Code of Conduct
 
-See [code of conduct](../CODE_OF_CONDUCT.md).
+See [code of conduct](https://github.com/argoproj/argo/blob/master/CODE_OF_CONDUCT.md).
 
 ## How To Contribute
 
@@ -22,7 +22,7 @@ To run Argo Workflows locally for development: [running locally](running-locally
 
 ### Test Policy
 
-Changes without either unit or e2e tests are unlikely to be accepted. See [the pull request template](../.github/pull_request_template.md).
+Changes without either unit or e2e tests are unlikely to be accepted. See [the pull request template](https://github.com/argoproj/argo/blob/master/.github/pull_request_template.md).
 
 ### Contributor Workshop
 

docs/README.md

@@ -2,63 +2,12 @@
 
 ### Getting Started
 
-For set-up information and running your first Workflows, please see our [Getting Started](getting-started.md) guide.
+For set-up information and running your first Workflows, please see our [Getting Started](quick-start.md) guide.
 
 ### Examples
 
-For detailed examples about what Argo can do, please see our [Argo Workflows: Documentation by Example](../examples/README.md) page.
+For detailed examples about what Argo can do, please see our [documentation by example](examples/README.md) page.
 
 ### Fields
 
 For a full list of all the fields available in for use in Argo, and a link to examples where each is used, please see [Argo Fields](fields.md).
-
-### Features
-Some use-case specific documentation is available:
-
-* [Contributing](CONTRIBUTING.md)
-* [Access Token](access-token.md)
-* [Argo Workflow Architecture](architecture.md)
-* [Argo Server Auth Mode](argo-server-auth-mode.md)
-* [Argo Server SSO](argo-server-sso.md)
-* [Argo Server](argo-server.md)
-* [Artifact Repository Ref](artifact-repository-ref.md)
-* [Asynchronous Job Pattern](async-pattern.md)
-* [CLI](cli.md)
-* [Cluster Workflow Templates](cluster-workflow-templates.md)
-* [Configuring Your Artifact Repository](configure-artifact-repository.md)
-* [Core Concepts](core-concepts.md)
-* [Cost Optimisation](cost-optimisation.md)
-* [Cron Backfill](cron-backfill.md)
-* [Cron Workflows](cron-workflows.md)
-* [Default Workflow Spec](default-workflow-specs.md)
-* [Enhanced Depends Logic](enhanced-depends-logic.md)
-* [Argo Fields](fields.md)
-* [Getting Started](getting-started.md)
-* [Links](links.md)
-* [Managed Namespace](managed-namespace.md)
-* [Prometheus Metrics](metrics.md)
-* [Node Field Selectors](node-field-selector.md)
-* [Offloading Large Workflows](offloading-large-workflows.md)
-* [Public API](public-api.md)
-* [Release Instructions](releasing.md)
-* [Resource Duration](resource-duration.md)
-* [REST API](rest-api.md)
-* [Running Locally](running-locally.md)
-* [Scaling](scaling.md)
-* [Security](security.md)
-* [Service Accounts](service-accounts.md)
-* [Static Code Analysis](static-code-analysis.md)
-* [Transport Layer Security](tls.md)
-* [Workflow Variables](variables.md)
-* [Versioning](versioning.md)
-* [Windows Container Support](windows.md)
-* [Work Avoidance](work-avoidance.md)
-* [Workflow Archive](workflow-archive.md)
-* [Workflow Controller Configmap](workflow-controller-configmap.md)
-* [Workflow Creator](workflow-creator.md)
-* [Workflow Events](workflow-events.md)
-* [Workflow Executors](workflow-executors.md)
-* [Workflow Notifications](workflow-notifications.md)
-* [Workfow RBAC](workflow-rbac.md)
-* [Workflow Restrictions](workflow-requirements.md)
-* [Workflow Templates](workflow-templates.md)

docs/access-token.md

@@ -4,57 +4,60 @@ If you want to automate tasks with the Argo Server API or CLI, you will need an
 
 Firstly, create a role with minimal permissions. This example role for jenkins only permission to update and list workflows:
 
-```shell script
+```sh
 kubectl create role jenkins --verb=list,update --resource=workflows.argoproj.io 
 ```
 
 Create a service account for your service:
 
-```shell script
+```sh
 kubectl create sa jenkins
 ```
 
 Bind the service account to the role (in this case in the `argo` namespace):
 
-```shell script
+```sh
 kubectl create rolebinding jenkins --role=jenkins --serviceaccount=argo:jenkins
 ```
 
 You now need to get a token:
 
-```shell script
+```sh
 SECRET=$(kubectl -n argo get sa jenkins -o=jsonpath='{.secrets[0].name}')
-ARGO_TOKEN=$(kubectl -n argo get secret $SECRET -o=jsonpath='{.data.token}' | base64 --decode)
+ARGO_TOKEN="Bearer $(kubectl -n argo get secret $SECRET -o=jsonpath='{.data.token}' | base64 --decode)"
 echo $ARGO_TOKEN
-ZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJNkltS...
+Bearer ZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJNkltS...
 ```
 
+!!!NOTE
+ The `ARGO_TOKEN` should always start with "Bearer ".
+
 Use that token with the CLI (you need to set `ARGO_SERVER` too):
 
-```shell script
+```sh
 ARGO_SERVER=https://localhost:2746 
 argo list
 ```
 
 Use that token in your API requests, e.g. to list workflows:
 
-```shell script
-curl https://localhost:2746/api/v1/workflows/argo -H "Authorisation: Bearer $ARGO_TOKEN"
+```sh
+curl https://localhost:2746/api/v1/workflows/argo -H "Authorisation: $ARGO_TOKEN"
 # 200 OK
 ```
 
 You should check you cannot do things you're not allowed!
 
-```shell script
-curl https://localhost:2746/api/v1/workflow-templates/argo -H "Authorisation: Bearer $ARGO_TOKEN"
+```sh
+curl https://localhost:2746/api/v1/workflow-templates/argo -H "Authorisation: $ARGO_TOKEN"
 # 403 error
 ```
 
 ## Token Revocation
 
 Token compromised?
 
-```shell script
+```sh
 kubectl delete secret $SECRET
 ```
 

docs/architecture.md

@@ -1,18 +1,9 @@
-# Argo Workflow Architecture
-
-> v2.5 and after
-
-From v2.5, you can run Argo WF in two modes: "local" and "hosted". 
-
-![diagram](assets/architecture-v2-5.png)
-
-> v2.4 and before
+# Architecture
 
 ## Argo Workflow Overview
 
 ![diagram](assets/overview.jpeg)
 
-
 ## Workflow controller architecture
 
 ![diagram](assets/architecture.jpeg)

docs/argo-server.md

@@ -17,7 +17,7 @@ Use this mode if:
 * You want a drop-in replacement for the Argo UI.
 * If you need to prevent users from directly accessing the database.
 
-Hosted mode is provided as part of the standard [manifests](../manifests), [specifically in argo-server-deployment.yaml](../manifests/base/argo-server/argo-server-deployment.yaml) .
+Hosted mode is provided as part of the standard [manifests](https://github.com/argoproj/argo/blob/master/manifests), [specifically in argo-server-deployment.yaml](https://github.com/argoproj/argo/blob/master/manifests/base/argo-server/argo-server-deployment.yaml) .
 
 ## Local Mode
 
@@ -32,7 +32,7 @@ To run locally:
 argo server
 ```
 
-This will start a server on port 2746 which you can view at [https://localhost:2746](https://localhost:2746]).
+This will start a server on port 2746 which you can view at [https://localhost:2746](https://localhost:2746).
 
 ## Options
 
@@ -56,4 +56,57 @@ See [TLS](tls.md).
 
 ### SSO 
 
-See [SSO](argo-server-sso.md).
+See [SSO](argo-server-sso.md).
+
+
+## Access the Argo Workflows UI
+
+```sh
+kubectl -n argo port-forward deployment/argo-server 2746:2746
+```
+
+Then visit: https://127.0.0.1:2746
+
+By default, the Argo UI service is not exposed with an external IP. To access the UI, use one of the
+following:
+
+### Method 1: kubectl port-forward
+
+```
+kubectl -n argo port-forward deployment/argo-server 2746:2746
+```
+
+Then visit: https://127.0.0.1:8001
+
+### Method 2: kubectl proxy
+
+```
+kubectl 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: Expose a LoadBalancer
+
+Update the argo-ui service to be of 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 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:
+
+```
+minikube service -n argo --url argo-ui
+```

docs/async-pattern.md

@@ -60,10 +60,13 @@ In this case the ```job-cmd``` parameter can be a command that makes an http cal
 
 On job completion the external job would need to call either resume if successful:
 
+You may need an [access token](access-token.md).
+
 ```
 curl --request PUT \
  --url https://localhost:2746/api/v1/workflows/<NAMESPACE>/<WORKFLOWNAME>/resume
  --header 'content-type: application/json' \
+ --header "Authorization: Bearer $ARGO_TOKEN" \
  --data '{
  "namespace": "<NAMESPACE>",
  "name": "<WORKFLOWNAME>",
@@ -77,6 +80,7 @@ or stop if unsuccessful:
 curl --request PUT \
  --url https://localhost:2746/api/v1/workflows/<NAMESPACE>/<WORKFLOWNAME>/stop
  --header 'content-type: application/json' \
+ --header "Authorization: Bearer $ARGO_TOKEN" \
  --data '{
  "namespace": "<NAMESPACE>",
  "name": "<WORKFLOWNAME>",
@@ -94,3 +98,10 @@ Instead you need to use the `--restart-successful` option, eg if using the templ
 ```
 argo retry <WORKFLOWNAME> --restart-successful --node-field-selector templateRef.template=run-external-job,phase=Failed
 ```
+
+See also:
+
+* [access token](access-token.md)
+* [resuming a workflow via automation](resuming-workflow-via-automation.md)
+* [submitting a workflow via automation](submit-workflow-via-automation.md)
+* [one workflow submitting another](workflow-submitting-workflow.md)

docs/cli.md

@@ -1,20 +1,29 @@
 # CLI
 
-Most help topics are provided using built-in help
+The CLI allows to (amongst other things) submit, watch, and list workflows, e.g.: 
+
+```sh
+argo submit my-wf.yaml
+argo list
+``` 
+
+## Reference
+
+You can find [detailed reference here](cli/argo.md)
+
+## Help
+
+Most help topics are provided by built-in help:
 
 ```
 argo --help
 ```
 
-# Argo Server
-
-![GA](assets/ga.svg)
-
-> v2.5 and after
+## Argo Server
 
 You'll need to configure your commands to use the Argo Server if you have [offloaded node status](offloading-large-workflows.md) or are trying to access your [workflow archive](workflow-archive.md). 
 
-To do so, set the ARGO_SERVER environment variable, e.g.:
+To do so, set the `ARGO_SERVER` environment variable, e.g.:
 
 ```
 export ARGO_SERVER=localhost:2746