Day02 K3s NGF（Nginx Gateway Fabric）单 Worker 环境网关更新与故障处置 SOP

# K3s NGF（Nginx Gateway Fabric）单Worker环境网关更新与故障处置SOP
> 环境信息
> - Master：192.168.3.***
> - Worker：192.168.3.***
> - 命名空间：ops-prod
> - 网关名称：private-gateway

## 一、常规操作：单Worker节点NGF网关配置更新标准流程
适用场景：集群仅1台Worker，调整NGF网关副本、重载网关配置、发布安全拦截策略
> 执行节点：Master 192.168.3.***

1. 固定kubeconfig，防止kubectl报8080连接拒绝
```bash
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get nodes

1. 修改 helm values 适配单 Worker 节点副本数

bash

vi /root/k8s-config/k3s-private/gateway/helm-values-ngf.yaml
# 修改 nginx.pod.replicas: 2 → replicas: 1，保存退出

1. 执行 NGF 网关重载脚本

bash

bash /root/k8s-config/k3s-private/scripts/restart-ngf.sh

1. 强制清理旧异常网关 Pod，触发重建

bash

kubectl delete pod -n ops-prod -l gateway.networking.k8s.io/gateway-name=private-gateway --force --grace-period=0

1. 持续监控 Pod 启动状态

bash

kubectl get pods -n ops-prod -l gateway.networking.k8s.io/gateway-name=private-gateway -o wide -w

✅ 正常预期：Init 容器执行完成 → Pod 变为1/1 Running，再执行后续步骤 ❌ 异常识别：Pod 长时间卡在0/1 Init:0/1，禁止无限等待，执行下文故障流程

1. 切换至 Worker 192.168.3.***，放行 NodePort 端口防火墙

bash

firewall-cmd --add-port=30000-32767/tcp --permanent
firewall-cmd --reload
firewall-cmd --list-ports

1. 网关功能安全校验

• Master 新开终端持续运行端口转发：

bash

kubectl port-forward -n ops-prod svc/private-gateway-nginx 30080

• 原有终端执行安全策略校验脚本

bash

HOST=jyjzhfw.qiantang.gov.cn bash /root/k8s-config/k3s-private/scripts/verify-actuator-security.sh

✅ 判定标准：脚本全部输出PASS，网关 actuator 安全拦截功能生效

二、故障处置：NGF 网关 Pod 持续卡在 0/1 Init:0/1

遇到问题

执行网关更新重建后，网关 Pod 状态长期显示 0/1 Init:0/1。 现象说明：初始化容器卡住，持续等待会出现容器反复重启、启动失败，不能单纯无限等待。

说明：本集群 Init 容器为 SnippetsPolicy 策略注入容器（开启snippets.enable=true），作用：写入 actuator 403 拦截 Nginx 配置。

常见根因

1. Init 容器镜像拉取失败
2. RBAC 权限不足，无法写入网关 Nginx 配置
3. Helm 更新后旧资源残留，资源未完全重建

标准化排查 & 解决步骤（Master 节点执行）

1. 查看 Pod 事件与初始化容器信息

bash

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl describe pod <pod名称> -n ops-prod

重点查看：

• Init Containers 区块初始化容器名称、启动命令
• 底部 Events 事件，捕获镜像拉取、权限、命令执行报错

1. 优先查看 Init 容器日志（最直观定位报错）

bash

kubectl logs <pod名称> -n ops-prod -c init

1. 无明确日志输出时，执行完整重建修复

bash

# 强制删除卡住异常Pod
kubectl delete pod <pod名称> -n ops-prod --force --grace-period=0
# 重新执行网关重载脚本
bash /root/k8s-config/k3s-private/scripts/restart-ngf.sh
# 再次监控Pod状态
kubectl get pods -n ops-prod -l gateway.networking.k8s.io/gateway-name=private-gateway -o wide -w

超时判定阈值

超过3 分钟 仍然停留在Init:0/1，必须介入排查，禁止持续等待。

三、常用命令速查（可直接复制复用）

bash

# NGF网关重载脚本
bash /root/k8s-config/k3s-private/scripts/restart-ngf.sh

# 批量清理网关异常Pod
kubectl delete pod -n ops-prod -l gateway.networking.k8s.io/gateway-name=private-gateway --force --grace-period=0

# 查询Init容器日志模板
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl logs private-gateway-nginx-xxx -n ops-prod -c init
kubectl describe pod private-gateway-nginx-xxx -n ops-prod