[DOC] - Major improvements to Argo usage docs

Preliminary Checks

• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/nebari-dev/nebari/discussions

Summary

The Argo docs need lots of love. As a new user coming to the docs to learn to Argo (hera isn't mentioned), there is a lot of important information missing. The docs need to be expanded to include all of the setup involved and cover actual usecases.

Steps to Resolve this Issue

Argo setup

Argo is not included in the base image so users have to install into their local space.

# One-time Setup of the Nebari workspace
# This script downloads and installs Argo.

# Setup Argo CLI
# The CLI will allow us to test Argo from the command line and is also used by Hera workflow management

# Download the binary. Get the url from the latest release page https://github.com/argoproj/argo-workflows/releases
curl -sLO https://github.com/argoproj/argo-workflows/releases/download/v3.4.8/argo-linux-amd64.gz

# Unzip
gunzip argo-linux-amd64.gz

# Make binary executable
chmod +x argo-linux-amd64

# Create argo directory
mkdir -p ~/bin/argo

# Move binary to path
mv ./argo-linux-amd64 ~/bin/argo

# Add alias to profile
echo "" >> ~/.bash_profile
echo "export PATH=\"$HOME/bin/argo:\$PATH\"" >> ~/.bash_profile
echo "alias argo=\"argo-linux-amd64\"" >> ~/.bash_profile
echo "source ~/.bashrc" >> ~/.bash_profile

# Test installation
argo version

Usage

Some env vars are setup for users by default, others need to be set up by the user.

import os
from hera.shared import global_config

os.environ['ARGO_HTTP1'] = "true"
os.environ['ARGO_SECURE'] = "true"
os.environ['KUBECONFIG'] = '/dev/null'

os.environ['HERA_TOKEN'] = os.environ['ARGO_TOKEN']
os.environ['GLOBAL_CONFIG_HOST'] = f"https://{os.environ['ARGO_SERVER'].rsplit(':')[0]}{os.environ['ARGO_BASE_HREF']}/"  # trailing slash required for proper urljoin inside of hera
os.environ['GLOBAL_CONFIG_NAMESPACE'] = os.environ['ARGO_NAMESPACE']

global_config.host = os.environ['GLOBAL_CONFIG_HOST']
global_config.token = os.environ['HERA_TOKEN'] 

A list of the env vars that are being used by Argo and Hera (there may be others):

os.environ['GLOBAL_CONFIG_NAMESPACE']
os.environ['GLOBAL_CONFIG_HOST']
os.environ['HERA_TOKEN']
os.environ['ARGO_TOKEN']
os.environ['GLOBAL_CONFIG_HOST']
os.environ['GLOBAL_CONFIG_NAMESPACE']
os.environ['ARGO_BASE_HREF']
os.environ['ARGO_SERVER']
os.environ['ARGO_NAMESPACE']
os.environ['ARGO_HTTP1']
os.environ['ARGO_SECURE']
os.environ['KUBECONFIG']

Simple hera script to submit a workflow

The simplest possible script for an Argo workflow. Note that Hera is the python api for Argo.

from hera.workflows import Steps, Workflow, script

@script()
def echo(message: str):
    print(message)


with Workflow(
    generate_name="hello-world-hera-",
    entrypoint="steps",
    namespace=os.environ['GLOBAL_CONFIG_NAMESPACE'],
) as w:
    with Steps(name="steps"):
        echo(arguments={"message": "Hello world!"})

w.create()

Locate the Argo usage documentation entry point in this repository and compare it with the setup and Hera examples in the issue. Verify the CLI installation, environment-variable guidance, and simple workflow example; done when a new user can follow the setup and submit a workflow.