ExternalDNS Gateway API Route Sources 完整指南：支持版本、Hostname 解析、注解放置与部署配置

云原生【免费下载链接】external-dnsConfigure external DNS servers dynamically from Kubernetes resources项目地址https://gitcode.com/gh_mirrors/ex/external-dns点击查看免费下载本篇技术指南围绕 ExternalDNS 的 Gateway API Route Sources 展开系统讲解 gateway-httproute、gateway-grpcroute、gateway-tlsroute、gateway-tcproute、gateway-udproute 五类 Route 源的功能原理、支持的 Gateway API 版本矩阵、Hostname 与目标地址Target的解析规则、注解的放置约定、常见错误规避以及包含 RBAC 的完整部署清单。读者学完后能够准确为 Gateway API 资源配置 DNS 记录同步处理 CNAME 冲突、AWS Route53 路由策略、Cloudflare 代理记录等真实场景。概述什么是 Gateway API Route SourcesExternalDNS 的 Gateway API Route Sources 是一组以gateway-*前缀命名的数据源它们分别监听gateway.networking.k8s.io分组下的 HTTPRoute、GRPCRoute、TLSRoute、TCPRoute、UDPRoute 资源并基于这些资源的内容生成 DNS 记录。该文档定位为各 Provider 专属安装教程的补充说明适用于已经完成某个 DNS Provider 配置、需要进一步接入 Gateway API 资源的场景。从源码结构看这五类 Route 源共享同一套核心实现在 source/gateway.go 中gatewayRouteSource结构体通过gatewayRoute接口统一抽象了五类 Route 的公共行为获取对象元数据、Hostnames、ParentRefs、Protocol、RouteStatus而每个具体源只负责创建对应的 informer例如 source/gateway_httproute.go、source/gateway_grpcroute.go 分别以HTTPRoute、GRPCRoute为 kind 调用同一个newGatewayRouteSource构造器。支持的 API 版本与渠道ExternalDNS 使用 Gateway API CRD这些 CRD 在 Standard标准和 Experimental实验渠道中按不同版本发布。当前仓库支持的版本矩阵如下资源ExternalDNS 使用的 API 版本最低 Standard 渠道版本Experimental 渠道版本Gatewayv1v1.0.0v1.0.0HTTPRoutev1v1.0.0v1.0.0GRPCRoutev1v1.1.0v1.1.0ListenerSetv1v1.5.0v1.5.0TLSRoutev1v1.5.0v1.0.0TCPRoutev1alpha2TBDv1.0.0UDPRoutev1alpha2TBDv1.0.0各版本要点如下Gateway 与 HTTPRoute在 Gateway API v1.0.0 晋升到 Standard 渠道使用 v1 API。这是最基础、最常用的一组资源。GRPCRoute在 Gateway API v1.1.0 晋升到 Standard 渠道使用 v1 API。ListenerSet在 Gateway API v1.5.0 晋升到 Standard 渠道使用 v1 API。它允许为已有 Gateway 附加额外的 listener。以 ListenerSet 作为parentRef的 Route 会被自动支持——ExternalDNS 会沿着 ListenerSet 追溯到其父 Gateway 来解析目标地址。ListenerSet 资源上也支持external-dns.kubernetes.io/target注解且其优先级高于父 Gateway 上的同名注解。ListenerSet 支持需要启用--gateway-listener-sets标志。TLSRoute在 Gateway API v1.5.0 晋升到 Standard 渠道但自 v1.0.0 起就以 v1alpha2 存在于 Experimental 渠道。ExternalDNS 出于对旧 CRD 的兼容仍使用 v1alpha2 API但该版本已弃用并将在未来版本中移除届时 ExternalDNS 需要迁移到 v1。TCPRoute 与 UDPRoute仍处于实验状态仅在 Experimental 渠道以 v1alpha2 提供。这些约束与 CLI 标志定义一致在 pkg/apis/externaldns/types.go 中--gateway-listener-sets的标志说明明确写着启用 Gateway API 源的 ListenerSet 支持需要 Gateway API v1.5 CRD。Hostname五种 Route 的域名来源差异HTTPRoute 与 TLSRoute 的 spec 中以及它们关联的 Gateway Listener 上都包含 ExternalDNS 会使用的 hostname。然而TCPRoute 与 UDPRoute 的 spec 中不允许指定任何 hostname因此对这两种 Route官方推荐通过external-dns.kubernetes.io/hostname注解为其提供域名。对于 HTTPRoute 和 TLSRouteExternalDNS 同样支持该注解但强烈建议优先使用 spec 中声明的 hostname因为最终路由请求/连接的 Gateway 不会识别注解中额外的 hostname——注解只是 ExternalDNS 用来生成记录的不会影响 Gateway 的实际转发行为。从源码实现看source/gateway.go 的resolveHostnames方法按以下顺序收集 Route 的 hostnamespec.hostnamesGRPCRoute、HTTPRoute、TLSRoute 各自spec.hostnames中的每个值注解 hostnameexternal-dns.kubernetes.io/hostname注解中的值若指定了--ignore-hostname-annotation标志则跳过FQDN 模板若前两步未产生任何 endpoint或指定了--combine-fqdn-annotation标志则追加由--fqdn-template生成的 hostnameListener 兜底若 Route 自身未声明 hostnamespec.hostnames为空则回退使用其挂载的每个 Gateway Listener 的hostname。其中合并去重环节由 source/gateway.go 的uniqueTargets完成对同一个 host 命中多个匹配 Listener 时其目标 IP 会被去重避免重复生成记录。注解放置位置决定是否生效注解放置约定ExternalDNS 从不同的 Gateway API 资源上读取不同的注解这与 Gateway API 的架构设计保持一致——Gateway 定义基础设施IP 地址、listenerRoute 定义应用层 DNS 记录Gateway 注解只从 Gateway 资源读取external-dns.kubernetes.io/targetListenerSet 注解同样支持external-dns.kubernetes.io/target且当 Route 引用某个 ListenerSet 时ListenerSet 的 target 注解优先于父 Gateway 的 target 注解需要--gateway-listener-sets标志Route 注解其余所有注解hostname、ttl、controller、provider 专属注解都从 Route 资源HTTPRoute、GRPCRoute、TLSRoute、TCPRoute、UDPRoute读取。源码实现印证了这一约定在 source/gateway.go 中newGatewayListenerObject通过annotations.TargetsFromTargetAnnotation(gw.Annotations)从 Gateway 读取 target而 provider 专属注解、TTL 则在 source/gateway.go 的Endpoints方法中从 Route 的 annotations 提取。示例一Cloudflare 代理记录apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: my-gateway namespace: default annotations: # ✅ 正确target 注解放在 Gateway 上 external-dns.kubernetes.io/target: 203.0.113.1 spec: gatewayClassName: cilium listeners: - name: https hostname: *.example.com protocol: HTTPS port: 443 --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: my-route annotations: # ✅ 正确provider 专属注解放在 HTTPRoute 上 external-dns.kubernetes.io/cloudflare-proxied: true external-dns.kubernetes.io/ttl: 300 spec: parentRefs: - name: my-gateway namespace: default hostnames: - api.example.com rules: - backendRefs: - name: api-service port: 8080示例二AWS Route53 路由策略apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: aws-gateway annotations: # ✅ 正确target 注解放在 Gateway 上 external-dns.kubernetes.io/target: alb-123.us-east-1.elb.amazonaws.com --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: weighted-route annotations: # ✅ 正确AWS 专属注解放在 HTTPRoute 上 external-dns.kubernetes.io/aws-weight: 100 external-dns.kubernetes.io/set-identifier: backend-v1 spec: parentRefs: - name: aws-gateway hostnames: - app.example.com其中set-identifier用于在同域名同类型的多个记录集之间做区分是 AWS Route53 加权、延迟、故障转移、地理定位、地理邻近、多值等路由策略所必需的。相关说明在 docs/annotations/annotations.md 中有更完整的解释——该注解虽然设计上是 Provider 无关的但主要配合 AWS Route53 使用。常见错误注解放错位置以下两种放置方式会被 ExternalDNS 忽略属于典型误用❌错误做法 1把 provider 专属注解放在 Gateway 上kind: Gateway metadata: annotations: # ❌ 这些注解在 Gateway 上会被忽略 external-dns.kubernetes.io/cloudflare-proxied: true external-dns.kubernetes.io/ttl: 300❌错误做法 2把 target 注解放在 Route 上kind: HTTPRoute metadata: annotations: # ❌ 这个注解在 Route 上会被忽略 external-dns.kubernetes.io/target: 203.0.113.1类似的提示也出现在 docs/annotations/annotations.md把set-identifier放在 Gateway 上同样是常见错误因为 Gateway 源只读取target注解其余注解hostname、ttl、controller、provider 专属注解如cloudflare-*、aws-*、scw-*一律读取自 Route 资源。gateway-hostname-source解决 CNAME 与 spec hostname 冲突为什么需要它在某些场景下ExternalDNS 同时处理 hostname 注解和*Routespec 中的 hostname 时会产生冲突的 DNS 记录。典型场景是使用 CNAME 记录company.public.example.com - company.private.example.com将流量导向私有端点例如 AWS PrivateLink某些第三方服务要求流量在公网上解析到 Gateway API 负载均衡器但company.public.example.com这个域名必须保持不变以免破坏已有的 CNAME 配置若不加以控制ExternalDNS 会因为两种 hostname 来源冲突用 A 记录覆盖掉已有的 CNAME 记录。用法在 Route 上设置注解external-dns.kubernetes.io/gateway-hostname-source: annotation-only即可让 ExternalDNS忽略 HTTPRoute spec 中定义的 hostname只使用注解中指定的 hostname从而兼容复杂的 DNS 配置、避免记录冲突。该注解支持的取值定义于 source/annotations/annotations.go常量在 source/gateway.go取值行为annotation-only只使用 Route 注解中的域名defined-hosts-only只使用 Route spec 中定义的域名不设置spec 与注解中的域名都使用source/gateway.go 的resolveHostnames展示了具体逻辑当取值为annotation-only时直接返回注解中的 hostname取值为defined-hosts-only时只保留 spec hostnames 并可选追加模板结果遇到非法取值时会输出告警日志并回退到默认行为等同于注解不存在。示例apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: annotations: external-dns.kubernetes.io/gateway-hostname-source: annotation-only external-dns.kubernetes.io/hostname: company.private.example.com spec: hostnames: - company.public.example.com在这个例子中ExternalDNS 只会基于注解为company.private.example.com创建 DNS 记录忽略 HTTPRoute spec 中的hostnames字段。这样既避免了与已有 CNAME 记录冲突又能让特定端点在公网正常解析。关于注解的完整列表可参考 annotations 文档其中明确说明该注解应放在 Route 资源上而非 Gateway 资源上。域名Domain计算与匹配流程要理解 Route 源如何决定生成哪些域名需要结合 docs/sources/gateway.md 中的说明——该文档是五个 Route 源gateway-grpcroute、gateway-httproute、gateway-tcproute、gateway-tlsroute、gateway-udproute的通用行为描述。计算过程分三步收集 Route 的域名集合来源依次为 spec.hostnames、hostname 注解、FQDN 模板、Listener hostname 兜底即上文 resolveHostnames 的四个来源。遍历status.parents只处理满足匹配 Gateway 条件、且至少有一个匹配 listener 的 parent。按 listener 收窄域名对每个匹配的 listener若其带hostname则将 Route 域名集合收窄到与 listener hostname 重叠的部分若 listener 没有hostname则使用未收窄的完整域名集合。匹配 Gateway匹配 Gateway 通过遍历 Route 的status.parents完成满足以下全部条件才算匹配parentRef.group必须是gateway.networking.k8s.ioparentRef.kind必须是Gateway否则忽略指定了--gateway-name时parentRef.name必须等于指定值指定了--gateway-namespace时parentRef.namespace必须等于指定值指定了--gateway-label-filter时对应 Gateway 必须匹配指定的标签过滤器Gateway 必须存在且必须已接受该 Route即status中的Accepted条件为 True。例如下面的示例中两个 HTTPRoute 分别引用名为internal和external的 Gateway若使用--gateway-nameexternal则只有echo2会被纳入 DNS 记录生成apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: echo spec: hostnames: - echoserver.example.org parentRefs: - group: networking.k8s.io kind: Gateway name: internal --- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: echo2 spec: hostnames: - echoserver2.example.org parentRefs: - group: networking.k8s.io kind: Gateway name: external注意上面示例中parentRef.group被刻意写成了networking.k8s.io非 gateway 分组仅用于演示--gateway-name的过滤效果实际使用中 group 应为gateway.networking.k8s.io。匹配 Listener对 parent 的parentRef.sectionName对应的所有 listener 进行遍历需要满足listener 的protocol字段必须与 Route 的类型匹配对应关系如下Route kind允许的协议GRPCRouteHTTP, HTTPSHTTPRouteHTTP, HTTPSTCPRouteTCPTLSRouteTLSUDPRouteUDP若parentRef.port指定了端口则 listener 的port必须与之匹配listener 的allowedRoutes配置必须允许该 Route包括命名空间来源与 Route kind 约束。协议匹配的底层实现是 source/gateway.go 的gwProtocolMatchesHTTP 与 HTTPS 视为同一协议且当 Listener 为 TLS、Route 为 TCP 时也视为匹配。Hostname 重叠判定则依赖 source/gateway.go 的gwMatchingHost以*.开头的通配符 hostname 按后缀匹配*.example.com可匹配test.example.com和foo.test.example.com但不匹配example.com空字符串匹配任意 hostname。目标地址Target的解析与去重Route 源生成 DNS 记录的目标地址按以下顺序确定若匹配的父 Gateway 带有external-dns.kubernetes.io/target注解则使用注解中的值否则遍历该 Gateway 的status.addresses把每个地址的value作为目标。多个匹配的父 Gateway 产生的 target 会被合并并去重对应 source/gateway.go 与uniqueTargets的实现。这条规则与 docs/sources/gateway.md 的描述一致。对于 ListenerSet 场景source/gateway.go 的newListenerSetObject实现了更细的优先级先读取 ListenerSet 自身的 target 注解若为空再回退到父 Gateway 的 target 注解。同时ListenerSet 是否被接受、父 Gateway 是否允许来自该命名空间的 ListenerSetAllowedListeners配置都会影响该对象是否被视为已挂载。双栈Dualstack行为Gateway 资源可能由一个同时支持 IPv4 和双栈IPv4 IPv6接口的外部负载均衡器提供。在使用 AWS Route53 Provider 时ExternalDNS 默认总会同时创建 A 和 AAAA 别名 DNS 记录无论负载均衡器是否为双栈。这是 Route53 场景下的默认行为无需额外配置。带 RBAC 的完整部署清单以下清单可作为在集群中部署 ExternalDNS 并启用全部五个 Gateway API Route 源的完整参考。它包含 ServiceAccount、ClusterRole、ClusterRoleBinding 与 Deployment所有 Gateway API 资源均授予get/watch/list权限apiVersion: v1 kind: ServiceAccount metadata: name: external-dns namespace: default --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: external-dns rules: - apiGroups: [] resources: [namespaces] verbs: [get,watch,list] - apiGroups: [gateway.networking.k8s.io] resources: [gateways,httproutes,grpcroutes,tlsroutes,tcproutes,udproutes,listenersets] verbs: [get,watch,list] --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: external-dns roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: external-dns subjects: - kind: ServiceAccount name: external-dns namespace: default --- apiVersion: apps/v1 kind: Deployment metadata: name: external-dns namespace: default spec: strategy: type: Recreate selector: matchLabels: app: external-dns template: metadata: labels: app: external-dns spec: serviceAccountName: external-dns containers: - name: external-dns image: registry.k8s.io/external-dns/external-dns:v0.23.0 args: # 添加所需的 Gateway API Route 源 - --sourcegateway-httproute - --sourcegateway-grpcroute - --sourcegateway-tlsroute - --sourcegateway-tcproute - --sourcegateway-udproute - --policyupsert-only # 防止 ExternalDNS 删除任何记录如需包含删除的完整同步设置 --policysync # 可选将 Route 限制在指定命名空间 - --namespacemy-route-namespace # 可选将 Route 限制为匹配给定标签选择器的那些 - --label-filtermy-route-labelmy-route-value # 可选将 Route 端点限制为指定名称的 Gateway - --gateway-namemy-gateway-name # 可选将 Route 端点限制为指定命名空间的 Gateway - --gateway-namespacemy-gateway-namespace # 可选将 Route 端点限制为匹配给定标签选择器的 Gateway - --gateway-label-filtermy-gateway-labelmy-gateway-value # 可选为引用 ListenerSet parentRef 的 Route 启用 ListenerSet 支持 - --gateway-listener-sets # 添加 Provider 专属标志... - --domain-filterexternal-dns-test.my-org.com - --providergoogle - --registrytxt - --txt-owner-idmy-identifier部署清单中的关键标志说明如下--sourcegateway-*一次可启用多个 Route 源ExternalDNS 会并行监听这些资源。五类源的定义可在 source/types/types.go 及各个gateway_*route.go文件如 source/gateway_httproute.go中确认。--namespace与--label-filter作用于 Route 资源本身来自通用 Source 配置在 source/gateway.go 中Route 的 label 与 annotation 过滤器会被传给 Route informer。--gateway-name、--gateway-namespace、--gateway-label-filter作用于 Route 的父 Gateway标志定义见 pkg/apis/externaldns/types.go。--gateway-listener-sets启用 ListenerSet 支持需要 Gateway API v1.5 CRD默认关闭对应 pkg/apis/externaldns/types.go 中的布尔标志。使用 Helm Chart 部署时可通过 charts/external-dns/values.yaml 中的enableGatewayListenerSets: false配置项开启同时 Chart 的 ClusterRole 模板 会在开启时追加listenersets资源权限。--policyupsert-only只增改不删除适合生产环境保守起步改为--policysync才会执行包含删除在内的完整同步。关键点速查版本Gateway/HTTPRoute 用 v1v1.0.0 起GRPCRoute 用 v1v1.1.0 起ListenerSet 用 v1v1.5.0 起需--gateway-listener-setsTLSRoute 用 v1alpha2已弃用TCPRoute/UDPRoute 用 v1alpha2仍实验性。HostnameTCP/UDPRoute 只能通过external-dns.kubernetes.io/hostname注解提供域名HTTP/TLSRoute 优先使用 spec.hostnames。注解放置target只放 Gateway或 ListenerSethostname、ttl、controller、provider 专属注解只放 Route。冲突规避使用external-dns.kubernetes.io/gateway-hostname-source: annotation-only或defined-hosts-only控制域名来源保护已有 CNAME 不被 A 记录覆盖。目标解析优先取 Gateway 的 target 注解否则取status.addresses多 Gateway 的 target 会合并去重。过滤--gateway-name、--gateway-namespace、--gateway-label-filter按父 Gateway 过滤--namespace、--label-filter按 Route 自身过滤。赞分享云原生【免费下载链接】external-dnsConfigure external DNS servers dynamically from Kubernetes resources项目地址https://gitcode.com/gh_mirrors/ex/external-dns点击查看免费下载相关推荐Minecraft区块管理终极指南如何用MCA Selector高效管理你的世界存档Minecraft区块管理终极指南如何用MCA Selector高效管理你的世界存档 MCA Selector是一款专门为Minecraft Java版设计的云原生MeshCentral多语言支持国际化部署与本地化配置完整指南MeshCentral多语言支持国际化部署与本地化配置完整指南 MeshCentral作为一个开源的远程监控和管理平台其强大的多语言支持功能让全球用户都能以后端运维ics库源码解析理解iCalendar文件生成的底层原理ics库源码解析理解iCalendar文件生成的底层原理 iCalendar简称ics文件是跨平台日历事件交换的标准格式而 ics 库作为Node.js后端序列化上一篇DeepChat docx 技能实战Office Open XMLOOXML文档编辑与修订追踪Redlining完整技术参考下一篇从零基础到AI达人workshop-library中的机器学习项目全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考