17370845950

创建Ingress资源必须显式指定apiVersion: networking.k8s.io/v1和kind: Ingress，字段名、嵌套结构、ingressClassName、TLS Secret命名及namespace均需严格匹配规范，否则导致验证失败或流量不通。

用 client-go 创建 Ingress 资源必须指定 apiVersion 和 kind

直接写 YAML 结构体却忘记设置 apiVersion: networking.k8s.io/v1 和 kind: Ingress，会导致 validation failure 错误。client-go 不会自动补全这些字段，必须显式声明。

常见错误现象：error validating data: unknown object type "nil" 或 the server could not find the requested resource，往往就是版本或类型没对上。

• networking.k8s.io/v1 是当前稳定版（K8s ≥ 1.19），不要用已废弃的 extensions/v1beta1
• struct 字段名需严格匹配 OpenAPI 定义，比如 Spec 首字母大写，spec 小写会静默失败
• 使用 unstructured.Unstructured 动态构造时，必须通过 SetGroupVersionKind 设置 schema.GroupVersionKind

IngressRule 中 host 和 http.paths 的嵌套结构容易写错

Ingress 的路由逻辑依赖 rules[].host + rules[].http.paths[].path + paths[].backend.service.name 三层嵌套，少一层或字段名拼错（如写成 servicename）就会导致 404 或 backend not found。

典型场景：想把 app.example.com/api 转发到 service api-svc 的 8080 端口，但 path 没加前缀匹配修饰符，结果所有路径都命中。

• path 必须以 / 开头；若用 PathPrefix 类型（v1），需在 pathType 显式设为 "Prefix"
• service.name 和 service.port.name（或 .number）必须与目标 Service 完全一致，大小写敏感
• 多个 rule 可共用一个 host，但 path 不能重叠；重叠时行为由 Ingress Controller 决定（如 nginx-ingress 用最长匹配）

ing := &networkingv1.Ingress{
	ObjectMeta: metav1.ObjectMeta{
		Name:      "my-ingress",
		Namespace: "default",
	},
	Spec: networkingv1.IngressSpec{
		Rules: []networkingv1.IngressRule{
			{
				Host: "ap
p.example.com",
				IngressRuleValue: networkingv1.IngressRuleValue{
					HTTP: &networkingv1.HTTPIngressRuleValue{
						Paths: []networkingv1.HTTPIngressPath{
							{
								Path: "/api",
								PathType: &pathTypePrefix,
								Backend: networkingv1.IngressBackend{
									Service: &networkingv1.IngressServiceBackend{
										Name: "api-svc",
										Port: networkingv1.ServiceBackendPort{
											Number: 8080,
										},
									},
								},
							},
						},
					},
				},
			},
		},
	},
}

IngressClass 名称不匹配导致资源不生效

集群中若有多个 Ingress Controller（如 nginx、traefik、alb），必须通过 ingressClassName 字段绑定对应 Class，否则 Ingress 可能被忽略——没有报错，但流量完全不通。

验证方式：运行 kubectl get ingressclass 查看可用 class 名，再检查 Ingress 的 spec.ingressClassName 是否与之完全一致（包括大小写和连字符）。

• 未设置 ingressClassName 时，部分旧版集群会回退到默认 controller，但 v1+ 默认不再隐式 fallback
• Class 对象本身需有 controller 字段（如 k8s.io/ingress-nginx），该值需与 Ingress Controller 启动参数 --controller-class 匹配
• 修改已有 Ingress 的 ingressClassName 不会触发热更新，需删除重建

TLS 配置缺失或 Secret 名称错误导致 HTTPS 无法握手

Ingress 的 TLS 终止依赖 spec.tls[] 中的 hosts 和 secretName，且对应 Secret 必须存在于同一 namespace，类型为 kubernetes.io/tls。

常见错误：Secret 名字拼错、证书私钥格式不对（如用了 PEM 标准以外的换行）、Secret 中 key 名不是 tls.crt 和 tls.key。

• secretName 必须是字符串，不能是空格或斜杠；建议用 kubectl create secret tls 命令生成，避免手动 base64 出错
• 多个 host 可共用一个 Secret，但 Secret 必须包含所有 host 的 SAN（Subject Alternative Name）
• 如果 Ingress Controller 不支持 TLS 1.3 或 SNI，即使配置正确，客户端也可能报 ssl_error_no_cypher_overlap

最常被忽略的是 namespace 隔离：Ingress 和它引用的 Secret 必须在同一个 namespace，跨 namespace 的 Secret 引用不被支持。这点和 ServiceAccount、ConfigMap 不同，容易踩坑。