KubeSphere Gateway 显示 Faulted 状态怎么排查【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere在 KubeSphere 中Gateway 扩展基于 ingress-nginx为集群、工作空间、项目三个层级提供外部访问入口每个 Gateway 都是kubesphere-controls-system命名空间下的一个 Gateway 资源CRDgateway.kubesphere.io/v2alpha2背后对应一个独立的 ingress-nginx Helm release。它的status.state有五种取值Creating、Updating、Running、Faulted、Stopped。当一个 Gateway 的status.state显示Faulted时按项目文档的定义意味着对应的 Deployment 缺失、被意外停止或健康探针超时。本文说明如何用 kubectl 定位具体原因、确认相关对象并最终把 Gateway 恢复到Running。适用前提集群已安装 Gateway 扩展且你有可访问kubesphere-controls-system命名空间的 kubectl 权限。排查前先定位出错的 Gateway先确认 Gateway 扩展确实已安装kubectl get installplans.kubesphere.io gateway --ignore-not-found如果找不到 InstallPlan说明扩展本身没装问题不在单个 Gateway 上。安装正常后按层级列出 Gateway找到显示Faulted的那一个。三级 Gateway 的命名规则和所在命名空间是固定的层级名称格式命名空间Clusterkubesphere-router-clusterkubesphere-controls-systemWorkspacekubesphere-router-workspace-{workspace}kubesphere-controls-systemProjectkubesphere-router-{namespace}kubesphere-controls-systemecho Cluster Gateway kubectl get gateways.gateway.kubesphere.io -n kubesphere-controls-system \ -l kubesphere.io/gateway-typecluster echo -e \n Workspace Gateways kubectl get gateways.gateway.kubesphere.io -n kubesphere-controls-system \ -l kubesphere.io/gateway-typeworkspace echo -e \n Project Gateways kubectl get gateways.gateway.kubesphere.io -n kubesphere-controls-system \ -l kubesphere.io/gateway-typeproject找到目标后把后面的排查命令里的变量设好。GW_NAME换成你实际要排查的 Gateway 名称按上表命名规则例如集群级就是kubesphere-router-cluster项目级就是kubesphere-router-你的项目命名空间GW_NSkubesphere-controls-system GW_NAMEkubesphere-router-cluster # 替换为实际要排查的 Gateway 名称 # app.kubernetes.io/instance 优先取 Helm release 名取不到时回退为 Gateway 名 GW_INSTANCE$(kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o jsonpath{.status.helmRelease.name} 2/dev/null) if [ -z $GW_INSTANCE ]; then GW_INSTANCE$GW_NAME fiGW_INSTANCE是后续按标签过滤 Pod 和 Deployment 用的标识正常路径下它来自 Gateway 的status.helmRelease.name如果该字段还没有值例如刚创建不久就回退为 Gateway 名称本身。用下面两条命令确认当前状态和条件作为排查的基线kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o wide kubectl describe gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME输出里的状态含义如下State含义Creating首次 Helm 安装进行中UpdatingHelm 升级进行中spec 发生了变化Running完全可用所有副本可用FaultedDeployment 缺失、意外停止或健康探针超时Stopped被有意缩容到零副本注意区分Faulted和StoppedStopped是刻意把副本数缩到零的结果不属于故障只有Faulted才需要按本文排查。执行 Faulted 排查命令项目文档给出的Faulted排查命令如下按顺序执行kubectl get deployment -n $GW_NS $GW_NAME -o wide kubectl describe deployment -n $GW_NS $GW_NAME kubectl get pods -n $GW_NS -l app.kubernetes.io/instance$GW_INSTANCE -o wide POD_NAME$(kubectl get pods -n $GW_NS -l app.kubernetes.io/instance$GW_INSTANCE -o jsonpath{.items[0].metadata.name}) kubectl describe pod -n $GW_NS $POD_NAME kubectl logs -n $GW_NS $POD_NAME --tail100每条命令对应的判断点get deployment -o wide/describe deployment确认 Deployment 是否还存在、副本数是否符合预期。Faulted的第一种成因就是 Deployment 缺失如果这里查不到 Deployment说明问题出在控制器没有把它创建出来或它被删除了而不是 Pod 本身。get pods -l app.kubernetes.io/instance$GW_INSTANCE -o wide按 Helm 实例标签过滤出这个 Gateway 的 ingress-nginx Pod看 Pod 处于什么状态Running、CrashLoopBackOff、ImagePullBackOff、Pending 等。describe pod重点看 Events 部分镜像拉取失败、探针超时、调度失败这类问题会直接出现在事件里。logs --tail100查看控制器进程最近的 100 行日志确认进程崩溃前的最后输出。按文档列出的四类常见原因判断项目文档将Faulted的常见原因归纳为四类镜像拉取失败、资源约束、端口冲突、缺失的 ConfigMap/Secret。对照上面命令的输出判断属于哪一类镜像拉取失败describe pod的 Events 里会出现拉取相关事件Pod 状态通常是ImagePullBackOff或ErrImagePull。资源约束Pod 因资源不足起不来或因超出 limits 被 OOMKilled后一种现象会在describe pod的容器状态里体现为OOMKilled。端口冲突Pod 无法在预期端口上监听日志或事件里体现为端口占用/绑定失败。缺失的 ConfigMap/Secretingress-nginx 依赖的 ConfigMap 或 Secret 不存在Pod 会启动失败或反复重启。如果 Pod 处于CrashLoopBackOff文档给出了针对崩溃循环的补充命令可以接着执行kubectl logs -n $GW_NS -l app.kubernetes.io/instance$GW_INSTANCE --tail100 --previous kubectl get events -n $GW_NS --sort-by.lastTimestamp | tail -20 kubectl exec -n $GW_NS -l app.kubernetes.io/instance$GW_INSTANCE -- cat /etc/nginx/nginx.conf 2/dev/null | head -50 kubectl get configmap -n $GW_NS -l app.kubernetes.io/instance$GW_INSTANCE -o yaml其中--previous读取上一次崩溃前容器的日志get events查看命名空间内最近的事件exec那条用于在容器还活着时查看实际生效的 nginx 配置容器已退出时会失败属于预期行为命令里的2/dev/null已处理。这一分支的常见原因包括nginx 配置错误、端口冲突、资源限制OOMKilled、依赖的 ConfigMap/Secret 缺失。确认恢复修复对应原因例如换可达的镜像地址、调大资源 limits、补回缺失的 ConfigMap/Secret后重新检查 Gateway 状态kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o wide kubectl get pods -n $GW_NS -l app.kubernetes.io/instance$GW_INSTANCE成功条件是status.state回到Running——按状态表定义Running表示所有副本可用、Gateway 完全正常工作同时status.conditions中typeGatewayReady的条件应为True。副本全部可用但状态迟迟不变时先确认 Gateway 控制器自身是否在正常调谐这属于下面一节的另一条排查路径。边界与相邻问题如果 Gateway 卡在Creating或Updating而不是Faulted那是安装/升级流程的问题排查路径不同应检查 Chart ConfigMap 是否缺失或损坏、Helm 执行是否超时config.helmExecutor.timeout默认值为10m、以及extension-gateway命名空间下gateway-controller-manager的日志而不是本文的 Deployment/Pod 路径。如果控制器完全不调谐任何状态变化都没有进展先确认extension-gateway命名空间下gateway-controller-manager的 Pod 是否在运行再查其日志、ValidatingWebhookConfiguration 和 RBAC 权限这也是文档中独立列出的一节。更完整的命令上下文和 InstallPlan 可配置项例如控制器镜像registry/tag、helmExecutor超时与资源限制见 SKILL.md 和 extension-values.md状态轮询可以用 check-status.shquick单次快照、poll轮询默认 300 秒超时。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考