Docs bug: following the quick-start guide _too_ explicitly can get users in trouble

[mfisher87]

Pre-requisites

• I have double-checked my configuration
• I have tested with the :latest image tag (i.e. quay.io/argoproj/workflow-controller:latest) and can confirm the issue still exists on :latest. If not, I have explained why, in detail, in my description below.
• I have searched existing issues and could not find a match for this bug
• I'd like to contribute the fix myself (see contributing guide)

What happened/what did you expect to happen?

Today I followed the quick start guide, and had trouble specifically with this part:

To install Argo Workflows, go to the releases page. Scroll down to the Controller and Server section and execute the kubectl commands.

I did this, which led to me applying install.yaml, not quick-start-minimal.yaml, which I think is what is intended for the quick-start guide. Therefore, when I did the hello-world step, I encountered:

pods "hello-world-xmsc9" is forbidden: User "system:serviceaccount:argo:default" cannot patch resource "pods" in API group "" in the namespace "argo"

This is because the hello-world step depends on resources defined in quick-start-minimal.yaml.

The example command immediately following this instruction does use the correct filename quick-start-minimal.yaml, but I ignored that example command for a few reasons:

• I already copied the command from the GitHub releases page as instructed in 1st paragraph
• Example contains a slug v<<ARGO_WORKFLOWS_VERSION>>, so it's not directly copyable.
• The difference between this command and the command in GitHub release page is hidden because the page isn't wide enough
• The text referred to it as an example, so I did not consider it an "instruction" to follow

Proposed resolution

Replace the language "execute the kubectl commands" with "navigate to quick-start-minimal.yaml, right click, and select 'copy link' to get the correct YAML URL. Craft a kubectl command to apply that yaml following this example: ..."

Or:

Replace the language "execute the kubectl commands" with "to find example kubectl commands."

Add a mkdocs callout of type "danger": "Do not directly execute those commands, as we do not want to apply install.yaml. Instead, we want to use quick-start-minimal.yaml. Here's an example command: ..."

Version

v3.5.6

Paste a small workflow that reproduces the issue. We must be able to run the workflow; don't enter a workflows that uses private images.

Follow quick start guide following instructions too explicitly

Logs from the workflow controller

n/a

Logs from in your workflow's wait container

n/a

[agilgur5]

Follow-up from this Slack thread.

This bug is also due to the change in #12445.

Proposed resolution

I'd suggest something simpler than both (per k8s style guide) as I did on Slack: let's just remove the reference to the releases page entirely. That one should use install.yaml and this one should use quick-start-minimal.yaml.

• The text referred to it as an example, so I did not consider it an "instruction" to follow

Yes, we can change this to no longer be an example and instead be an instruction.

• Example contains a slug v<<ARGO_WORKFLOWS_VERSION>>, so it's not directly copyable.

To make this copyable, we could use an environment variable instead, something like "Set the version of Argo you want to install", then "Run the commands below to install into your cluster"

[mfisher87]

let's just remove the reference to the releases page entirely

I'll plan to open a PR tomorrow!