Tetragon Explained: eBPF Runtime Security Architecture

Updated on Oct 23, 2026

10 min read

Tetragon eBPF runtime security helps platform and security teams observe activity inside Linux workloads and respond to selected events while programs are running. It is discussed as an alternative to relying only on application logs or post-incident host audits: Tetragon places sensors at supported kernel hooks, adds process and Kubernetes context, and can apply policy actions where configured. This explainer covers its architecture, practical deployment, and the boundaries operators need to understand before using it in production.

What Is Tetragon?

Tetragon is an open-source security observability and runtime enforcement project in the Cilium ecosystem. It uses eBPF, a Linux kernel facility for running constrained programs at supported hooks, to inspect security-relevant events such as process execution, file access, and network activity. In Kubernetes, it can associate events with workload information such as a pod and namespace rather than reporting only a host process identifier. The Tetragon project site describes its focus on kernel-level security visibility and enforcement.

The distinction between observing and enforcing matters. An event feed can help an analyst investigate what happened; enforcement means a configured policy also causes an action when a matching event occurs. Tetragon supports both, but installing the agent does not automatically create an organization-specific security policy. Operators decide what to observe, which workloads are in scope, and what response is safe.

Tetragon is not a Kubernetes admission controller, a network firewall, or a replacement for Linux access controls. It works during runtime and complements controls that decide what may be deployed or which network connections are allowed. The Kubernetes Pod Security Admission explainer covers a deployment-time control with a different responsibility.

Why Does Tetragon Exist?

Security events often cross several layers. A container log may show an application error but not the system call that preceded it. A host audit record may capture an operation without making it easy to connect that operation to a Kubernetes workload. A network alert may identify a connection but not explain which process opened it.

Traditional monitoring can be built from audit frameworks, endpoint agents, runtime rules, and custom scripts. Each source has its own event format, deployment model, and context. Teams then need to correlate process activity with container identity and translate a finding into a response. This can leave gaps between detecting a behavior and understanding which workload caused it.

Tetragon focuses on the kernel boundary, where process and system activity can be observed independently of an application’s logging choices. Its sensors can emit structured events and enrich them with Linux and Kubernetes metadata. For selected cases, policy can filter events and trigger an action in the kernel path. This can make detection timely, but it does not remove the need for application logs, identity controls, network policy, or incident-response processes.

How Tetragon Works

A Tetragon deployment includes an agent on each monitored Linux node. In Kubernetes, the agent normally runs as a DaemonSet so that each eligible node can observe local workloads. The agent loads eBPF programs and attaches them to supported kernel hooks. Depending on the use case, those hooks can include kprobes, tracepoints, and uprobes. The IETF’s BPF Instruction Set Architecture specification describes the instruction set used by BPF programs; it does not define Tetragon’s policy format or security behavior.

When a relevant event occurs, an attached program gathers permitted event details. Tetragon correlates those details with its process and workload state, applies any configured in-kernel filters, and emits selected information through its event interfaces. A collector or log pipeline can then route events to storage, alerting, or investigation tools. Tetragon is therefore one part of an observability pipeline, not the storage or incident-management system itself.

For custom behavior, a TracingPolicy identifies a hook and selectors that determine which events match; it can also specify supported actions. Policies can be loaded through Kubernetes custom resources, the Tetra gRPC interface, or static configuration. The TracingPolicy documentation explains the supported hooks, selectors, and loading methods. Policies are scoped and managed through distinct domains, so operators should understand which mechanism installed a policy before changing or removing it.

Security approach	Main observation point	Context and response	Operational consideration
Linux audit rules	Configured operating-system audit events	Host-oriented records; response is usually handled by separate tooling	Rule coverage and event volume need deliberate configuration
User-space runtime monitor	System calls or process events delivered to a user-space sensor	Depends on the monitor’s process and container enrichment	Event delivery and processing happen outside the kernel
Tetragon	Supported Linux kernel hooks through eBPF	Can enrich events with process and Kubernetes data; selected policies can act on matches	Hook support, privileges, policy scope, and kernel compatibility must be checked
Application logging	Events recorded by the application itself	Rich business context when the application emits it	Cannot reliably report activity outside its own instrumentation

These approaches are not mutually exclusive. Audit records, application telemetry, and Tetragon events answer different questions, and using more than one source can help validate an investigation. For a broader explanation of how eBPF programs attach and collect kernel data, see eBPF observability and network tracing.

Components and Key Concepts

Sensors and hooks: Sensors are the eBPF-backed instrumentation that observes supported kernel events. Process lifecycle events such as execution and exit provide a useful baseline. More specialized tracing can use selected kernel or user-space hooks, but availability and behavior vary with kernel configuration and the specific program being observed.

