AKS使用Nginx Ingress暴露CouchDB报503服务不可用问题

Nginx Ingress返回503 Service Temporarily Unavailable的核心逻辑是Ingress控制器无法将请求正常转发到存活的后端服务端点。你已经通过port-forward验证CouchDB实例本身运行正常（port-forward是直接转发到Pod，不经过Service、Ingress链路），问题出在Ingress到CouchDB Pod的转发链路上，按以下优先级排查修复即可。

1. 优先校验后端Service与Endpoint配置 #

这是该场景下最高发的问题点：IBM CouchDB Operator自动创建的Service，不一定直接将5984作为Service的暴露端口，部分版本会做端口重映射，如果你Ingress里配置的后端端口和Service实际端口不匹配，会直接返回503。

• 先检查db命名空间下名为couch的Service配置：

kubectl get svc couch -n db -o yaml

重点确认spec.ports列表中，是否有映射到Pod 5984端口的Service端口，记录下该端口的port字段值，替换掉Ingress配置里写死的5984。

• 再检查Service关联的Endpoint是否正常：

kubectl get endpoints couch -n db

如果返回的ENDPOINTS列为空，说明Service的selector标签和CouchDB Pod的实际标签不匹配，没有选中运行中的Pod，修正selector即可；如果Endpoint有正常的Pod IP，用集群内临时调试Pod验证Service连通性：

kubectl run -it --rm debug --image=curlimages/curl -- curl http://couch.db.svc.cluster.local:<上一步查到的Service端口>

正常情况下该请求会返回带couchdb版本信息的JSON响应，如果连不通，先修复Service问题再验证Ingress。

2. 校验Ingress规则是否被Nginx控制器正确加载 #

• 先确认你配置的public-nginx IngressClass真实存在，且被对应控制器监听：

kubectl get ingressclass public-nginx

检查返回结果里的CONTROLLER字段，需要和你部署的外部Nginx Ingress控制器的控制器名完全一致，否则Ingress规则不会被控制器读取，所有请求都会打到默认后端返回503。

• 确认测试请求携带了正确的Host头：你配置的Ingress规则仅匹配Host: couch.db.svc的请求，如果直接用Ingress公网IP访问、没带对应Host头，Nginx匹配不到规则会直接返回默认503。正确测试命令示例：

curl -H "Host: couch.db.svc" http://<Nginx Ingress的公网访问IP>

• 修正后端健康检查配置：默认Nginx Ingress会用根路径做后端健康检测，而CouchDB单节点模式下未认证访问根路径可能返回非200状态码，导致Ingress误将后端标记为不健康。给Ingress添加如下annotation，用CouchDB官方自带的/_up健康检查端点（正常返回200）即可：

metadata:
  annotations:
    nginx.ingress.kubernetes.io/healthcheck-path: /_up

3. 检查Ingress控制器日志定位转发错误 #

如果前面的配置都没问题，直接查看Nginx Ingress控制器的日志，能直接看到转发失败的具体原因：

• 先找到Nginx Ingress控制器的Pod：

kubectl get pods -n <你部署public-nginx Ingress控制器的命名空间> -l app.kubernetes.io/name=ingress-nginx

• 过滤和couch服务相关的错误日志：

kubectl logs <ingress-controller-pod名称> -n <ingress命名空间> | grep -E 'couch|503|upstream'

常见报错包括：连接被拒绝（端口配置错误）、没有权限读取Endpoint（RBAC配置缺失）、上游超时（网络策略拦截）。

• 如果是RBAC权限问题，补全Ingress控制器对应的ClusterRole权限，允许其读取全集群的Service、Endpoint、Pod资源即可。
• 如果是超时问题，检查AKS集群的网络策略：如果db命名空间配置了默认拒绝入站的规则，需要添加策略允许Ingress控制器所在命名空间的Pod访问CouchDB Service的对应端口。

内容的提问来源于stack exchange，提问作者Shadi Albatal