对 AKS 上的 Inspektor 小工具扩展进行故障排除（预览版）

本文介绍在安装、更新或使用 Azure Kubernetes 服务 (AKS) 上的 Inspektor 小工具群集扩展时可能会遇到的常见错误消息和故障。每个部分都遵循 症状→原因→解决 格式。

Important

AKS 预览功能可在自助服务和自愿选择的基础上启用。预览版按“现状”和“视供应情况”提供，它们不包括在服务级别协议和有限保证范围内。 AKS 预览功能是由客户支持尽最大努力部分覆盖。因此，这些功能并不适合用于生产。有关详细信息，请参阅以下支持文章：

诊断扩展

Inspektor Gadget 扩展会在每个工作节点上于 gadget 命名空间中部署一个名为 gadget 的 DaemonSet。大多数故障都通过扩展状态、基础 Helm 版本或节点上的 eBPF 运行时显现出来。当扩展报告故障时，首先检查其状态以及群集上工作负载的状态。

检查扩展状态：

az k8s-extension show \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget

错误消息记录在输出中 message 数组的 statuses[] 属性中，通常反映的是 Helm 或 Kubernetes API 错误。

检查群集上的基础工作负荷：

kubectl get pods -n gadget -o wide
kubectl describe daemonset -n gadget gadget
kubectl logs -n gadget -l k8s-app=gadget --tail=200

安装因 Helm 渲染或值配置错误而失败

症状： 该扩展报告的状态代码为 InstallationFailed，且消息中包含一个 Helm 模板错误，例如 executing "gadget/templates/..." at <.Values.inspektor-gadget.config.xxx>。

原因：--configuration-settings传递给az k8s-extension create的键与图表支持的值不匹配。 AKS 扩展使用了一个伞式 Helm 图表，该图表将 Inspektor Gadget 图表作为子图表包含其中，并将其别名为 inspektor-gadget。每个以 Inspektor Gadget 为目标的值都必须以 inspektor-gadget. 为前缀。子图表将配置拆分为两种：

根级密钥配置 Kubernetes 资源，例如inspektor-gadget.imageinspektor-gadget.nodeSelector，和inspektor-gadget.hostPID。
config 下的键用于配置 Inspektor Gadget 运行时，例如 inspektor-gadget.config.daemonLogLevel 和 inspektor-gadget.config.hookMode。

一个常见错误是省略 inspektor-gadget. 前缀，或者在根级别设置运行时选项，而不是在 config 下设置。

解决方法：

根据所安装的扩展版本的已记录配置选项验证密钥。

如果以前的安装使版本处于失败状态，请在重试之前删除扩展：

az k8s-extension delete \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget \
    --yes

使用更正的键重新发出命令，例如 inspektor-gadget.config.daemonLogLevel=info。

安装无法解析扩展版本

症状：az k8s-extension create 命令执行失败，并显示类似 ExtensionOperationFailed 的消息 Failed to resolve the extension version from the given values ... does not support release train 'preview' for version '0.53.0'. Please try again with release train "stable".

原因：和--release-train--version值不匹配。请求的版本未发布在您指定的发布序列上，因此无法解析该版本。

解决方法：

安装时不指定版本，以便该扩展能自动从发布系列中获取最新版本：

az k8s-extension create \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget \
    --extension-type microsoft.inspektorgadget \
    --release-train preview

如果您需要特定版本，请使用发布该版本的发布序列。列出集群上该扩展类型支持的版本，然后使用匹配的版本和发布序列重试：

az k8s-extension extension-types list-versions-by-cluster \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --extension-type microsoft.inspektorgadget \
    --release-train preview

安装失败，因为小工具命名空间包含冲突的资源

症状： 安装失败，并显示类似于 rendered manifests contain a resource that already exists ... invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" must equal "gadget" 的消息。

原因： Inspektor 小工具以前是使用 kubectl gadget deploy 或其他 Helm 版本名称部署的，在安装 AKS 扩展之前未完全删除。

解决方法：

如果之前的 kubectl gadget deploy 仍已安装，请将其移除：
```
kubectl gadget undeploy
```

否则，请手动清理命名空间中 gadget 剩余的任何资源：

kubectl delete namespace gadget
kubectl delete clusterrole gadget-cluster-role --ignore-not-found
kubectl delete clusterrolebinding gadget-cluster-role-binding --ignore-not-found
kubectl delete clusterimagepolicy gadget-image-policy --ignore-not-found

重试扩展安装。有关详细信息，请参阅 Inspektor 小工具文档中的“从群集中卸载 ”。

