本文是从零学习envoy笔记第二章
  • 从零学习envoy笔记 - Gateway总览
  • 从零学习envoy笔记 - 学习EG API和Gateway API
  • 从零学习envoy笔记 - 快速部署实验环境
  • 从零学习envoy笔记 - 官方Task Backend Routing
  • 从零学习envoy笔记 - 官方Task Backend Utilization Load Balancing
  • 从零学习envoy笔记 - 官方Task Bandwidth Limit
  • 从零学习envoy笔记 - 官方Task Client Traffic Policy

本文通过几个示例来完成对 Gateway API 和 EG API 的印象加深学习

使用Envoy Gateway 中主要会接触两类 API：

  • Gateway API 在常规情况下接触的还是原生的比较高
  • EG API (Envoy Gateway API)：一些高级特性会使用到

Gateway API 是 Kubernetes SIG Network 定义的标准网关 API，例如 GatewayClass、Gateway、HTTPRoute 等。

Envoy Gateway API 是 Envoy Gateway 自己扩展出来的一组 CRD，用来补充 Gateway API 没有覆盖到的 Envoy 能力，例如外部后端、流量策略、安全策略、Envoy 参数等。

简单理解：

  • Gateway API：定义入口、监听器、路由、后端引用
  • EG API：补充 Envoy Gateway 的高级能力，比如 Backend、Policy、EnvoyProxy

Backend（EG API）

Backend API 是 Envoy Gateway 提供的扩展 API，用于定义非 Kubernetes Service 类型的后端。

一般情况下，HTTPRoute 的后端通常是 Kubernetes Service，不需要单独创建 Backend。

但是如果后端不是集群内的 Service，而是外部域名、外部 IP，或者 Unix Domain Socket，就可以使用 Envoy Gateway 的 Backend 资源来描述这些后端。

Backend API 支持的 backend endpoint 类型包括 [2]

FieldTypeRequiredDefaultDescription
apiVersionstringgateway.envoyproxy.io/v1alpha1
kindstringBackend
metadataObjectMetatrueRefer to Kubernetes API documentation for fields of metadata.
specBackendSpectrueSpec defines the desired state of Backend.
statusBackendStatustrueStatus defines the current status of Backend.

Backend 示例

这是将一个外部域名通过 envoy backend 来引入到集群

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
  name: external-httpbin
  namespace: default
spec:
  type: Endpoints
  endpoints:
    - fqdn:
        hostname: www.baidu.com
        port: 80

上面定义的这个 Backend 不能直接访问，这相当于定义 “外部 endpoints 后端”，如果需要访问还需要 HTTPRoute

HTTPRoute（Gateway API）

HTTPRoute 是 Gateway API 中用于描述 HTTP 流量路由规则的资源。

它负责定义：

  • 请求从哪个 Gateway 进入
  • 根据什么规则匹配请求
  • 请求转发到哪个后端
  • 是否需要路径改写、Header 修改、流量拆分等

他的请求流量图可以参考官网架构图

图：HTTPRoute请求流量图
Source：https://gateway-api.sigs.k8s.io/reference/api-types/httproute/

一个简单的 HTTPRoute 示例

下面这个示例表示：把经过 eg 这个 Gateway 的 HTTP 请求转发到 nginx Service 的 80 端口。

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: nginx-route
spec: 
  parentRefs: 
  - name: eg # 表示这个 HTTPRoute 挂在哪个Gateway 上。
  rules: 
  - backendRefs: 
    - name: nginx
      port: 80

这里的 nginx 默认是 Kubernetes Service，而不是 Envoy Gateway 的 Backend。

  • backendRefs Kind默认是 Service, 也可以是其他的，例如ExternalName, Backend等

结合 Backend 部分完成实验

定义一个用于访问的 HTTPRoute 资源

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: baidu-route
  namespace: default
spec:
  parentRefs:
    - name: eg
  hostnames:
    - baidu.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: www.baidu.com
      backendRefs:
        - group: gateway.envoyproxy.io
          kind: Backend
          name: external-httpbin
          port: 80

测试结果

text
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ curl -i -H "Host: baidu.example.com" http://127.0.0.1:8888
HTTP/1.1 200 OK
cache-control: private, no-cache, no-store, proxy-revalidate, no-transform
content-length: 2381
content-type: text/html
pragma: no-cache
server: bfe
set-cookie: BDORZ=27315; max-age=86400; domain=.baidu.com; path=/
date: Wed, 17 Jun 2026 14:16:23 GMT

