Falco Helm Chart 破坏性变更完全迁移指南：从 v3 到 v9 的升级对照与配置改造

• 云原生
• 运行时防护
• IDS
• 应用安全

Falco Helm Chart 在 v3.0.0 到 v9.0.0 之间经历了多轮重大重构：引入 falcoctl 自动化工件管理、移除 gRPC 输出、废弃 Legacy eBPF 探针与 gVisor 引擎、重构 driver 配置结构、更换默认镜像与容器元数据采集方式。本文以 chart/falco/BREAKING-CHANGES.md 为骨架，逐版本梳理每一项破坏性变更的来龙去脉、影响范围与迁移命令，并结合本仓库的 values.yaml、templates/_helpers.tpl、templates/pod-template.tpl 等源码给出配置级佐证，帮助你安全完成从旧版 Chart 到新版 Chart 的升级。

版本变更总览

下表汇总了当前 Chart（Chart.yaml 中 version 为9.1.0、appVersion 为0.44.1）自 v3.0.0 以来每一处破坏性变更及其影响面，方便你在升级前快速定位自己可能受影响的配置项：

9.0.0：gRPC 输出与 Legacy eBPF / gVisor 正式移除

gRPC output 与 gRPC server 移除

自 Falco 0.44.0 起（此前 0.43.0 已发出废弃通知），gRPC output 与内嵌的 gRPC server 不再受支持。gRPC server 的移除是 gRPC output 移除的直接结果——后者依托前者向客户端推送告警流。如果你在values.yaml中仍配置了falco.grpc或falco.grpc_output，Chart 会在渲染阶段直接失败。

仓库中的 templates/_helpers.tpl 实现了falco.removedConfigGuard守卫模板，将已移除的配置项显式列入黑名单：

{{- $removedDriverKinds := list "ebpf" "gvisor" -}} {{- $removedDriverKeys := list "ebpf" "gvisor" -}} {{- $removedFalcoKeys := list "grpc" "grpc_output" -}} ... {{- fail (printf "The following chart configuration is no longer supported: %s. See BREAKING-CHANGES.md for migration guidance." (join ", " $found)) -}}

也就是说，升级到 9.x 后如果旧配置里还留着falco.grpc.*或falco.grpc_output.*，helm upgrade会直接报错并提示你查阅 BREAKING-CHANGES.md，而不是静默忽略——这是比 8.0.0 时期的"启动时告警"更强硬的保护。

迁移建议：改用以下替代输出通道（这些通道在 values.yaml 中均有完整配置项）：

• HTTP output（falco.http_output）：支持 URL、user_agent、CA 证书（ca_cert/ca_bundle/ca_path）、mTLS 客户端证书（mtls、client_cert、client_key）、compress_uploads、keep_alive等参数；
• File output（falco.file_output）：支持keep_alive、filename，注意 Falco 不会对文件做日志轮转，收到 SIGUSR1 会关闭并重开文件；
• Stdout output（falco.stdout_output）：enabled: true即可；
• Falcosidekick：作为高级集成入口，可把告警转发到 Slack、Teams、Webhook 等下游。Chart 中通过falcosidekick.enabled条件依赖引入（见 Chart.yaml）。

Legacy eBPF probe 与 gVisor 引擎移除

同样自 Falco 0.44.0 起，以下引擎不再受支持：

• Legacy eBPF probe（driver.kind=ebpf）：官方建议改用Modern eBPF probe（driver.kind=modern_ebpf），后者具备更好的性能与更广的内核兼容性；
• gVisor engine（driver.kind=gvisor）：官方建议改用其他监控方案。

_helpers.tpl中的falco.engineConfiguration也印证了当前 Chart 支持的 driver 类型范围：kmod、modern_ebpf、auto（外加兼容旧写法的别名module、modern-bpf），一旦传入ebpf或gvisor，同样会被 removedConfigGuard 拦截。

从本仓库的废弃提案 proposals/20251215-legacy-bpf-grpc-output-gvisor-engine-deprecation.md 可以了解废弃的技术动因：Legacy eBPF 探针无法利用 CO-RE（Compile Once, Run Everywhere）特性，官方必须为每种内核风味维护独立编译的 eBPF 对象，维护负担大且旧内核上 verifier 限制苛刻；gVisor 引擎无法提供与内核驱动完全等价的事件类型，且引入 protobuf 依赖显著增加构建时间。这些内容对评估迁移成本很有参考价值。

