fix(docs): update getting started instructions

[scottslowe]

Thanks for contributing! Please ensure your pull request adheres to the following guidelines:

• All commits contain a well written commit message and are signed-off (see Submitting a pull request).
• All code is covered by unit and/or end-to-end tests where feasible.
• All generated files are updated if needed (see Making changes).
• Provide a title or release-note blurb suitable for the release notes (see guidelines).
• Update documentation and write an upgrade note if needed (see guidelines).
• Are you a user of Tetragon? Please add yourself to the Users doc in the Cilium repository.

Update Kubernetes install instructions to call out single node cluster assumption.

Update execution monitoring instructions to provide commands for using multi-node clusters.

Fixes #2680

[netlify]

✅ Deploy Preview for tetragon ready!

Name	Link
🔨 Latest commit	bc4204e
🔍 Latest deploy log	https://app.netlify.com/sites/tetragon/deploys/669a867db9b3560007c114de
😎 Deploy Preview	https://deploy-preview-2681--tetragon.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mtardy]

Hey, thanks for opening that PR.

However, having those two different paths might overcomplicate the getting-started. I feel like we could use this command:

POD=$(kubectl get pod -l 'app.kubernetes.io/name=tetragon' -o name -n kube-system --field-selector spec.nodeName=$(kubectl get pod xwing -o=jsonpath='{.spec.nodeName}')); kubectl exec -ti -n kube-system $POD -c tetragon -- tetra getevents -o compact --pods xwing

To replace the existing:

kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing

I haven't found a way to make it simpler, the better option would have been to create the xwing pod directly on the first node of the daemonset so that ds/tetragon directly selects the appropriate node but this is impossible if we continue to use the .yaml file of cilium. We could just deploy the xwing using kubectl run but the final getting started guide uses the deathstar thingie. So maybe it's simpler to just use a more complicated command to run on the appropriate tetragon node.

The other solution would have been to use the aggregated logs:

kubectl logs -l app.kubernetes.io/name=tetragon -c export-stdout -f -n kube-system | kubectl exec -i -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing

But this contains historic data which can be confusing for the user I guess!

So I would suggest to replace all the command with the one retrieving the correct tetragon POD. You can find all those references using:

$ grep -nr "kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing" docs
docs/content/en/docs/getting-started/execution.md:21:kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing
docs/content/en/docs/getting-started/enforcement.md:70:kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing
docs/content/en/docs/getting-started/enforcement.md:134:kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing
docs/content/en/docs/getting-started/network.md:46: kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing --processes curl
docs/content/en/docs/getting-started/file-events.md:43:kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing

[scottslowe]

@mtardy I'm not sure that one long command is any better for users than taking a bit of space to explain what needs to be done and why. IMHO, it's clearer to explain what needs to be done, provide commands for each step, and then (at/near the end) provide a single command that encapsulates everything. I'll also point out that users with single node clusters can follow the multi-node instructions without any errors (they're just taking additional steps that aren't necessary at this moment).

To reduce any potential confusion, what do you think about restructuring the tabs to show:

• Kubernetes (single node)
• Kubernetes (multi-node)
• Docker

And then providing instructions in each section? It adds some complexity to the docs themselves, but provides clear distinction/separation for users on what set of instructions to follow.

[scottslowe]

@mtardy I'd also suggest that we focus on fixing only the "Execution Monitoring" section in this PR. Once we are happy with how it looks and works, then I can file an additional PR to model the same changes in the other sections. I think this would make reviews easier (smaller change sets to review).

[mtardy]

@mtardy I'm not sure that one long command is any better for users than taking a bit of space to explain what needs to be done and why. IMHO, it's clearer to explain what needs to be done, provide commands for each step, and then (at/near the end) provide a single command that encapsulates everything. I'll also point out that users with single node clusters can follow the multi-node instructions without any errors (they're just taking additional steps that aren't necessary at this moment).

To reduce any potential confusion, what do you think about restructuring the tabs to show:

• Kubernetes (single node)
• Kubernetes (multi-node)
• Docker

And then providing instructions in each section? It adds some complexity to the docs themselves, but provides clear distinction/separation for users on what set of instructions to follow.

yeah that's a good idea as well. I just want to avoid the proposed changes that are confusing because we end up with 4 commands and a lot of text instead of one command.

On that:

IMHO, it's clearer to explain what needs to be done, provide commands for each step, and then (at/near the end) provide a single command that encapsulates everything.

I think I don't agree, for a "getting started" quick guide, it might be more valuable to show results as fast as possible and then explain. I would say for a more in-depth part of the doc yes but maybe not here.

I'd also suggest that we focus on fixing only the "Execution Monitoring" section in this PR. Once we are happy with how it looks and works, then I can file an additional PR to model the same changes in the other sections. I think this would make reviews easier (smaller change sets to review).

It's up to you, I don't mind. I find it okay to review any case.

[mtardy]

For the record, I'm not a fan of a long command that doesn't explain what it's doing.

I'd rather get these changes into the docs than get hung up on a minor difference of opinion, so I've added the two commands as suggested above in commit bc4204e.

I agree this is debatable!

I'd even merge the Kubernetes single node and Kubernetes multiple node to simplify further but this is way better than previously thanks! :)

[mtardy]

I forgot to ask for squashing the commits oups

[mtardy]

btw why did we change that? I think running interactively was fine to get the logs and everything.

[scottslowe]

This made things a bit more similar between Docker and Kubernetes.

[mtardy]

forgot to add to remove shell

[scottslowe]

So you want no language designator here, just the backticks?

[mtardy]

yes, it's a nit again, but it makes the input look different than the output, this is subtle but this is the convention we have in the doc: