2. 环境准备与常见部署陷阱：Kubernetes 集群版本兼容性、Istio/Contour 网关配置、Knative 自定义资源安装验证

在开始 Knative Service 故障排查之前，必须确保底层环境符合 Knative 的运行要求。本章聚焦于三个最容易引发“部署后不可用”问题的环节：Kubernetes 集群版本兼容性、网关（Istio / Contour）配置以及Knative 自定义资源安装验证。跳过这些检查，后续的故障现象将难以定位。

2.1 Kubernetes 集群版本兼容性矩阵

Knative 对 Kubernetes 版本有严格的依赖。使用不兼容的版本会导致 API 资源无法注册、控制器崩溃或网络策略失效。下表列出了 Knative 1.12+ 与主流 Kubernetes 版本的兼容关系：

2.2 网关层配置：Istio 与 Contour 的部署陷阱

Knative 依赖网关组件将外部流量路由到无服务器服务。Istio 和 Contour 是两种最常用的选择，但它们的配置细节经常导致流量无法到达 Pod。

2.2.1 Istio 网关配置要点

• 自动注入标签：Knative 所在的命名空间必须打上 istio-injection=enabled 标签，否则 sidecar 不会自动注入。
• Gateway 资源定义：Knative 默认使用 knative-serving 命名空间下的 knative-ingress-gateway。如果自定义了 Gateway 名称，必须同步修改 config-network ConfigMap 中的 gateway.name 字段。
• HTTPS 证书挂载：如果启用了 TLS，证书 Secret 必须存在于 istio-system 或 knative-serving 命名空间，并且 Gateway 的 tls 字段要正确引用。

2.2.2 Contour 网关配置要点

• Envoy 服务类型：Contour 的 Envoy 服务默认是 LoadBalancer。在本地开发环境（如 Kind 或 Minikube）中，需要改为 NodePort 或使用 kubectl port-forward 才能访问。
• HTTPProxy CRD 版本：Knative 要求 Contour 的 HTTPProxy CRD 版本为 v1。如果集群中残留了旧版 v1beta1 资源，会导致 Knative 网络控制器无法创建路由。
• 域名解析：Contour 默认不处理外部域名。需要确保 knative-serving 的 ConfigMap config-domain 中配置了正确的域名后缀（如 example.com），否则 Knative Service 的 URL 将无法被解析。

2.3 Knative 自定义资源安装验证

安装 Knative 后，必须验证关键 CRD 是否已正确注册。缺失或版本错误的 CRD 会导致 ksvc、configuration、revision 等资源无法创建。

2.3.1 核心 CRD 清单

2.3.2 验证步骤

1. 检查 CRD 状态：执行 kubectl get crd | grep knative.dev，确认所有 CRD 的 ESTABLISHED 列为 True。
2. 检查 API 服务：执行 kubectl get apiservice | grep knative，确保 AVAILABLE 列为 True。
3. 检查控制器日志：执行 kubectl logs -n knative-serving deployment/controller，搜索 error 或 failed 关键字。
4. 创建测试 Service：部署一个最小化的 Knative Service，观察是否进入 Ready 状态。

#!/bin/bash
echo "=== CRD 状态 ==="
kubectl get crd | grep knative.dev | awk '{print $1, $2}'
echo "=== API 服务 ==="
kubectl get apiservice | grep knative | awk '{print $1, $4}'
echo "=== 控制器 Pod ==="
kubectl get pods -n knative-serving -o wide
echo "=== 网关 Pod ==="
kubectl get pods -n istio-system -o wide 2>/dev/null || kubectl get pods -n contour-system -o wide 2>/dev/null

2.4 常见部署陷阱速查表