TracingPolicy: A policy describes where to observe and what event details or selectors matter. A match may be used to report an event or invoke an action supported by that hook. Policies are powerful and should be treated as production code: review them, test them against representative workloads, and document their ownership.

Selectors and filtering: Filtering narrows events to relevant processes, arguments, namespaces, or other supported fields. Applying filters near the event source can reduce unnecessary data, but a filter that is too narrow can hide activity. Begin with the broadest safe observation needed to validate coverage, then refine it using test workloads and known-good event samples.

Process and Kubernetes context: Process relationships help connect an event to its parent process, executable, and container. In clusters, workload metadata can make an alert actionable for the team that owns the pod. That context depends on the agent’s visibility and the environment; it should not be assumed to replace an authoritative identity or asset inventory.

Event output and consumers: Tetragon can expose structured events for collection and inspection. Downstream systems decide how long to retain them, how to alert, and who may access them. Process arguments and file paths may contain sensitive information, so event selection, access control, retention, and redaction deserve the same attention as application logs.

Kernel and privilege requirements: Loading eBPF instrumentation requires suitable kernel support and privileges. Container security settings, host policy, kernel configuration, and distribution choices can affect which features are available. The project documentation should be checked against each node image and kernel version before deployment, especially in heterogeneous clusters.

Real-World Uses

Investigating unexpected process execution: Correlate an executable with its parent process, container, and namespace to determine whether a workload launched an unexpected child.
Monitoring sensitive file or credential access: Use a narrowly scoped policy to identify access patterns that merit review, then route the events to a controlled security pipeline.
Detecting changes in privilege or process behavior: Observe supported kernel events that indicate a change in execution context and alert the team responsible for that host or workload.
Adding runtime context to container controls: Container security combines image, identity, network, and runtime measures. The container security best-practices guide explains those layers; Tetragon can contribute kernel-level evidence without replacing them.

In each case, the outcome depends on policy quality and response procedures. A detector that generates too many low-value events may be ignored, while an overly strict enforcement rule can interrupt healthy services. Detection and blocking should be rolled out separately where possible.

Getting Started with Tetragon

The following Kubernetes commands are a starting point for a test cluster, not a production hardening recipe. Use a cluster and Linux nodes you administer, and review the official installation guide for current prerequisites, chart settings, and version-specific instructions.

Add the Cilium Helm repository and install Tetragon in the existing kube-system namespace:

helm repo add cilium https://helm.cilium.io
helm repo update
helm install tetragon cilium/tetragon -n kube-system

Wait for the DaemonSet to become ready and check its state:

kubectl rollout status -n kube-system daemonset/tetragon --timeout=5m
kubectl get daemonset tetragon -n kube-system
kubectl get pods -n kube-system -l app.kubernetes.io/name=tetragon

Review recent agent output to confirm that events are being produced:

kubectl logs -n kube-system daemonset/tetragon --since=5m

The exact pod labels and available output depend on the chart version and configuration. If a label selector returns no pods, inspect kubectl get pods -n kube-system --show-labels rather than assuming the DaemonSet failed. If the DaemonSet is not ready, inspect its events and logs, check whether the nodes meet the documented kernel requirements, and confirm that cluster policy permits the required privileges.

Start with built-in process lifecycle events and observation-only policies. Compare the output with expected activity in a test workload, check event volume, and verify that workload metadata is useful to responders. Only then introduce actions that can affect a process or operation. Validate those actions against normal application behavior, define an exception and rollback path, and monitor both policy health and application availability. In production, pin and review chart versions, apply least privilege to policy authors, and send only the data needed by downstream systems.

Common Misconceptions

“Tetragon automatically blocks suspicious behavior.” Installation provides an agent and baseline observability, not a complete threat policy. Enforcement requires a policy with an appropriate supported action and a deliberate response decision.

“eBPF makes runtime monitoring risk-free.” The verifier constrains BPF programs, but deployment still requires privileges and consumes system resources. Poorly scoped events can expose sensitive data or overwhelm a collector, and an enforcement policy can disrupt a workload.

“Tetragon replaces every other security layer.” It does not decide whether an image should be admitted, whether a network flow is allowed, or whether an application request is authorized. It adds runtime evidence and selected enforcement at the kernel boundary; use it alongside admission, identity, host, network, and application controls.

“A policy written for one cluster will behave identically everywhere.” Kernel support, available hooks, workload labels, and deployment configuration can differ across nodes. Test compatibility and expected events on each supported node type before relying on a policy for coverage or prevention.

Changelog

Last updated: October 23. Initial publication.