Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): update getting started instructions #2681

Merged
merged 3 commits into from
Jul 22, 2024
Merged

fix(docs): update getting started instructions #2681

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b2e03e6
fix(docs): update getting started instructions
scottslowe Jul 16, 2024
ce2009d
fix: update execution monitoring section of docs
scottslowe Jul 18, 2024
bc4204e
fix: update execution events section
scottslowe Jul 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 88 additions & 28 deletions docs/content/en/docs/getting-started/execution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,67 +4,128 @@ 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 first need to find the node where
the workload is running. This command shows the node where the "xwing" Pod is
running.

```shell
kubectl get pod xwing -o jsonpath='{.spec.nodeName}'
```

Next, you will need to find the Tetragon Pod on the same node. This command
returns a list of Tetragon Pods and the name of the Kubernetes node on which
they are running.

This will print a compact form of the exec logs. For an example we do the following
with the demo application.
```shell
kubectl -n kube-system get pods -o custom-columns=NAME:.metadata.name,NODE:.spec.nodeName | grep <name-of-node-with-workload>
```

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 po/<tetragon-pod-name> -c tetragon -- tetra getevents -o compact --pods xwing
```
mtardy marked this conversation as resolved.
Show resolved Hide resolved

Because the Tetragon Pod where you are running `tetra getevents` in on the same
Pod 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
Expand Down Expand Up @@ -142,7 +203,6 @@ Labels among other useful metadata.
"node_name": "gke-john-632-default-pool-7041cac0-9s95",
"time": "2023-10-06T22:03:57.700326678Z"
}

```
</p>
</details>
Expand All @@ -151,5 +211,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.
34 changes: 29 additions & 5 deletions docs/content/en/docs/getting-started/install-docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

--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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

forgot to add to remove shell

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:
image

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" >}}).
9 changes: 7 additions & 2 deletions docs/content/en/docs/getting-started/install-k8s.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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:
Expand Down
24 changes: 24 additions & 0 deletions examples/quickstart/docker-compose.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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