diff --git a/docs/content/en/docs/getting-started/execution.md b/docs/content/en/docs/getting-started/execution.md index f8d1ed88959..4964bc15297 100644 --- a/docs/content/en/docs/getting-started/execution.md +++ b/docs/content/en/docs/getting-started/execution.md @@ -4,42 +4,90 @@ 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" @@ -47,24 +95,32 @@ following output. 💥 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/ -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. -
Process execution event +
Full output of a process execution event

```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" } - ```

@@ -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. diff --git a/docs/content/en/docs/getting-started/install-docker.md b/docs/content/en/docs/getting-started/install-docker.md index 67fb9eb6c49..c8450893b0c 100644 --- a/docs/content/en/docs/getting-started/install-docker.md +++ b/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" >}}). diff --git a/docs/content/en/docs/getting-started/install-k8s.md b/docs/content/en/docs/getting-started/install-k8s.md index c4406732cee..9e26a920bda 100644 --- a/docs/content/en/docs/getting-started/install-k8s.md +++ b/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 < 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: diff --git a/examples/quickstart/docker-compose.yaml b/examples/quickstart/docker-compose.yaml new file mode 100644 index 00000000000..359ed5d01e3 --- /dev/null +++ b/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