Release notes

Upgrade notes

Read the upgrade notes carefully before upgrading Tetragon. Depending on your setup, changes listed here might require a manual intervention.

Helm Values

• It's now supported to run multiple Tetragon operator replicas simultaneously. Enable it by setting tetragonOperator.replicas=2 and tetragonOperator.failoverLease.enabled=true.
• tetragonOperator.strategy now sets a default rollingUpdate strategy (maxSurge=1, maxUnavailable=0) to reduce downtime during an upgrade.
• The Tetragon operator Deployment now sets a default podAntiAffinity (preferredDuringSchedulingIgnoredDuringExecution) to improve the Pod distribution (if possible), without enforcing it to avoid being stuck during upgrades on single or two node clusters.

TracingPolicy (k8s CRD)

• FollowFD, UnfollowFD, and CopyFD actions are being deprecarted in this (1.4) and are scheduled for removal in the next (1.5)

Metrics

• tetragon_map_errors_total metric is replaced by map_errors_update_total and map_errors_delete_total.

Changes

total: 298 commits, prs: 110 pr commits: 298

Major Changes

• feat: include ancestors in process events (https://github.com/cilium/tetragon/pull/2938) by @t0x01
• Add attribute resolution (https://github.com/cilium/tetragon/pull/3143) by @ScriptSathi
• policies: add support for setting a monitoring mode in tracing policies (https://github.com/cilium/tetragon/pull/3393) by @kkourt
• Windows: Build tetragon on Windows (Part -1) (https://github.com/cilium/tetragon/pull/3445) by @ExceptionalHandler

Bugfixes

• [fix] fix probe_read_str return type (https://github.com/cilium/tetragon/pull/3236) by @arthur-zhang
• tetragon: avoid the agent from hanging in some corner error conditions (https://github.com/cilium/tetragon/pull/3321) by @kkourt
• Fix in_init_tree flag for processes started before Tetragon. (https://github.com/cilium/tetragon/pull/3338) by @will-isovalent
• Fix a bug where unloading programs where detaching them even in the case of unpin false (i.e.) --keep-sensors-on-exit (https://github.com/cilium/tetragon/pull/3347) by @mtardy
• Fix path truncations in event values for cwd and path/file function arguments. The function responsible for reading dentry was upgraded to 4096 but some users were still using the previous limitation of 256. (https://github.com/cilium/tetragon/pull/3427) by @mtardy
• Use BTF to access skb_ext (https://github.com/cilium/tetragon/pull/3439) by @xabrouck
• watcher: Fix K8sWatcher.FindPod (https://github.com/cilium/tetragon/pull/3409) by @lambdanis

Minor Changes

• tetra: Fix tetra debug progs fail (https://github.com/cilium/tetragon/pull/3235) by @olsajiri

• tetragon: factor generic maps (https://github.com/cilium/tetragon/pull/3257) by @olsajiri

• fix: nspid assign is not correct (https://github.com/cilium/tetragon/pull/3267) by @arthur-zhang

• bug: fix assign vfsmnt correctly (https://github.com/cilium/tetragon/pull/3261) by @arthur-zhang

• [bug] matchPIDs is using first pid only (https://github.com/cilium/tetragon/pull/3255) by @arthur-zhang

• tetragon: Fix override program pin for fmodret and kprobe multi (https://github.com/cilium/tetragon/pull/3298) by @olsajiri

• tetra: Add CEL filter to the CLI (https://github.com/cilium/tetragon/pull/3124) by @knrc

• tetragon: update vmlinux.h (https://github.com/cilium/tetragon/pull/3308) by @olsajiri

• doc: note that kernels >= 6.11 require new cgroupv1 configs (https://github.com/cilium/tetragon/pull/3284) by @tixxdz

• tetra: Set default for retries to 1 (https://github.com/cilium/tetragon/pull/3335) by @olsajiri

• tetragon: assorted fixes (https://github.com/cilium/tetragon/pull/3323) by @olsajiri

• tetragon: Add map_errors_update_total/map_errors_delete_total metrics (https://github.com/cilium/tetragon/pull/3346) by @olsajiri

• Add support for struct socket and struct sockaddr. (https://github.com/cilium/tetragon/pull/3358) by @kevsecurity

• tetragon: map changes (https://github.com/cilium/tetragon/pull/3328) by @olsajiri

• tetragon: Add GetExecveEntries function (https://github.com/cilium/tetragon/pull/3390) by @olsajiri

• helm: add cri.enabled, cri.socketHostPath, and cgidmap.enables variables (https://github.com/cilium/tetragon/pull/3382) by @kkourt

  metrics: add metrics for cgidmap CRI resolution

• cgroups: relax deployment detection logic (https://github.com/cilium/tetragon/pull/3400) by @tixxdz

• tetragon: Move extract code into separate function (https://github.com/cilium/tetragon/pull/3416) by @olsajiri

• tetragon: assorted fixes (https://github.com/cilium/tetragon/pull/3394) by @olsajiri

• tetragon: harden actions a bit (https://github.com/cilium/tetragon/pull/3279) by @olsajiri

• generic sensor: add a dentry type (https://github.com/cilium/tetragon/pull/3423) by @olsajiri

• gRPC: the deprecated sensors API is now removed. (https://github.com/cilium/tetragon/pull/3437) by @kkourt

CI Changes

• [CI] Fix virt-customize issue in vmtests (https://github.com/cilium/tetragon/pull/3232) by @tpapagian
• ci: remove buildjet runners and use GitHub arm64 runners (https://github.com/cilium/tetragon/pull/3280) by @mtardy
• renovate: disable digest update on Dockerfiles (https://github.com/cilium/tetragon/pull/3285) by @mtardy
• renovate: fix for config change 70ad4e78d5b4 (https://github.com/cilium/tetragon/pull/3286) by @mtardy
• renovate: remove matchBaseBranches on main for grouping rules (https://github.com/cilium/tetragon/pull/3324) by @mtardy
• renovate: update various versions in source code (https://github.com/cilium/tetragon/pull/3342) by @mtardy
• CI: build tetragon on every commit of a PR (https://github.com/cilium/tetragon/pull/3354) by @mtardy
• renovate: Group cel-go together with k8s dependencies (https://github.com/cilium/tetragon/pull/3383) by @lambdanis
• workflows: only run build every commit on pull request event (https://github.com/cilium/tetragon/pull/3386) by @mtardy
• renovate: more robust parser for Go version in go.mod (https://github.com/cilium/tetragon/pull/3401) by @mtardy
• Various renovate config tunings (https://github.com/cilium/tetragon/pull/3420) by @mtardy
• fix bug in e2e tests and update its dependencies (https://github.com/cilium/tetragon/pull/3421) by @mtardy
• workflow: fix a bug in build every commit (https://github.com/cilium/tetragon/pull/3449) by @mtardy
• chore: added verifier tests (https://github.com/cilium/tetragon/pull/3433) by @AshishNaware
• renovate config: automerge more (https://github.com/cilium/tetragon/pull/3505) by @mtardy
• ci: Refactor linters, formatters and generators checks (https://github.com/cilium/tetragon/pull/3509) by @lambdanis
• api: Copy API reference into docs (https://github.com/cilium/tetragon/pull/3525) by @lambdanis

Documentation changes

• docs: Add dev setup instructions for Apple silicon Macs (https://github.com/cilium/tetragon/pull/3231) by @michi-covalent
• docs: local dev with Apple Silicon small fixes (https://github.com/cilium/tetragon/pull/3237) by @mtardy
• docs: remove redundance CLI command in tracing policy example (https://github.com/cilium/tetragon/pull/3256) by @arthur-zhang
• docs: enhancements to the troubleshooting section (https://github.com/cilium/tetragon/pull/3238) by @mtardy
• fix: correcting the script path for minikube installation steps in do… (https://github.com/cilium/tetragon/pull/3111) by @d-cryptic
• Add link to Kubecon NA 2024 talk discussing Tetragon (https://github.com/cilium/tetragon/pull/3303) by @daxmc99
• fix: Troubleshooting documentation for System dump (https://github.com/cilium/tetragon/pull/3325) by @z63d
• docs: fix typo referencing kube-system as kubesystem (https://github.com/cilium/tetragon/pull/3334) by @z63d
• docs: fix the Example jq filter in Observability Policies (https://github.com/cilium/tetragon/pull/3367) by @z63d
• fix: returnArg index of TracingPolicy is not specified (https://github.com/cilium/tetragon/pull/3388) by @z63d
• docs: fix tracing policy options (https://github.com/cilium/tetragon/pull/3470) by @z63d
• docs: Remove incorrect event types from field filter docs examples. (https://github.com/cilium/tetragon/pull/3489) by @will-isovalent
• docs: fix typo (https://github.com/cilium/tetragon/pull/3528) by @jetlime

Dependency updates

• fix(deps): update module github.com/cilium/ebpf to v0.17.1 (main) (https://github.com/cilium/tetragon/pull/3206) by @cilium-renovate[bot]
• fix(deps): update module google.golang.org/grpc to v1.70.0 (main) (https://github.com/cilium/tetragon/pull/3330) by @cilium-renovate[bot]
• chore(deps): update all github action dependencies (main) (https://github.com/cilium/tetragon/pull/3387) by @cilium-renovate[bot]
• chore(deps): update docker.io/golangci/golangci-lint docker tag to v1.64.5 (main) (https://github.com/cilium/tetragon/pull/3398) by @cilium-renovate[bot]

Misc Changes

• start v1.4 development (https://github.com/cilium/tetragon/pull/3226) by @kkourt
• fix: improve error handling for tracing policies directory access (https://github.com/cilium/tetragon/pull/3289) by @arthur-zhang
• Add tetra policyfilter listpolicies command (https://github.com/cilium/tetragon/pull/3122) by @tpapagian
• tetragon: add get_current_task_btf (https://github.com/cilium/tetragon/pull/3305) by @jrfastab
• bpf: declare maps with __type for key and value (https://github.com/cilium/tetragon/pull/3307) by @mtardy
• clang-format: use ignore file (https://github.com/cilium/tetragon/pull/3322) by @kkourt
• Create an AUTHORS file for tetragon (https://github.com/cilium/tetragon/pull/3319) by @kkourt
• tetra/debug: Clone GetDebugResponse entries (https://github.com/cilium/tetragon/pull/3343) by @tpapagian
• Add the ability to get process cache entries (https://github.com/cilium/tetragon/pull/3348) by @tpapagian
• pkg/sensors: pin link in TracingAttach (https://github.com/cilium/tetragon/pull/3352) by @mtardy
• vmtests: disable TestFastK8s (https://github.com/cilium/tetragon/pull/3356) by @kkourt
• gitattributes: auto resolve merge conflicts for generated files (https://github.com/cilium/tetragon/pull/3366) by @will-isovalent
• api: build using buf (https://github.com/cilium/tetragon/pull/3368) by @will-isovalent
• Refactor CRD defaulting and validation as generic (https://github.com/cilium/tetragon/pull/3403) by @lambdanis
• buf fixes (https://github.com/cilium/tetragon/pull/3417) by @kkourt
• ci: fixes for buf workflow (https://github.com/cilium/tetragon/pull/3418) by @will-isovalent
• api/Makefile: make it work for worktrees (https://github.com/cilium/tetragon/pull/3419) by @kkourt
• pkg/bpf: remove redundant check from HasLSMPrograms (https://github.com/cilium/tetragon/pull/3422) by @anfedotoff
• filters: Minor CEL refactoring (https://github.com/cilium/tetragon/pull/3426) by @lambdanis
• watcher: Refactor K8sWatcher to reuse config and factories (https://github.com/cilium/tetragon/pull/3413) by @lambdanis
• Revert "pkg/bpf: remove redundant check from HasLSMPrograms" (https://github.com/cilium/tetragon/pull/3456) by @ScriptSathi
• syscallmetrics: use syscall type (https://github.com/cilium/tetragon/pull/3462) by @kkourt
• bpf: verification fixes (https://github.com/cilium/tetragon/pull/3460) by @kkourt
• tetra: add a --reconnect option to getevents command (https://github.com/cilium/tetragon/pull/3438) by @kkourt
• install/kubernetes: fix typo (https://github.com/cilium/tetragon/pull/3499) by @kkourt
• main: Split k8s watchers into process metadata and policy (https://github.com/cilium/tetragon/pull/3524) by @lambdanis