小工具 Pod 卡在 ImagePullBackOff 或 ErrImagePull 中

症状： 命名空间中的 gadget Pod 无法启动和显示 ImagePullBackOff 或 ErrImagePull。

原因： 由于出口防火墙、没有出站规则的专用群集或节点上未配置的代理，群集无法访问 mcr.azk8s.cn 。或者，通过 inspektor-gadget.image.repository 或 inspektor-gadget.image.tag 提供的自定义映像指向了一个没有有效拉取密钥的专用注册表。

解决方法：

通过描述失败的 Pod 确定确切的图像和错误，并查看 “事件 ”部分：
```
kubectl describe pod -n gadget <gadget-pod-name>
```
对于默认的 Microsoft Artifact Registry (MCR) 映像，请验证节点是否可以访问到 mcr.azk8s.cn。如果群集使用用户定义的出站路由（例如具有Azure 防火墙的专用群集），请确保mcr.azk8s.cn*.data.mcr.azk8s.cn并在出口规则中允许。有关详细信息，请参阅 AKS 群集的出站网络和 FQDN 规则。

对于自定义专用注册表，请在 gadget 命名空间中创建拉取机密，并在扩展配置中引用它：

kubectl create secret docker-registry gadget-pull-secret \
    --namespace gadget \
    --docker-server=<registry-server> \
    --docker-username=<username> \
    --docker-password=<password>

az k8s-extension update \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget \
    --configuration-settings "inspektor-gadget.imagePullSecrets[0]=gadget-pull-secret"

安装失败，找不到与 PodMonitor 类型匹配的资源

症状： 该扩展报告一个状态，其中包含代码 InstallationFailed 和类似于以下内容的消息：

unable to build kubernetes objects from release manifest: resource mapping not found for name: "inspektor-gadget" namespace: "gadget" from "": no matches for kind "PodMonitor" in version "azmonitoring.coreos.com/v1"

原因： 你安装了 azureMonitor.enabled=true扩展名。此设置会创建一个 PodMonitor自定义资源，用于将 gadget 指标导出到 Azure Monitor 托管 Prometheus。 PodMonitorCRD（azmonitoring.coreos.com/v1）仅在群集上启用 Azure Monitor 指标加载项时可用。如果未启用加载项，Kubernetes 找不到 CRD，Helm 版本将失败。

解决方法：

选项 A – 在群集上启用Azure Monitor指标。 启用 Azure Monitor 托管 Prometheus 加载项，以注册 PodMonitor CRD，然后重试安装该扩展：
```
az aks update \
     --resource-group myResourceGroup \
     --name myAKSCluster \
     --enable-azure-monitor-metrics
```

选项 B – 禁用Azure Monitor集成。 如果您不需要托管的 Prometheus 集成，例如因为您运行自己的 Prometheus 实例，请将 azureMonitor.enabled 设置为 false：

az k8s-extension create \
     --cluster-type managedClusters \
     --cluster-name myAKSCluster \
     --resource-group myResourceGroup \
     --name inspektor-gadget \
     --extension-type microsoft.inspektorgadget \
     --release-train preview \
     --configuration-settings "azureMonitor.enabled=false"

如果以前的安装使版本处于失败状态，请在重试之前删除扩展：

az k8s-extension delete \
     --cluster-type managedClusters \
     --cluster-name myAKSCluster \
     --resource-group myResourceGroup \
     --name inspektor-gadget \
     --yes

Tip

当您使用自己的 Prometheus 实例时，请配置一个抓取作业，以 gadget 命名空间中带有标签 k8s-app=gadget 的 Pod 为目标，并使用端口 2224 和路径 /metrics。

Gadget Pod 因 eBPF 或 BTF 错误而在启动时崩溃

症状：DaemonSet Pod 进入 CrashLoopBackOff，日志中包含诸如 no BTF found for kernel version 或 field <X> is not a known kernel type 之类的行。

原因： Inspektor 小工具需要启用了 BTF 的 Linux 内核，并且至少需要 Linux 5.10。某些设备可能需要 5.10 基线之外的更新内核功能。

解决方法：

验证每个节点上的内核版本：

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kernelVersion}{"\n"}{end}'

检查是否在节点上启用了 BTF。如果 /sys/kernel/btf/vmlinux 文件存在，则表示已启用 BTF：

kubectl debug node/<node-name> -it --image=mcr.azk8s.cn/cbl-mariner/base/core:2.0 -- ls /sys/kernel/btf/vmlinux

如果内核版本低于小工具所需的最低版本，请将 AKS 节点映像或节点池 Kubernetes 版本升级到附带较新的内核的版本。请参阅升级 Azure Kubernetes 服务 (AKS) 的节点映像。