8.0.0：废弃期行为——启动告警而非硬失败

自 Falco 0.43.0 起，上述两组功能进入废弃期：如果配置了falco.grpc.enabled=true或falco.grpc_output.enabled=true，或使用了driver.kind=ebpf/driver.kind=gvisor，Falco 会在启动时输出警告，但功能仍然可用。废弃期只持续一个版本（0.43.0 → 0.44.0），因此如果你仍处于 8.x Chart，务必在升级到 9.x 之前完成迁移，否则升级将因配置校验失败而中止。

7.0.0：容器元数据 collectors 统一为 containerEngine

Chart v4.22 起废弃的三个独立 collectors 选项在 v7.0.0 被正式移除：

• collectors.containerd
• collectors.cri
• collectors.docker

请改用collectors.containerEngine。新方案通过统一的容器插件（container plugin）从各类容器运行时采集元数据，并在底层复用同一套引擎配置。当前 values.yaml 中collectors.containerEngine的结构如下：

collectors: containerEngine: enabled: true pluginRef: "ghcr.io/falcosecurity/plugins/plugin/container:0.7.5" labelMaxLen: 100 withSize: false hooks: ["create"] engines: docker: enabled: true sockets: ["/var/run/docker.sock"] podman: enabled: true sockets: ["/run/podman/podman.sock"] containerd: enabled: true sockets: ["/run/host-containerd/containerd.sock"] cri: enabled: true sockets: ["/run/containerd/containerd.sock", "/run/crio/crio.sock", ...] lxc: enabled: true libvirt_lxc: enabled: true bpm: enabled: true

engines下同时保留了docker、containerd、cri等子开关，用于控制对具体运行时 socket 的监听，因此从旧的三个 collectors 迁移到containerEngine时，把原来的启用/禁用意图平移到engines.<name>.enabled即可。底层实现上，templates/_helpers.tpl 中的falco.containerPlugin会把容器插件写入falco.plugins与falco.load_plugins，并自动把pluginRef追加到 falcoctl 的安装清单中；falco.containerPluginVolumes 则负责按引擎 socket 目录生成 hostPath 卷（挂载的是 socket 所在目录而非 socket 文件本身，避免运行时重启后 pod 持有失效 inode）。

6.0.0：Falco Talon 配置重命名

v6.0.0 对values.yaml做了两处不兼容改名：

• falcotalon更名为falco-talon
• falcotalon.enabled更名为responseActions.enabled

当前 values.yaml 中的对应结构为：

# -- Enable the response actions using Falco Talon. responseActions: enabled: false # -- It must be used in conjunction with the response_actions.enabled option. falco-talon: {}

同时 Chart.yaml 中通过condition: responseActions.enabled条件依赖引入falco-talon子 Chart。升级时只需把旧的falcotalon:键改名为falco-talon:、把falcotalon.enabled改为responseActions.enabled，其余子配置结构不变。

5.0.0：默认镜像切换为 distroless

从 v5.0.0 开始，Chart 默认使用 Falco 标准容器镜像，这是一个不带任何额外工具的 distroless 镜像。此前 Chart 使用包含多种工具的debian镜像以避免升级过程中的破坏；新镜像更安全、更轻量，但不再内置这些工具。

迁移影响：如果你依赖镜像中的某些工具——典型场景是program_output特性（通过program_output.program调用jq、curl、nc等外部命令，见 values.yaml 中的示例配置）——需要手动覆盖image.tag以选用其他镜像风味。例如：

image: tag: "0.41.0-debian"

即可恢复 Debian 版镜像中的工具集。如果你的告警消费链路不依赖任何外部命令（如仅使用 stdout / file / http 输出），保持默认 distroless 镜像即可获得更小的攻击面。

4.0.0：driver 配置重构与 K8s 元数据采集改造

Drivers：统一 driver 命名与配置分组

v4.0.0 依据 Falco 上游 PR 对driver段进行了整体重构，目标是统一 Falco 中 driver 的配置方式，并按 driver 类型分组配置。具体改名如下：

