基于Consul实现K8s外部服务到内部微服务的发现映射

2026年2月19日 星耀云

consul service mesh 与 kubernetes dns 默认不互通，需通过 coredns 转发至 consul dns（8600端口）并配置 sidecar、crd 和 acl 权限；服务名、cluster_name、metadata.name、域名后缀必须严格一致。

基于Consul实现K8s外部服务到内部微服务的发现映射

Consul Service Mesh 与 Kubernetes DNS 不互通是默认行为

Consul 的 consul connect 服务网格和 K8s 原生的 CoreDNS 互不感知，K8s 内 Pod 默认解析不到 Consul 注册的服务名（比如 api.service.consul），反之亦然。这不是配置错了，而是两个系统在设计上就隔离——Consul 的 DNS 服务器监听 8600 端口，K8s 的 /etc/resolv.conf 里压根没它。

常见错误现象：curl: (6) Could not resolve host: payment.service.consul；或 K8s 内部服务调用外部 Consul 服务时直接超时。

  • 必须显式让 K8s Pod 的 DNS 查询能转发到 Consul DNS：通过修改 CoreDNS ConfigMap，添加 consul 插件或 forward 规则
  • Consul DNS 默认只响应 .consul 后缀请求；若想用 payment.default.svc.cluster.local 这类 K8s 域名反向查 Consul 服务，得配 recursors 或启用 enable_k8s_services（仅限 Consul 1.15+）
  • 注意 Consul agent 必须以 -client=0.0.0.0 启动，并开放 8600/udp，否则 CoreDNS 转发失败

k8s-service-to-consul-sync 需要 sidecar + CRD 双驱动

单纯靠 consul-k8s 控制器同步 Service 到 Consul，只能把 K8s Service 当作“静态节点”注册进去，不带健康检查、无实例级元数据、无法对接 Connect 证书体系。真要让 Consul 中的服务支持 mTLS 和细粒度路由，必须让每个 K8s Pod 自带一个 consul connect envoy sidecar，并由控制器为每个 Service 生成对应 ServiceIntentions 和 ProxyDefaults CRD。

使用场景：K8s 内部微服务（如 order）需要安全调用 Consul 外部的 payment 服务，且要求 TLS 终止在 Envoy，而非应用层。

  • 不要只部署 consul-k8s-control-plane，漏掉 consul-connect-injector —— 否则 annotation consul.hashicorp.com/connect-inject: "true" 不生效
  • consul-k8s 默认只同步 ClusterIP 类型 Service；NodePort/LoadBalancer 需手动加 consul.hashicorp.com/service-sync: "true" annotation
  • 若 Consul 集群启用了 ACL，consul-k8s-control-plane 的 SA 必须绑定 service:write 和 node:read 权限，否则注册失败但日志只报 failed to register service，不提示缺权限

consul resolve -service 返回空结果的三个硬条件

consul resolve -service 是验证映射是否成功的最简命令，但它返回空不是因为服务没注册，而是卡在了三个前置检查上：服务必须有健康检查通过、必须属于当前数据中心、且查询客户端必须能访问 Consul agent 的 /v1/health/service/ 接口。

性能影响：该命令每次调用都触发一次完整健康检查聚合，高并发下可能拖慢 Consul API 响应；生产环境别用它做健康探活。

  • 检查 consul catalog services 是否列出目标服务名；没出现说明同步根本没触发
  • 运行 consul health service <code>payment，确认状态是 passing；常见坑是 K8s readiness probe 没对齐 Consul check 的路径或端口
  • 如果 Consul 启用了 primary_datacenter 多中心模式，consul resolve 默认只查本地 DC；跨 DC 查需加 -datacenter=dc2

Envoy bootstrap 配置中 cluster_name 必须与 Consul service.name 严格一致

当 K8s Pod 里的 Envoy 尝试连接 Consul 外部服务时，如果 cluster_name 写成 payment-v1，但 Consul 里注册的是 payment，Envoy 就会报 no healthy upstream —— 它根本不会做名称归一化或前缀匹配。

容易踩的坑：开发者常以为 Consul 支持类似 K8s 的 serviceName:portName 语法，实际 Envoy 的 cluster_name 字段只认 Consul 服务注册时的原始 Name 字段（即 service.name），大小写、连字符、下划线全部敏感。

  • 查真实注册名用 consul catalog service <code>payment，别信 YAML 文件里的 alias 或 label
  • 若 Consul 服务启用了 connect，还需确保 ProxyDefaults CRD 中 config.connect.enabled 为 true，否则 Envoy 不会加载对应 cluster
  • 调试时用 curl -s http://localhost:19000/clusters | grep payment 直接看 Envoy 实际加载的 cluster 名，比猜配置靠谱得多

事情说清了就结束。真正卡住的往往不是哪步没做，而是 Consul 的服务名、Envoy 的 cluster_name、K8s Service 的 metadata.name、CoreDNS 转发规则里的域名后缀——这四个字符串有一处不严丝合缝，整个链路就静默失败。