Skip to content

Commit

Permalink
tetragon: docs, simplify getting started guide
Browse files Browse the repository at this point in the history
Simplify the getting started guide
  • Loading branch information
jrfastab committed Oct 6, 2023
1 parent decc786 commit d019715
Show file tree
Hide file tree
Showing 10 changed files with 393 additions and 492 deletions.
4 changes: 2 additions & 2 deletions docs/content/en/docs/concepts/tracing-policy/example.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,8 +115,8 @@ echo eBPF! > /tmp/tetragon
Starting Tetragon with the above `TracingPolicy`, for example putting the
policy in the `example.yaml` file, compiling the project locally and starting
Tetragon with (you can do similar things with container image releases, see the
docker run command in the [Try Tetragon on Linux guide]({{< ref
"/docs/getting-started/try-tetragon-linux#observability-with-tracingpolicy" >}}):
docker run command in the [Try Tetragon on Linux guide]

```shell-session
sudo ./tetragon --bpf-lib bpf/objs --tracing-policy example.yaml
```
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
title: "Quick Install Tetragon"
linkTitle: "Quick Install"
isShownInList: false
weight: 1
description: >
Quick install quide for Tetragon.
---

Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: "Try Tetragon locally "
weight: 1
description: "Discover and experiment with Tetragon on your local Linux host"
---

{{< note >}}
This guide has been tested on Ubuntu 22.04 and 22.10 with respectively kernel
`5.15.0` and `5.19.0` on amd64 and arm64 but
[any recent distribution](https://github.com/libbpf/libbpf#bpf-co-re-compile-once--run-everywhere)
shipping with a relatively recent kernel should work. See the FAQ for further details on
the [recommended kernel versions]({{< ref "/docs/faq#what-is-the-minimum-linux-kernel-version-to-run-tetragon" >}}).

Note that you cannot run Tetragon using Docker Desktop on macOS because of a
limitation of the Docker Desktop Linux virtual machine. Learn more about this issue
and how to run Tetragon on a Mac computer in [this section of the FAQ page](/docs/faq/#can-i-run-tetragon-on-mac-computers).
{{< /note >}}

## Start Tetragon

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 \
--pid=host --cgroupns=host --privileged \
-v /sys/kernel/btf/vmlinux:/var/lib/tetragon/btf \
quay.io/cilium/tetragon-ci:latest
```

This will start Tetragon in a privileged container. Priviliges are required
to load and attach BPF programs. See Installation section for more details.
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: "Try Tetragon on Kubernetes"
weight: 1
description: "Discover and experiment with Tetragon in a kubernetes environment"
---

### Create a cluster

If you don’t have a Kubernetes Cluster yet, you can use the instructions below to create a Kubernetes cluster locally or using a managed Kubernetes service:

TBD tabplane this...

#### Kind

Run the following command to create the Kubernetes cluster:
```
kind create cluster
```

#### GKE

Run the following command to create a GKE cluster:

```shell
export NAME="$(whoami)-$RANDOM"
gcloud container clusters create "${NAME}" \
--zone us-west2-a \
--num-nodes 1
```

### Deploy Tetragon

To install and deploy Tetragon, run the following commands:

```shell
helm repo add cilium https://helm.cilium.io
helm repo update
helm install tetragon cilium/tetragon -n kube-system
kubectl rollout status -n kube-system ds/tetragon -w
```

By default, Tetragon will filter kube-system events to reduce noise in the
event logs. See concepts and advanced configuration to configure these
parameters.

### Deploy demo application

To explore Tetragon its helpful to have a sample workload. Here wu use the Cilium
HTTP application, but any workload would work equally well.

To use our [demo
application](https://docs.cilium.io/en/v1.11/gettingstarted/http/#deploy-the-demo-application)

```shell
kubectl create -f https://raw.githubusercontent.com/cilium/cilium/v1.11/examples/minikube/http-sw-app.yaml
```

Before going forward, verify that all pods are up and running - it might take
several seconds for some pods until they satisfy all the dependencies:

```shell
kubectl get pods
```

The output should be similar to:
```
NAME READY STATUS RESTARTS AGE
deathstar-6c94dcc57b-7pr8c 1/1 Running 0 10s
deathstar-6c94dcc57b-px2vw 1/1 Running 0 10s
tiefighter 1/1 Running 0 10s
xwing 1/1 Running 0 10s
```


This file was deleted.

45 changes: 45 additions & 0 deletions docs/content/en/docs/getting-started/tetragon-enforcement.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
title: "Policy Enforcement"
weight: 2
description: "Policy Enforcement"
---

This adds a network and file policy enforcement on top of execution, file tracing
and networking policy already deployed in the quick start. In this use case we
use a namespace and pod labels to limit the scope of where the network, file
and some security policies will be applied. This highlights two important concepts
of Tetragon. First in kernel filter provides performance advantages, but also allows for
enforcing policies inline with the action. Second, by including kubernetes
filters, such as namespace and labels we can segment a policy to apply to
targeted pods. For implementation details see Enforcement section and for
modifying and creating additional policies see Tracing Policies.

# Enforcement

To apply the policy

{{< tabpane >}}
{{< tab header="K8s" >}}
kubectl apply -f tbd.base-enforce.yaml
{{< /tab >}}
{{< tab header="Docker" >}}
{{< /tab >}}
{{< tab header="Systemd" >}}
{{< /tab >}}
{{< /tabpane >}}

With the file applied we can attach tetra to observe events again,

```
kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon
```

And once again execute a curl command in the xwing,

```
kubectl exec -ti xwing -- bash -c 'curl https://ebpf.io/applications/#tetragon
```

The CLI will print the exec tracing and file access as before, but will additional show the network connection outside the K8s cluster.

#

0 comments on commit d019715

Please sign in to comment.