当前 values.yaml 中driver段的结构为：

driver: enabled: true # 可用选项：kmod（内核模块）、modern_ebpf（Modern eBPF 探针）、auto kind: auto sysfsMountPath: "/sys/kernel" kmod: bufSizePreset: 4 dropFailedExit: false modernEbpf: leastPrivileged: false bufSizePreset: 4 dropFailedExit: false cpusForEachBuffer: 2 disableIterators: false sysfsMount: true loader: enabled: true initContainer: image: repository: falcosecurity/falco-driver-loader ...

值得注意的是driver.kind=auto：这是当前默认值，由 driver-loader 在节点上自动探测并选择可用驱动。_helpers.tpl中的falco.engineConfiguration（templates/_helpers.tpl）会把auto展开为同时携带kmod与modern_ebpf两套参数的 engine 配置；driverLoader.enabled（templates/_helpers.tpl）则决定是否注入 driver-loader init container。另外driver.modernEbpf.leastPrivileged: true时，容器将以BPF、SYS_RESOURCE、PERFMON、SYS_PTRACE四个 capability 运行而非 privileged（见 pod-template.tpl 中的falco.securityContext）。

K8s Collector：旧 Kubernetes client 移除，改由 k8s-metacollector + k8smeta 插件承担

Falco 0.37.0 移除了旧版 Kubernetes client。作为替代，k8s-metacollector组件与k8smeta插件接管了 Kubernetes 元数据采集。随之，Chart 中以下为 Falco 直连 API server 准备的资源被移除：

• service account
• cluster role
• cluster role binding

当collectors.kubernetes.enabled=true时，Chart 会部署 k8s-metacollector 子 Chart（条件依赖见 Chart.yaml），并自动配置 Falco 加载 k8smeta 插件。默认情况下collectors.kubernetes.enabled为关闭状态（values.yaml），因为该采集器需要额外的部署成本；关闭时 Falco 回退到容器注解获取元数据，此时仅有 pod 的 ID、名称、namespace、labels 可用。

collectors.kubernetes的关键配置项：

• pluginRef：k8smeta 插件的 OCI 引用，默认ghcr.io/falcosecurity/plugins/plugin/k8smeta:0.4.2
• collectorHostname/collectorPort：k8smeta 插件连接 k8s-metacollector 的 gRPC 地址与端口（端口默认取 k8s-metacollector 服务的broker-grpc端口 45000）
• verbosity：插件日志级别（trace / debug / info / warning / error / critical）
• hostProc：宿主机 /proc 的挂载前缀，默认/host

Plugins：镜像不再内置插件，启用 resolveDeps 按需安装

Falco Docker 镜像不再随镜像发布插件。因此，Chart 在相关 values 文件（如values-k8saudit.yaml）中启用了resolveDeps：当 falcoctl 安装 rulesfile 工件时，会解析其依赖并顺带安装所需插件。

以 values-k8saudit.yaml 为例，纯插件部署（无 syscall driver）场景的配置要点是：

driver: enabled: false # 仅部署 k8saudit 插件，无需 driver collectors: enabled: false # 无 syscall 事件需要元数据富化 controller: kind: deployment # 单实例即可 deployment: replicas: 1 falcoctl: artifact: install: enabled: true # init container 安装工件 follow: enabled: true # sidecar 跟随更新 config: artifact: install: refs: [k8saudit-rules:0.16, k8saudit:0.16] follow: refs: [k8saudit-rules:0.16] falco: load_plugins: [k8saudit, json]

注意此处的falcoctl.config.artifact.allowedTypes会由 Chart 自动扩展为包含plugin，同时把容器插件 / k8smeta 插件的pluginRef自动追加到 install 的refs中（见 templates/_helpers.tpl 与falco.containerPlugin）。

3.0.0：falcoctl 时代开启

v3.0.0 是 Chart 历史上最大的一次架构变更：新 Chart 部署了新的 K8s 资源并在values.yaml中新增了大量配置变量。从 v2.x 升级的用户需要把旧配置移植到新values.yaml。好消息是：Falco 本体（由 Chart 安装的版本）不引入破坏性变更，你可以直接把旧 Falco 配置复制粘贴到新 values 中。

