Tetragon (tetragon)
Runtime protection on every host: the platform configures the eBPF agent, the Navin TracingPolicies (forbidden binaries killed, sensitive files watched), the JSON event export and the Prometheus metrics.
Generated from catalog/services/tetragon.yaml: do not edit by hand.
Summary
| Version | 1.8.0 |
| Use | install and configure, configure and connect |
| Layer | functional (AI catalog) |
| Category | Security and policies |
| Installation methods | binary, podman |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | tetragon |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| container image | quay.io/cilium/tetragon | v1.8.0 | Apache-2.0 | image key tetragon, used by tetragon, digest sha256:5ed9088a1582131d71b06c98e0d549a37a71ae63ab13aabefc7a47553c822a9d |
| binary archive | tetragon-v1.8.0-amd64.tar.gz | 1.8.0 | Apache-2.0 | https://github.com/cilium/tetragon/releases/download/v1.8.0/tetragon-v1.8.0-amd64.tar.gz, x86_64, checksum sha256 |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- Linux kernel 5.4 or later (blocking,
kernel).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
tetragon | metrics | 2112/tcp | yes |
tetragon | metrics_local | 2112/tcp | no |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
Tetragon agent (tetragon) | worker | binary, podman | 2112/tcp, 2112/tcp |
Every chosen host (per-host) (default)
One agent per host, like a daemon set.
What the mode deploys:
| Component | Placement |
|---|---|
tetragon | min 1, recommended 3 |
Single host (standalone)
One agent on one host.
What the mode deploys:
| Component | Placement |
|---|---|
tetragon | min 1, max 1 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select Tetragon. The card shows the licence
Apache-2.0. Pick the Method amongbinary,podman(defaultbinary). -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
per-host(default),standalone. Each mode deploys the components listed in Installation methods and modes. -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
Connect an existing service
| Schemes | https, http |
| Default port | 2112 |
| Authentication | none |
| Health check | /metrics |
| Authentication method | Fields | Description |
|---|---|---|
none | - | The Tetragon metrics endpoint has no authentication. |
Official documentation: https://tetragon.io/docs/
| Field | Type | Default | Description | Notes |
|---|---|---|---|---|
Event export file (export_path) | string | /var/log/tetragon/tetragon.log | JSON event file of the existing agents, collected by the platform log pipeline. | - |
High availability
| Cluster | per host (per-host) |
| High availability | per host (per-host) |
| Failover | none (none) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | none (none) |
| Entry point | per host (per-host) |
| Official documentation | https://tetragon.io/docs/installation/kubernetes/ |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
per-host | ha (ha) | per host (per-host) | - | - | One agent on every host: each host covers itself, the loss of a host only loses its own coverage. |
standalone | standalone (standalone) | single (single) | - | 1 | One agent on one host. |
Notes
- Tetragon needs Linux with eBPF and BTF on every host; it watches only its own host.
- The metrics server of Tetragon has no TLS (pkg/metricsconfig of the release serves plain HTTP). With metrics_local, it listens on 127.0.0.1 only and the Alloy agent of each host relays the metrics to Prometheus by remote write; install Alloy on the Tetragon hosts with its bindings tetragon and prometheus.
Configuration parameters
General
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Metrics port (metrics_port) | port | 2112 | - | no | no | yes | Port of the Prometheus metrics (/metrics). |
Metrics on the loopback only (metrics_local) | bool | false | - | no | no | yes | The metrics server of Tetragon has no TLS: bind it to 127.0.0.1 of each host so that nothing leaves the host in clear; the Alloy agent of the host (bindings tetragon and prometheus) scrapes it and sends the metrics to Prometheus by remote write, in TLS when Prometheus is. Required by the banking-secure and air-gapped profiles. |
gRPC port (grpc_port) | port | 54321 | - | no | no | yes | Local gRPC API of the agent (tetra CLI, event stream), bound to 127.0.0.1. |
Enforcement (enforce) | bool | true | - | no | no | no | Kill the processes matched by the Navin policies (false: log only). |
Forbidden binaries (forbidden_binaries) | list | ["/usr/bin/nc", "/usr/bin/ncat", "/usr/bin/socat"] | - | no | no | no | Binaries whose execution is blocked on the platform hosts. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
metrics | http | tetragon | 2112 (metrics_port) | /metrics | - | local | - | - |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
tetragon | HTTP http://{{ '127.0.0.1' if config.metrics_local else (host.ip or '127.0.0.1') }}:{{ config.metrics_port }}/metrics | Expected 200; 30 retries; interval 2 s; timeout 5 s |
Readiness (service check)
| Check | Details |
|---|---|
HTTP http://{{ '127.0.0.1' if config.metrics_local else (host.ip or '127.0.0.1') }}:{{ config.metrics_port }}/metrics | Expected 200; Expected tetragon_ |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
kernel | kernel_min {"version": "5.4"} | Linux kernel 5.4 or later | blocking | every component |
metrics_port_free | port_free {"param": "metrics_port"} | port 2112 free on the host | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.log }}.
Upstream documentation
- Homepage: https://tetragon.io
- Source: https://github.com/cilium/tetragon
- High availability: https://tetragon.io/docs/installation/kubernetes/
- Authentication: https://tetragon.io/docs/