<!DOCTYPE html>
<!--STATUS OK--><html> <head><meta http-equiv=content-type content=text/html;charset=utf-8><meta http-equiv=X-UA-Compatible content=IE=Edge><meta content=always name=referrer><link rel=stylesheet type=text/css href=http://s1.bdstatic.com/r/www/cache/bdorz/baidu.min.css><title>百度一下，你就知道</title></head> <body link=#0000cc> <div id=wrapper> <div id=head> <div class=head_wrapper> <div class=s_form> <div class=s_form_wrapper> <div id=lg> <img hidefocus=true src=//www.baidu.com/img/bd_logo1.png width=270 height=129> </div> <form id=form name=f action=//www.baidu.com/s class=fm> <input type=hidden name=bdorz_come value=1> <input type=hidden name=ie value=utf-8> <input type=hidden name=f value=8> <input type=hidden name=rsv_bp value=1> <input type=hidden name=rsv_idx value=1> <input type=hidden name=tn value=baidu><span class="bg s_ipt_wr"><input id=kw name=wd class=s_ipt value maxlength=255 autocomplete=off autofocus></span><span class="bg s_btn_wr"><input type=submit id=su value=百度一下 class="bg s_btn"></span> </form> </div> </div> <div id=u1> <a href=http://news.baidu.com name=tj_trnews class=mnav>新闻</a> <a href=http://www.hao123.com name=tj_trhao123 class=mnav>hao123</a> <a href=http://map.baidu.com name=tj_trmap class=mnav>地图</a> <a href=http://v.baidu.com name=tj_trvideo class=mnav>视频</a> <a href=http://tieba.baidu.com name=tj_trtieba class=mnav>贴吧</a> <noscript> <a href=http://www.baidu.com/bdorz/login.gif?login&amp;tpl=mn&amp;u=http%3A%2F%2Fwww.baidu.com%2f%3fbdorz_come%3d1 name=tj_login class=lb>登录</a> </noscript> <script>document.write('<a href="http://www.baidu.com/bdorz/login.gif?login&tpl=mn&u='+ encodeURIComponent(window.location.href+ (window.location.search === "" ? "?" : "&")+ "bdorz_come=1")+ '" name="tj_login" class="lb">登录</a>');</script> <a href=//www.baidu.com/more/ name=tj_briicon class=bri style="display: block;">更多产品</a> </div> </div> </div> <div id=ftCon> <div id=ftConw> <p id=lh> <a href=http://home.baidu.com>关于百度</a> <a href=http://ir.baidu.com>About Baidu</a> </p> <p id=cp>&copy;2017&nbsp;Baidu&nbsp;<a href=http://www.baidu.com/duty/>使用百度前必读</a>&nbsp; <a href=http://jianyi.baidu.com/ class=cp-feedback>意见反馈</a>&nbsp;京ICP证030173号&nbsp; <img src=//www.baidu.com/img/gs.gif> </p> </div> </div> </div> </body> </html>
note
这里重写了 Header 保证可以正常访问

BackendTrafficPolicy (EG API)

BackendTrafficPolicy 是 Envoy Gateway 提供的扩展 API，用于配置 Envoy Proxy 和后端服务之间的流量行为。也就是从网关到后端服务这一段的策略。常见用途包括：

  • 熔断
  • 限速
  • 健康检查
  • 重试
  • 后端超时
  • 负载均衡策略

官方示例：断路器和限速

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Direct reference targeting
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: direct-policy
spec:
  targetRefs:
    - kind: HTTPRoute
      name: my-route
  circuitBreaker:
    maxConnections: 50

---

# Label-based targeting
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: selector-policy
spec:
  targetSelectors:
    - kind: HTTPRoute
      matchLabels:
        app: payment-service
  rateLimit:
    local:
      requests: 10
      unit: Second
note
这里 (BackendTrafficPolicy)，可以使用任何Gateway 的API, Gateway, HTTPRoute, GRPCRoute, TCPRoute, UDPRoute, TLSRoute.

例如 Gateway, 表示这个 Gateway 下端默认浏览都走这个策略

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: backend-policy
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: eg
  loadBalancer:
    type: RoundRobin