Falcoctl：自动安装与跟随工件

在 v3.0.0 之前，rulesfiles 与插件都捆绑在 Falco 镜像中，导致无法独立更新——运营者必须手动更新 rulesfiles、自行构建包含新插件的镜像，或等待 Falco 新版本发布，过程繁琐且易错。v3.0.0 起 Chart 引入falcoctl，实现：

• install：安装 Falco 生态工件（插件、规则文件）；
• follow：跟随工件更新（官方建议仅对 rulesfile 使用），保持规则与 falcosecurity 组织的最新发布同步，从而在无需重新部署 Falco 的情况下更新检测新漏洞/安全问题的规则。

Chart 通过init container（安装工件并在 Falco 启动前就绪，经 emptyDir 卷共享）和sidecar container（常驻 Falco 旁，检测到更新即下载安装到共享目录）两种方式部署 falcoctl；规则文件被安装到正确目录后会被 Falco 自动加载，且 falcoctl 会在安装前校验工件与运行中 Falco 版本的兼容性。上述两种容器的渲染逻辑分别位于 templates/pod-template.tpl（sidecar 与 init container 注入）以及_helpers.tpl的 falcoctl 相关 define 中；共享的 emptyDir 卷plugins-install-dir、rulesfiles-install-dir、artifact-state-dir的定义见 pod-template.tpl。

当前 values.yaml 中的 falcoctl 默认配置（以当前仓库为准，注意默认值与 v3.0.0 文档示例已有差异）：

falcoctl: image: pullPolicy: IfNotPresent registry: docker.io repository: falcosecurity/falcoctl tag: "0.14.2" artifact: install: enabled: true args: ["--log-format=json"] follow: enabled: true args: ["--log-format=json"] config: indexes: - name: falcosecurity url: https://falcosecurity.github.io/falcoctl/index.yaml artifact: allowedTypes: - rulesfile - plugin install: resolveDeps: true refs: [falco-rules:5] rulesfilesDir: /rulesfiles pluginsDir: /plugins stateDir: /artifactstate follow: refs: [falco-rules:5] every: 168h falcoversions: http://localhost:8765/versions rulesfilesDir: /rulesfiles pluginsDir: /plugins stateDir: /artifactstate

关键参数说明：

• indexes：falcoctl 下载并用于定位/下载工件的索引列表；
• allowedTypes：允许处理的工件类型白名单，解析出的工件类型不在列表中会被拒绝安装；
• install.resolveDeps：是否解析工件依赖（v4.0.0 起镜像不再内置插件，因此默认true，插件由 falcoctl 顺带安装）；
• install.refs/follow.refs：要安装/跟随的工件引用（支持名称:版本语法）；
• every：follow 检查更新的周期，当前默认168h（v3.0.0 文档示例为每 6h）；
• falcoversions：falcoctl 用于校验工件与运行中 Falco 兼容性的版本端点，指向 Falco 内嵌 webserver 的/versions接口（webserver 配置见 values.yaml，listen_port默认 8765）；
• rulesfilesDir/pluginsDir：工件落盘目录，与 Falco 容器共享；
• stateDir：falcoctl 状态文件目录，在 install 与 follow 之间共享以保持一致。

falcoctl 配置本身保存在 ConfigMap 中并挂载到容器（见 templates/falcoctl-configmap.yaml），该 ConfigMap 还会并入 Chart 自动生成的 container 插件与 k8smeta 插件配置。

基于部署场景的四种升级路径（原文档完整保留）

1. 无插件、仅升级 Falco 版本：

helm upgrade falco falcosecurity/falco \ --namespace=falco \ --reuse-values \ --set falcoctl.artifact.install.enabled=false \ --set falcoctl.artifact.follow.enabled=false

升级既有 release 时 Helm 使用新 Chart 版本，由于新增了模板文件且 values schema 有变化，显式禁用 falcoctl 即可复用旧配置、仅将 Falco 升级到新版本。

2. 无插件、希望自动获取最新 falco-rules：

helm upgrade falco falcosecurity/falco \ --namespace=falco

Helm 先应用新 Chart 的默认 values，再用上一 release 的 values 覆盖，最终结果是：沿用旧配置、运行新版 Falco、falcoctl 安装并自动更新官方规则工件、按follow.every周期检查更新。