Gadget Pod 由于 Azure Policy 而卡在 Pending 状态

症状： DaemonSet 的 Pod 一直处于 Pending 状态。 Pod 事件显示来自准入 webhook 的拒绝，例如 admission webhook "validation.gatekeeper.sh" denied the request: Privileged container is not allowed。

原因：Azure Policy 策略计划（例如 Kubernetes 群集不应允许特权容器策略）被分配到群集或订阅，并阻止 gadget DaemonSet 被调度。 DaemonSet 需要特权访问权限和 SYS_ADMIN、、 SYS_PTRACE、 SYS_RESOURCE、 NET_ADMIN、 NET_RAW和 IPC_LOCK Linux 功能来加载 eBPF 程序并检查主机级内核事件。

解决方法：

创建一个 Azure 策略豁免，将 gadget 命名空间排除在限制性策略分配之外。
设置好豁免后，请删除卡住的 Pod，以便 DaemonSet 重新创建它们：
```
kubectl delete pods -n gadget --all
```

kubectl gadget 命令返回版本偏差错误

症状： 运行 kubectl gadget run ... 返回错误，例如 version mismatch， unknown field或 gRPC 解码错误。

原因：kubectl-gadget客户端插件和群集内 DaemonSet 必须完全相同的版本。不支持跨版本兼容性。

解决方法：

查找在群集中部署的版本：

kubectl get daemonset -n gadget gadget -o jsonpath='{.spec.template.spec.containers[0].image}'

使用 kubectl-gadget 将客户端安装或升级到匹配的版本：
```
kubectl krew install gadget
kubectl krew upgrade gadget
```
确认双方匹配：
```
kubectl gadget version
```

注释

如果配置启用了自动升级的扩展，群集端 DaemonSet 版本可能会自动升级。将 kubectl-gadget 客户端固定为相同的次版本，以避免意外偏差。

运行小工具时图像签名验证失败

症状： 拉取或运行小工具时出现错误，错误代码为 the image was not signed by the provided keys: crypto/rsa: verification error。

原因： 小工具映像未使用 Inspektor 小工具守护程序信任的公钥进行签名，或者配置的 inspektor-gadget.config.operator.oci.public-keys 密钥与用于对映像进行签名的密钥不匹配。默认情况下，最新版本启用映像验证。

解决方法：

使用来自 mcr.azk8s.cn/oss/v2/inspektor-gadget/gadget/... 的官方 gadget 映像，这些映像使用项目密钥签名，并默认受信任。
如果您运行来自自己注册表的小工具，请使用您的密钥为其签名，并在扩展配置中的 inspektor-gadget.config.operator.oci.public-keys 下添加相应的公钥。请参阅 “验证小工具图像”。

Warning

仅作为临时解决方法，可以通过设置 inspektor-gadget.config.operator.oci.verify-image=false禁用图像验证。不建议将其用于生产环境，因为这会允许运行未签名或被篡改的 gadget 镜像。

小工具运行但不生成输出

症状： 你已部署并运行了 Inspektor Gadget，但 kubectl gadget run ... 返回的输出为空，或者遗漏了特定工作负荷的事件。

原因： 守护程序的容器挂钩模式与节点上的容器运行时不匹配。 gadget 命令的作用域被限定为排除目标工作负载的命名空间或 Pod 选择器。该小工具需要一个 eBPF 功能，而该节点内核并未提供该功能。

解决方法：

验证节点上的容器运行时：

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.containerRuntimeVersion}{"\n"}{end}'

AKS 节点默认使用容器，因此请使用 hookMode=auto 或 hookMode=podinformer。如果节点使用 CRI-O，请显式配置挂钩模式：

az k8s-extension update \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget \
    --configuration-settings "inspektor-gadget.config.hookMode=crio"

请确保不要无意中将该工具的作用域限定到会排除目标 Pod 的命名空间。使用--all-namespaces或指定正确的命名空间。--namespace <namespace>

检查守护程序日志中是否有跳过或不受支持的程序：

kubectl logs -n gadget -l k8s-app=gadget --tail=500 | grep -i "skip\|unsupported\|error"

小工具无法将数据导出到后端

症状： 导出数据的小工具（例如 profile_cuda）能够运行，但会反复记录导出错误。守护程序日志显示类似于以下内容的条目：

{"gadget":"profile_cuda:v0.53.0","instanceName":"gpu-memory-profiles","level":"error","msg":"emitting and releasing \"allocs\" data: rpc error: code = Unavailable desc = name resolver error: produced zero addresses","type":"gadget-log"}