例如 HTTPRouter, 表示只对这个 HTTPRoute 转发到 backend 的流量生效。

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: route-backend-policy
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: app-route
  loadBalancer:
    type: LeastRequest

上面说了 “targetRefs”，BackendTrafficPolicy 还可以可以通过 Lable 选择一批资源 (targetSelectors)

例如：HTTPRoute 上打 app: payment-service 标签，然后 BackendTrafficPolicy 用 targetSelectors 批量选中这些 HTTPRoute

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payment-route
  namespace: demo
  labels:
    app: payment-service
spec:
  parentRefs:
    - name: eg
  hostnames:
    - payment.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: payment-service
          port: 90
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
  name: payment-backend-policy
  namespace: demo
spec:
  targetSelectors:
    - kind: HTTPRoute
      matchLabels:
        app: payment-service

  loadBalancer:
    type: RoundRobin

  circuitBreaker:
    maxConnections: 100
    maxPendingRequests: 100
    maxParallelRequests: 100
    maxParallelRetries: 3

ClientTrafficPolicy (EG API)

ClientTrafficPolicy 是 Envoy Gateway 提供的扩展 API，用于配置客户端到 Envoy 之间的连接行为。也就是客户端进入网关这一段的策略。常见用途包括：

  • 客户端连接策略
  • TLS 配置
  • HTTP/3
  • 超时
  • 连接行为
  • 下游连接的行为.

官方示例

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Policy created first - takes precedence
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: alpha-policy
  creationTimestamp: "2023-01-01T10:00:00Z"
spec:
  targetRefs:
    - kind: Gateway
      name: my-gateway
      sectionName: https-listener
  timeout:
    http:
      idleTimeout: 30s

---
# Policy created later - lower precedence
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: beta-policy
  creationTimestamp: "2023-01-01T11:00:00Z"
spec:
  targetRefs:
    - kind: Gateway
      name: my-gateway
      sectionName: https-listener
  timeout:
    http:
      idleTimeout: 40s

SecurityPolicy (EG API)

SecurityPolicy 是 Envoy Gateway 提供的扩展 API，用于配置流量进入 Gateway 前后的认证和授权能力。常见用途包括：

  • CORS
  • JWT
  • OIDC
  • API Key
  • Basic Auth
  • External Authorization

它主要解决的是：

这个请求能不能进来？ 这个请求有没有权限？ 这个请求是否满足安全要求？

官方示例

yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Policy created first - takes precedence
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: alpha-policy
  creationTimestamp: "2023-01-01T10:00:00Z"
spec:
  targetRefs:
    - kind: HTTPRoute
      name: my-route
  cors:
    allowOrigins:
      - exact: https://example.com

---
# Policy created later - lower precedence
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: beta-policy
  creationTimestamp: "2023-01-01T11:00:00Z"
spec:
  targetRefs:
    - kind: HTTPRoute
      name: my-route
  cors:
    allowOrigins:
      - exact: https://different.com

SecurityPolicy 一般作用在 Gateway 或 Route 上，用来决定请求是否允许继续向后转发。

比如：

text
1

Client -> Gateway -> SecurityPolicy d -> HTTPRoute -> Backend

如果 SecurityPolicy 校验不通过，请求就不会继续进入后端服务。

这里需要注意的是：BackendTrafficPolicy 、ClientTrafficPolicy 、SecurityPolicy ，均是按照这些内容进行排序

  • Creation Time Priority：创建时间更早的 Policy 优先级更高
  • Name-based Sorting：如果创建时间相同，会按照名称排序决定优先级

ClientTrafficPolicy & BackendTrafficPolicy & SecurityPolicy 的位置理解

可以用下面这个图理解三种 Policy 的位置：

  • ClientTrafficPolicy 控制客户端到 Envoy Gateway Listener 之间的连接行为。
  • SecurityPolicy 控制请求进入 Gateway 或 Route 时的认证、鉴权、安全检查。
  • BackendTrafficPolicy 控制 Envoy Gateway 到后端 Service 之间的流量行为。
text
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

用户 / 客户端

  |
  | ① ClientTrafficPolicy：客户端 -> Envoy
  v

Envoy Gateway / Envoy Proxy

  |
  | ② SecurityPolicy：请求能不能进来、是否有权限
  v

后端 Service / Pod

  ^
  |
  | ③ BackendTrafficPolicy：Envoy -> 后端服务

Reference

[1] extension_types backend

[2] Gateway API Extensions