3. 有插件、仅升级 Falco：与场景 1 相同的命令（显式禁用 install / follow）。

4. 有插件、希望用 falcoctl 下载插件的 rulesfiles：将 falcoctl 配置写入独立 values 文件（如./falcoctl-values.yaml），核心内容包括falcoctl.artifact.install.enabled=true并设置falcoctl.config.artifact.install.refs=[k8saudit-rules:0.5]（按实际插件名调整），然后执行：

helm upgrade falco falcosecurity/falco \ --namespace=falco \ --reuse-values \ --values=./falcoctl-values.yaml

5. 多数据源场景（syscalls + 插件）：仅升级时同场景 1；同时想用 falcoctl 管理规则与插件时，参照场景 4 的 falcoctl 配置。

Rulesfiles：捆绑时代终结

自 v3.0.0 起，Chart 不再创建包含以下 rulesfiles 的 ConfigMap：

• application_rules.yaml
• aws_cloudtrail_rules.yaml
• falco_rules.local.yaml
• falco_rules.yaml
• k8s_audit_rules.yaml

原因是这些文件已随 Falco 镜像内置，Chart 侧维护纯属冗余且需随每个 Falco 版本手动同步。但镜像内置方案的弊端是：用户必须等待 Falco 新版本才能获得最新规则。更优方案就是前述 falcoctl——从 falcosecurity 组织拉取并安装最新 rulesfiles。注意：如果你此前曾（错误地）自定义过这些文件再部署，请改用 custom rules 机制（customRules配置项，见 values.yaml）。

放弃falcosecurity/falco镜像与 driver-loader 简化

从 Chart v2.0.0 起默认镜像即为falcosecurity/falco-no-driver（v2.0.0 仍兼容falcosecurity/falco，但 v2.2.0 起该镜像组合已被破坏且不再修复）。当前 values.yaml 默认repository: falcosecurity/falco（该仓库现已提供 no-driver 语义的镜像）。

随之而来的是 driver-loader 逻辑简化：现在只有一个开关driver.loader.enabled=true控制 driver-loader init container 的启用/禁用，无需再针对不同镜像做组合判断。driver-loader init container 的实现见 pod-template.tpl：它会挂载/host/proc、/host/boot、/host/lib/modules等宿主机目录，并按driver.kind传入对应参数（kmod/modern_ebpf/auto）；当kind=auto时还会注入FALCOCTL_DRIVER_CONFIG_NAMESPACE与FALCOCTL_DRIVER_CONFIG_CONFIGMAP环境变量，由 falcoctl 驱动配置写入。

升级实操建议

1. 先做配置体检：把旧 values 中的键与本文总览表逐项比对，重点排查falco.grpc*、driver.kind=ebpf/gvisor、collectors.docker/containerd/cri、falcotalon*、driver.module/driver.modern-bpf等已移除或已改名的配置。9.x Chart 的 removedConfigGuard 会在渲染失败时报错并直接指向 BREAKING-CHANGES.md，这是最可靠的校验手段。
2. 按依赖顺序迁移：先处理 driver 与输出通道（9.x/8.x 硬性移除项），再迁移容器元数据采集（7.x），最后评估是否启用 falcoctl（3.x 引入的能力可延后启用，不影响升级本身）。
3. 升级前验证镜像工具依赖：若使用program_output或自定义 init 脚本依赖镜像内工具，确认 distroless 镜像是否满足需求，不满足则显式覆盖image.tag为-debian风味。
4. 善用 dry-run 与单点发布：执行helm upgrade --dry-run观察渲染结果；falcoctl 的follow建议只对 rulesfile 工件启用，插件跟随可能引入非预期行为。

完成上述迁移后，你的部署即可平稳落地到当前 Chart 9.x / Falco 0.44.x 的架构：默认 distroless 镜像 +autodriver（kmod / modern_ebpf）+ containerEngine 元数据采集 + falcoctl 工件管理，同时彻底告别 gRPC 输出、Legacy eBPF 与 gVisor 引擎带来的维护与兼容负担。

• 云原生
• 运行时防护
• IDS
• 应用安全