fix(docs): update getting started instructions

docs/content/en/docs/getting-started/execution.md

@@ -4,67 +4,123 @@ weight: 3
 description: "Execution traces with Tetragon"
 ---
 
-At the core of Tetragon is the tracking of all executions in a kubernetes cluster,
-virtual machines, and baremetal systems. This creates the foundation that allows
+At the core of Tetragon is the tracking of all executions in a Kubernetes cluster,
+virtual machines, and bare metal systems. This creates the foundation that allows
 Tetragon to attribute all system behavior back to a specific binary and its
 associated metadata (container, Pod, Node, and cluster).
 
-## Observe Tetragon Execution Events
+## Observe Tetragon execution events
 
-Tetragon exposes the execution trace over JSON logs and GRPC stream. The user
+Tetragon exposes the execution events over JSON logs and GRPC stream. The user
 can then observe all executions in the system.
 
-The following command can be used to observe exec events.
+Use the following instructions to observe execution events. These instructions
+assume you have deployed the Cilium [demo application](https://docs.cilium.io/en/stable/gettingstarted/demo/)
+in your environment.
 
-{{< tabpane lang=shell >}}
-{{< tab Kubernetes >}}
+{{< tabpane text=true >}}
+{{% tab "Kubernetes (single node)" %}}
+
+For a single node Kubernetes cluster, you can target the Tetragon DaemonSet with
+a `kubectl exec` command:
+
+```shell
 kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents -o compact --pods xwing
-{{< /tab >}}
-{{< tab Docker >}}
-docker exec tetragon-container tetra getevents -o compact
-{{< /tab >}}
-{{< /tabpane >}}
+```
+
+This command runs `tetra getevents -o compact --pods xwing` in the single Pod
+that is a member of the Tetragon DaemonSet. Because there is only a single node
+in the cluster, it is guaranteed that the "xwing" Pod will also be running on
+the same node and that Tetragon will be able to capture and report execution
+events.
+
+{{% /tab %}}
+{{% tab "Kubernetes (multiple nodes)" %}}
+
+In a cluster with multiple nodes, you will need to ensure that the Tetragon Pod
+you use is located on the same node as the "xwing" Pod, so that it can capture
+the execution events.
+
+You can use this command to get the name of the Tetragon Pod that is on the same
+Kubernetes node as the "xwing" Pod:
+
+```shell
+POD=$(kubectl -n kubesystem get pods -l 'app.kubernetes.io/name=tetragon' -o name --field-selector spec.nodeName=$(kubectl get pod xwing -o jsonpath='{.spec.nodeName}'))
+```
+
+Once you have the identified the matching Pod, then target it with a `kubectl
+exec` to run the `tetra getevents` command.
+
+```shell
+kubectl exec -ti -n kube-system $POD -c tetragon -- tetra getevents -o compact --pods xwing
+```
 
-This will print a compact form of the exec logs. For an example we do the following
-with the demo application.
+Because the Tetragon Pod where you are running `tetra getevents` in on the same
+node as the "xwing" Pod, the command will return the execution events captured
+by Tetragon.
 
+{{% /tab %}}
+{{% tab Docker %}}
+
+```shell
+docker exec tetragon tetra getevents -o compact
+```
+
+{{% /tab %}}
+{{< /tabpane >}}
+
+The `tetra get-events -o compact` command returns a compact form of the execution
+events. To trigger an execution event, you will run a `curl` command inside the
+"xwing" Pod/container.
 
 {{< tabpane lang=shell >}}
-{{< tab Kubernetes >}}
+{{< tab "Kubernetes (single node)" >}}
+kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon'
+{{< /tab >}}
+{{< tab "Kubernetes (multiple nodes)" >}}
 kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon'
 {{< /tab >}}
 {{< tab Docker >}}
-curl https://ebpf.io/applications/#tetragon
+docker exec -ti starwars-xwing-1 curl https://ebpf.io/applications/#tetragon
 {{< /tab >}}
 {{< /tabpane >}}
 
 The CLI will print a compact form of the event to the terminal similar to the
-following output.
+following output. The example output below is from Kubernetes; the Docker output
+is very similar.
 
 ```
 🚀 process default/xwing /bin/bash -c "curl https://ebpf.io/applications/#tetragon"
 🚀 process default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon
 💥 exit    default/xwing /usr/bin/curl https://ebpf.io/applications/#tetragon 60
 ```
 
-The compact exec event contains the event type, the pod name, the binary and the args. The exit event will include the return code, in the case of curl `60` above.
+The compact execution event contains the event type, the pod name, the binary
+and the args. The exit event will include the return code; in the case of the
+`curl` command above, the return code was 60.
 
-For the complete exec event in JSON format remove the compact option.
+For the complete execution event in JSON format remove the `-o compact` option
+from the `tetra getevents` command.
 
 {{< tabpane lang=shel-session >}}
-{{< tab Kubernetes >}}
+{{< tab "Kubernetes (single node)" >}}
 kubectl exec -ti -n kube-system ds/tetragon -c tetragon -- tetra getevents --pods xwing
 {{< /tab >}}
+{{< tab "Kubernetes (multiple nodes)" >}}
+kubectl exec -ti -n kube-system po/<tetragon-pod-name> -c tetragon -- tetra getevents --pods xwing
+{{< /tab >}}
 {{< tab Docker >}}
-docker exec tetragon-container tetra getevents
+docker exec -ti tetragon tetra getevents
 {{< /tab >}}
 {{< /tabpane >}}
 
-This will include a lot more details related the binary and event. A full example of the above curl is hown here,
-In a Kubernetes environment this will include the Kubernetes metadata include the Pod, Container, Namespaces, and
-Labels among other useful metadata.
+The complete execution event includes a lot more details related to the binary
+and event. See below for a full example of the execution event generated by the
+`curl` command used above. In a Kubernetes environment this will include the
+Kubernetes metadata include the Pod, Container, Namespaces, and Labels, among
+other useful metadata.
 
-<details><summary>Process execution event</summary>
+<details><summary>Full output of a process execution event</summary>
 <p>
 
 ```json
@@ -142,7 +198,6 @@ Labels among other useful metadata.
   "node_name": "gke-john-632-default-pool-7041cac0-9s95",
   "time": "2023-10-06T22:03:57.700326678Z"
 }
-
 ```
 </p>
 </details>
@@ -151,5 +206,5 @@ Labels among other useful metadata.
 
 Execution events are the most basic event Tetragon can produce. To see how to
 use tracing policies to enable file monitoring see the
-[File Access Monitoring]({{< ref "/docs/getting-started/file-events" >}}) quickstart.
-To see a network policy check the [Networking Monitoring]({{< ref "/docs/getting-started/network" >}}) quickstart.
+[File Access Monitoring]({{< ref "/docs/getting-started/file-events" >}}) section of the Getting Started guide.
+To see a network policy check the [Networking Monitoring]({{< ref "/docs/getting-started/network" >}}) section.

docs/content/en/docs/getting-started/install-docker.md

@@ -23,15 +23,39 @@ The easiest way to start experimenting with Tetragon is to run it via Docker
 using the released container images.
 
 ```shell
-docker run --name tetragon-container --rm --pull always \
+docker run -d --name tetragon --rm --pull always \
     --pid=host --cgroupns=host --privileged             \
     -v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf    \
-    quay.io/cilium/tetragon-ci:latest
+    quay.io/cilium/tetragon:latest
 ```
 
-This will start Tetragon in a privileged container. Priviliges are required
-to load and attach BPF programs. See Installation section for more details.
+This will start Tetragon in a privileged container running in the background.
+Running Tetragon as a privileged container is required to load and attach BPF
+programs. See the [Installation and Configuration]({{< ref "/docs/installation" >}})
+section for more details.
 
-## What's Next
+## Run demo application
+
+To explore Tetragon it is helpful to have a sample workload. You can use Cilium’s
+demo application with [this Docker Compose file](https://github.com/cilium/tetragon/blob/main/examples/quickstart/docker-compose.yaml),
+but any workload would work equally well:
+
+```shell
+curl -LO https://github.com/cilium/tetragon/raw/main/examples/quickstart/docker-compose.yaml
+docker compose -f docker-compose.yaml up -d
+```
+
+You can use `docker container ls` to verify that the containers are up and
+running. It might take a short amount of time for the container images to
+download.
+
+```shell
+CONTAINER ID   IMAGE                             COMMAND                  CREATED          STATUS          PORTS                                   NAMES
+cace79752d94   quay.io/cilium/json-mock:v1.3.8   "bash /run.sh"           34 seconds ago   Up 33 seconds                                           starwars-xwing-1
+4f8422b43b5b   quay.io/cilium/json-mock:v1.3.8   "bash /run.sh"           34 seconds ago   Up 33 seconds                                           starwars-tiefighter-1
+7b60618ca8bd   quay.io/cilium/starwars:v2.1      "/starwars-docker --…"   34 seconds ago   Up 33 seconds   0.0.0.0:8080->80/tcp, :::8080->80/tcp   starwars-deathstar-1
+```
+
+## What's next
 
 Check for [execution events]({{< ref "/docs/getting-started/execution" >}}).

docs/content/en/docs/getting-started/install-k8s.md

@@ -41,7 +41,7 @@ az aks get-credentials --resource-group "${AZURE_RESOURCE_GROUP}" --name "${NAME
 {{% /tab %}}
 {{% tab EKS %}}
 
-The following commands create a Kubernetes cluster with `eksctl` using [Amazon Elastic
+The following commands create a single node Kubernetes cluster with `eksctl` using [Amazon Elastic
 Kubernetes Service](https://aws.amazon.com/eks/). See [eksctl installation](https://github.com/eksctl-io/eksctl#installation)
 for instructions on how to install `eksctl` and prepare your account.
 
@@ -54,7 +54,7 @@ eksctl create cluster --name "${NAME}"
 {{% tab "Kind" %}}
 
 Tetragon's correct operation depends on access to the host `/proc` filesystem. The following steps
-configure kind and Tetragon accordingly when using a Linux system.
+configure kind and Tetragon accordingly when using a Linux system. The following commands create a single node Kubernetes cluster using `kind` that is properly configured for Tetragon.
 
 ```shell
 cat <<EOF > kind-config.yaml
@@ -73,6 +73,11 @@ EXTRA_HELM_FLAGS=(--set tetragon.hostProcPath=/procHost) # flags for helm instal
 
 {{< /tabpane >}}
 
+The commands in this Getting Started guide assume you use a single-node
+Kubernetes cluster. If you use a cluster with multiple nodes, be aware that
+some of the commands shown need to be modified. We call out these changes where
+they are necessary.
+
 ### Deploy Tetragon
 
 To install and deploy Tetragon, run the following commands:

examples/quickstart/docker-compose.yaml

@@ -0,0 +1,24 @@
+name: starwars
+networks:
+  galaxyfaraway:
+services:
+  deathstar:
+    hostname: deathstar
+    image: quay.io/cilium/starwars:v2.1
+    networks:
+      - galaxyfaraway
+    ports:
+      - 8080:80
+    restart: always
+  tiefighter:
+    hostname: tiefighter
+    image: quay.io/cilium/json-mock:v1.3.8
+    networks:
+      - galaxyfaraway
+    restart: always
+  xwing:
+    hostname: xwing
+    image: quay.io/cilium/json-mock:v1.3.8
+    networks:
+      - galaxyfaraway
+    restart: always