原因： 该工具被配置为导出到某个后端，例如用于性能剖析数据的 Pyroscope 或用于指标的 OpenTelemetry 收集器，但后端未部署或无法连接。消息 produced zero addresses 表示导出终结点的 DNS 名称未解析为任何地址。

解决方法：

确认目标后端已部署，并且其服务存在于预期的命名空间中：
```
kubectl get service --all-namespaces | grep -i "pyroscope\|otel\|collector"
```
验证为小工具配置的导出终结点是否与后端的服务名称、命名空间和端口匹配。
部署缺少的后端，或更新小工具配置以指向可访问的终结点，然后重新运行小工具。端点恢复正常后，这些错误就会停止出现。

Gadget Pod 不会被调度到虚拟节点上

症状： 安装成功，但 DaemonSet Pod 无法调度到虚拟节点上。 Gadgets 不会返回在其中运行的工作负载的任何事件。

原因： Inspektor 小工具作为特权 DaemonSet 运行，直接在主机 Linux 内核上加载 eBPF 程序。不支持节点不是真正的 Linux 主机（例如由 Azure 容器实例支持的虚拟节点）的拓扑。

分辨率： 使用节点选择器，以便 DaemonSet 仅面向标准 Linux 节点池，而不是虚拟节点：

az k8s-extension update \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget \
    --configuration-settings "inspektor-gadget.nodeSelector.kubernetes\.azure\.com\/agentpool=<nodepool-name>"

对于更复杂的选择器或关联规则，请提供 --configuration-settings-file一个值文件。

卸载扩展会留下过时的资源

症状： 删除扩展后，某些资源将保留在群集中，例如 ClusterImagePolicy/gadget-image-policy用户提供 SeccompProfile 的资源或 gadget 命名空间本身。

原因： 图表不会在卸载时删除群集范围或用户拥有的资源，以防止数据丢失。

分辨率： 手动清理剩余的资源：

kubectl delete clusterimagepolicy gadget-image-policy --ignore-not-found
kubectl delete seccompprofile --all -n gadget --ignore-not-found
kubectl delete namespace gadget --ignore-not-found

注释

ClusterImagePolicy仅当群集上启用了映像完整性功能时，CRD 才存在。如果收到 no matches for kind "ClusterImagePolicy" 错误，可以安全地忽略它。

收集支持请求的诊断信息

在提出支持请求或GitHub问题之前，请收集以下诊断信息。

扩展状态：

az k8s-extension show \
    --cluster-type managedClusters \
    --cluster-name myAKSCluster \
    --resource-group myResourceGroup \
    --name inspektor-gadget \
    --output json > extension.json

群集端状态、节点清单和客户端版本：

kubectl get all -n gadget -o yaml > gadget-resources.yaml
kubectl describe daemonset -n gadget gadget > gadget-daemonset.txt
kubectl get events -n gadget --sort-by='.lastTimestamp' > gadget-events.txt
kubectl logs -n gadget -l k8s-app=gadget --all-containers --tail=2000 > gadget-logs.txt
kubectl get nodes -o wide > nodes.txt
kubectl gadget version > version.txt 2>&1

如果问题出在 AKS 扩展的生命周期上，例如 Azure 资源管理器操作、自动升级或角色分配，请创建 Azure 支持请求。
如果问题与 Inspektor 小工具运行时行为（如特定小工具、eBPF 错误或缺失字段）有关，请在 Inspektor 小工具GitHub存储库中打开问题，并附加收集的诊断。
在 AKS 上安装和配置 Inspektor 小工具扩展
运行小工具以检查 AKS 上的工作负载
Inspektor 小工具扩展概述

Last updated on 2026-07-23

对 AKS 上的 Inspektor 小工具扩展进行故障排除（预览版）

诊断扩展

安装因 Helm 渲染或值配置错误而失败

安装无法解析扩展版本

安装失败，因为小工具命名空间包含冲突的资源

小工具 Pod 卡在 ImagePullBackOff 或 ErrImagePull 中

安装失败，找不到与 PodMonitor 类型匹配的资源

Gadget Pod 因 eBPF 或 BTF 错误而在启动时崩溃

Gadget Pod 由于 Azure Policy 而卡在 Pending 状态

kubectl gadget 命令返回版本偏差错误

运行小工具时图像签名验证失败

小工具运行但不生成输出

小工具无法将数据导出到后端

Gadget Pod 不会被调度到虚拟节点上

卸载扩展会留下过时的资源

收集支持请求的诊断信息

相关内容

其他资源