This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

欢迎访问 Envoy Gateway

Envoy Gateway 文档

Envoy Gateway 是一个开源项目,用于将 Envoy Proxy 作为独立或基于 Kubernetes 的应用程序网关进行管理。 Gateway API 资源用于动态供应和配置托管 Envoy 代理。

架构

准备好开始了吗?

1 - 开发者指南

本节告知开发者如何开发 Envoy Gateway。

Envoy Gateway 使用基于 make 的构建系统构建。我们的 CI 基于 Github Actions,使用 workflows

前置条件

go

  • 版本:1.22
  • 安装指南:https://go.dev/doc/install

make

  • 推荐版本:4.0 or later
  • 安装指南:https://www.gnu.org/software/make

docker

  • 如果您想构建一个 Docker 镜像或者在 Docker 内部运行 make
  • 推荐版本:20.10.16
  • 安装指南:https://docs.docker.com/engine/install

python3

  • 需要 python3 程序
  • 一个可正常执行的 venv module 是必要的;这是标准的一部分, 但某些发行版(例如 Debian 和 Ubuntu)使用 stub 来替代它,并要求您单独安装 python3-venv 包。

快速开始

  • 运行 make help 来查看所有可构建,可测试,可运行的的目标,并运行 Envoy Gateway。

构建

  • 运行 make build 来构建所有的二进制文件。
  • 运行 make build BINS="envoy-gateway" 来构建 Envoy Gateway 库。
  • 运行 make build BINS="egctl" 来构建 egctl 库。

注意: 上述二进制文件会在 bin/$OS/$ARCH 目录下生成,例如, bin/linux/amd64/

测试

  • 运行 make test 来运行 golang 测试。

  • 运行 make testdata 来生成 golden YAML 测试数据文件。

运行代码检查器(Linters)

  • 运行 make lint 来确保您的代码可以通过所有的代码检查工具检查。 注意:golangci-lint这里

构建和推送镜像

  • 运行 IMAGE=docker.io/you/gateway-dev make image 来构建 Docker 镜像。
  • 运行 IMAGE=docker.io/you/gateway-dev make push-multiarch 来构建和推送支持多架构的 Docker 镜像。

注意: 使用您注册的镜像名称来替代 IMAGE

为测试或开发部署 Envoy Gateway

  • 运行 make create-cluster 来创建一个 Kind 集群。

可选 1:使用最新的 gateway-dev 镜像

  • 运行 TAG=latest make kube-deploy 来使用最新的镜像在 Kind 集群中部署 Envoy Gateway。 替换 latest 来使用不同的镜像标签。

可选 2:使用定制的镜像

  • 运行 make kube-install-image 来从当前分支来构建一个镜像,然后将镜像载入 Kind 集群中。
  • 运行 IMAGE_PULL_POLICY=IfNotPresent make kube-deploy 来使用定制化镜像将 Envoy Gateway 安装到 Kind 集群中。

在 Kubernetes 中部署 Envoy Gateway

  • 运行 TAG=latest make kube-deploy 使用最新镜像将 Envoy Gateway 部署到 Kubernetes 集群中(当前 kube 上下文指向的集群)。 在命令前面加上 IMAGE 或替换 TAG 以使用不同的 Envoy Gateway 镜像或标签。
  • 运行 make kube-undeploy 在集群中卸载 Envoy Gateway。

注意: Envoy Gateway 针对 Kubernetes v1.24.0 进行了测试。

创建示例

  • 运行 make kube-demo 来部署一个示例后端服务, GatewayClass,Gateway 和 HTTPRoute 资源(类似于快速开始文档中概述的步骤)并且测试配置。
  • 运行 make kube-demo-undeploy 来删除由 make kube-demo 命令创建的资源。

运行 Gateway API 一致性测试

以下命令将 Envoy Gateway 部署到 Kubernetes 集群并运行 Gateway API 一致性测试。 请参阅 Gateway API 一致性主页了解有关测试的更多信息。如果 Envoy Gateway 已安装, 请运行 TAG=latest make run-conformance 运行一致性测试。

在 Linux 主机中

  • 运行 TAG=latest make conformance 来创建一个 Kind 集群, 使用最新的 gateway-dev 镜像安装 Envoy Gateway, 然后运行 Gateway API 一致性测试。

在 Mac 主机中

由于 Mac 不支持将 Docker 网络直接暴露到 Mac 主机,因此请使用以下方法之一来运行一致性测试:

  • Kubernetes 支持下部署 Kubernetes 集群或使用 Docker Desktop 然后运行 TAG=latest make kube-deploy run-conformance。 这将使用最新的 gateway-dev 镜像安装 Envoy Gateway 到当前 kubectl 上下文连接到的 Kubernetes 集群中,并运行一致性测试。 使用 make kube-undeploy 来卸载 Envoy Gateway。
  • 安装并执行 Docker Mac Net Connect 然后运行 TAG=latest make conformance

注意: 在命令前加上 IMAGE 或替换 TAG 以使用不同的 Envoy Gateway 镜像或标签。 如果未指定 TAG ,则会默认使用当前分支的短 SHA。

调试 Envoy 配置

查看 Envoy Gateway 正在使用的 Envoy 配置的一种简单方法是将 Envoy 的管理端口(当前为 19000)转发到一个本地端口上,这样就可以直接在本地进行访问。

获取 Envoy 部署的名称。下面是 Gateway egdefault 命名空间中的例子:

export ENVOY_DEPLOYMENT=$(kubectl get deploy -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')

对其管理端口进行端口转发:

kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000

现在您可以访问 127.0.0.1:19000/config_dump 来查看 Envoy 正在使用的配置。

Envoy 管理接口上还有许多其他端点,这些端点在调试时可能会有所帮助。

JWT 测试

示例 JSON Web Token(JWT)JSON Web Key Set(JWKS) 用于请求认证任务。 JWT 由 JWT 调试器使用 RS256 算法创建。来自 JWT 的公钥验证签名已复制到 JWK Creator 以生成 JWK。 JWK Creator 配置了匹配的设置,即 Signing 公钥使用和 RS256 算法。 生成的 JWK 包装在 JWKS 结构中并被托管在仓库中。

2 - 任务

通过任务学习 Envoy Gateway 实践。

2.1 - 快速入门

只需几个简单的步骤即可开始使用 Envoy Gateway。

本指南将帮助您通过几个简单的步骤开始使用 Envoy Gateway。

前置条件

一个 Kubernetes 集群。

注意: 请参考兼容性表格来查看所支持的 Kubernetes 版本。

注意: 如果您的 Kubernetes 集群没有负载均衡器实现,我们建议安装一个 ,以便 Gateway 资源能够关联一个地址。我们推荐使用 MetalLB

安装

安装 Gateway API CRD 和 Envoy Gateway:

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace

等待 Envoy Gateway 至可用后:

kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available

安装 GatewayClass,Gateway,HTTPRoute 和示例应用:

kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/quickstart.yaml -n default

注意:quickstart.yaml 定义了 Envoy Gateway 将侦听其全局可路由 IP 地址上端口 80 上的流量,以便轻松使用浏览器测试 Envoy Gateway。当 Envoy Gateway 看到它的侦听器使用特权端口(<1024), 它将在内部映射到非特权端口,因此 Envoy Gateway 不需要额外的特权。 了解此映射很重要,当您调试时您可能需要将其考虑在内。

测试配置

获取由示例 Gateway 创建的 Envoy 服务的名称:

export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}')

端口转发到 Envoy 服务:

kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8888:80 &

通过 Envoy 代理,使用 curl 测试示例应用:

curl --verbose --header "Host: www.example.com" http://localhost:8888/get

您还可以通过将流量发送到外部 IP 来测试相同的功能。运行下面的命令可以获取 Envoy 服务的外部 IP 地址:

export GATEWAY_HOST=$(kubectl get svc/${ENVOY_SERVICE} -n envoy-gateway-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

在某些环境中,负载均衡器可能会公开主机名而不是 IP 地址,如果是这样,将上述命令中的 ip 替换为 hostname

使用 curl 来通过 Envoy Proxy 访问示例应用:

curl --verbose --header "Host: www.example.com" http://$GATEWAY_HOST/get

接下来的探索?

在快速开始(本节),您将:

  • 完成 Envoy Gateway 的安装
  • 部署一个后端服务和一个网关
  • 使用 Kubernetes Gateway API 资源 GatewayHttpRoute 配置网关。将网关传入的 HTTP 请求转发到后端服务。

以下是建议的后续任务列表,可指导您探索 Envoy Gateway:

请查看与您使用情况相符的场景下的任务部分。Envoy Gateway 的任务按照流量管理、安全、扩展性、可观察性和运维等分类组织。

清理

请按照本节中的步骤将快速入门中的所有内容卸载。

删除 GatewayClass,Gateway,HTTPRoute 和示例应用:

kubectl delete -f https://github.com/envoyproxy/gateway/releases/download/latest/quickstart.yaml --ignore-not-found=true

删除 Gateway API CRD 和 Envoy Gateway:

helm uninstall eg -n envoy-gateway-system

接下来

浏览开发者指南 ,了解如何参与项目。

2.2 - GRPC 路由

GRPCRoute 资源允许用户通过匹配 HTTP/2 流量并将其转发到后端 gRPC 服务器来配置 gRPC 路由。 要了解有关 gRPC 路由的更多信息,请参阅Gateway API 文档

先决条件

按照快速入门中的步骤安装 Envoy Gateway 和示例清单。 在继续之前,您应该能够使用 HTTP 查询示例程序后端。

安装

安装 gRPC 路由示例资源:

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/grpc-routing.yaml

该清单安装 GatewayClassGateway、Deployment、Service 和 GRPCRoute 资源。 GatewayClass 是集群范围的资源,表示可以被实例化的一类 Gateway。

**注意:**Envoy Gateway 默认被配置为使用 controllerName: gateway.envoyproxy.io/gatewayclass-controller 管理 GatewayClass。

验证

检查 GatewayClass 的状态:

kubectl get gc --selector=example=grpc-routing

状态应反映为 Accepted=True,表示 Envoy Gateway 正在管理 GatewayClass。

Gateway 代表基础设施的配置。创建 Gateway 时,Envoy 代理基础设施由 Envoy Gateway 预配或配置。 gatewayClassName 定义此 Gateway 使用的 GatewayClass 的名称。检查 Gateway 状态:

kubectl get gateways --selector=example=grpc-routing

状态应反映为 Ready=True,表示 Envoy 代理基础设施已被配置。 该状态还提供 Gateway 的地址。该地址稍后用于测试与代理后端服务的连接。

检查 GRPCRoute 的状态:

kubectl get grpcroutes --selector=example=grpc-routing -o yaml

GRPCRoute 的状态应显示 Accepted=True 和引用示例 Gateway 的 parentRefexample-route 匹配 grpc-example.com 的任何流量并将其转发到 yages 服务。

测试配置

在测试到 yages 后端的 GRPC 路由之前,请获取 Gateway 的地址。

export GATEWAY_HOST=$(kubectl get gateway/example-gateway -o jsonpath='{.status.addresses[0].value}')

使用 grpcurl 命令测试到 yages 后端的 GRPC 路由。

grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping

您应该看到以下响应:

{
  "text": "pong"
}

Envoy Gateway 还支持此配置的 gRPC-Web 请求。下面的 curl 命令可用于通过 HTTP/2 发送 grpc-Web 请求。 您应该收到与上一个命令相同的响应。

正文 AAAAAAA= 中的数据是 Ping RPC 接受的空消息(数据长度为 0)的 Base64 编码表示。

curl --http2-prior-knowledge -s ${GATEWAY_HOST}:80/yages.Echo/Ping -H 'Host: grpc-example.com'   -H 'Content-Type: application/grpc-web-text'   -H 'Accept: application/grpc-web-text' -XPOST -d'AAAAAAA=' | base64 -d

GRPCRoute 匹配

matches 字段可用于根据 GRPC 的服务和/或方法名称将路由限制到一组特定的请求。 它支持两种匹配类型:Exact(精准)和 RegularExpression(正则)。

精准

Exact(精准)匹配是默认匹配类型。

以下示例显示如何根据 grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo 的服务和方法名称来匹配请求, 以及如何在我们的部署中匹配方法名称为 Ping 且与 yages.Echo/Ping 匹配的所有服务。

cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: yages
  labels:
    example: grpc-routing
spec:
  parentRefs:
    - name: example-gateway
  hostnames:
    - "grpc-example.com"
  rules:
    - matches:
      - method:
          method: ServerReflectionInfo
          service: grpc.reflection.v1alpha.ServerReflection
      - method:
          method: Ping
      backendRefs:
        - group: ""
          kind: Service
          name: yages
          port: 9000
          weight: 1
EOF

保存以下资源并将其应用到您的集群:

---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: yages
  labels:
    example: grpc-routing
spec:
  parentRefs:
    - name: example-gateway
  hostnames:
    - "grpc-example.com"
  rules:
    - matches:
      - method:
          method: ServerReflectionInfo
          service: grpc.reflection.v1alpha.ServerReflection
      - method:
          method: Ping
      backendRefs:
        - group: ""
          kind: Service
          name: yages
          port: 9000
          weight: 1

验证 GRPCRoute 状态:

kubectl get grpcroutes --selector=example=grpc-routing -o yaml

使用 grpcurl 命令测试到 yages 后端的 GRPC 路由。

grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping

正则

以下示例演示如何根据服务和方法名称将请求与匹配类型 RegularExpression 进行匹配。 它与模式 /.*.Echo/Pin.+ 匹配所有服务和方法,该模式与我们部署中的 yages.Echo/Ping 匹配。

cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: yages
  labels:
    example: grpc-routing
spec:
  parentRefs:
    - name: example-gateway
  hostnames:
    - "grpc-example.com"
  rules:
    - matches:
      - method:
          method: ServerReflectionInfo
          service: grpc.reflection.v1alpha.ServerReflection
      - method:
          method: "Pin.+"
          service: ".*.Echo"
          type: RegularExpression
      backendRefs:
        - group: ""
          kind: Service
          name: yages
          port: 9000
          weight: 1
EOF

保存以下资源并将其应用到您的集群:

---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: yages
  labels:
    example: grpc-routing
spec:
  parentRefs:
    - name: example-gateway
  hostnames:
    - "grpc-example.com"
  rules:
    - matches:
      - method:
          method: ServerReflectionInfo
          service: grpc.reflection.v1alpha.ServerReflection
      - method:
          method: "Pin.+"
          service: ".*.Echo"
          type: RegularExpression
      backendRefs:
        - group: ""
          kind: Service
          name: yages
          port: 9000
          weight: 1

检查 GRPCRoute 状态:

kubectl get grpcroutes --selector=example=grpc-routing -o yaml

使用 grpcurl 命令测试到 yages 后端的 GRPC 路由。

grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping

2.3 - JWT 身份验证

此任务提供有关配置 JSON Web Token(JWT)身份验证的说明。 JWT 身份验证在将请求路由到后端服务之前检查传入请求是否具有有效的 JWT。 目前,Envoy Gateway 仅支持通过 HTTP 标头验证 JWT,例如 Authorization: Bearer <token>

Envoy Gateway 引入了一个名为 SecurityPolicy 的新 CRD,允许用户配置 JWT 身份验证。 该实例化资源可以链接到 GatewayHTTPRouteGRPCRoute 资源。

先决条件

按照快速入门中的步骤安装 Envoy Gateway 和示例清单。 对于 GRPC - 请按照 GRPC 路由示例中的步骤操作。 在继续之前,您应该能够使用 HTTP 或 GRPC 查询示例程序后端。

配置

通过创建 SecurityPolicy 并将其附加到示例 HTTPRoute 或 GRPCRoute,允许使用具有有效 JWT 的请求。

HTTPRoute

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/jwt/jwt.yaml

已创建两个 HTTPRoute,一个用于 /foo,另一个用于 /bar。 已创建 SecurityPolicy 并以 HTTPRoute foo 为目标来验证对 /foo 的请求。 HTTPRoute bar 不是 SecurityPolicy 的目标,并且将允许未经身份验证的请求发送到 /bar

验证 HTTPRoute 配置和状态:

kubectl get httproute/foo -o yaml
kubectl get httproute/bar -o yaml

SecurityPolicy 配置为 JWT 身份验证,并使用单个 JSON Web Key Set(JWKS)提供程序来对 JWT 进行身份验证。

验证 SecurityPolicy 配置:

kubectl get securitypolicy/jwt-example -o yaml

GRPCRoute

kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/jwt/grpc-jwt.yaml

已创建 SecurityPolicy 并针对 GRPCRoute yages 来验证 yages 服务的所有请求。

验证 GRPCRoute 配置和状态:

kubectl get grpcroute/yages -o yaml

SecurityPolicy 配置为 JWT 身份验证,并使用单个 JSON Web Key Set(JWKS)提供程序来对 JWT 进行身份验证。

验证 SecurityPolicy 配置:

kubectl get securitypolicy/jwt-example -o yaml

测试

确保设置了快速入门 中的 GATEWAY_HOST 环境变量。如果没有,请按照快速入门说明设置变量。

echo $GATEWAY_HOST

HTTPRoute

验证在没有 JWT 的情况下对 /foo 的请求是否被拒绝:

curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/foo

应返回一个 401 HTTP 响应码。

获取用于测试请求身份验证的 JWT:

TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode -

**注意:**上述命令解码并返回令牌的有效内容。您可以将 f2 替换为 f1 来查看令牌的标头。

验证是否允许使用有效 JWT 向 /foo 发出请求:

curl -sS -o /dev/null -H "Host: www.example.com" -H "Authorization: Bearer $TOKEN" -w "%{http_code}\n" http://$GATEWAY_HOST/foo

应返回一个 200 HTTP 响应码。

验证是否允许在没有 JWT 的情况下向 /bar 发出请求:

curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/bar

GRPCRoute

验证是否在没有 JWT 的情况下拒绝对 yages 服务的请求:

grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping

您应该看到以下响应:

Error invoking method "yages.Echo/Ping": rpc error: code = Unauthenticated desc = failed to query for service descriptor "yages.Echo": Jwt is missing

获取用于测试请求身份验证的 JWT:

TOKEN=$(curl https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/test.jwt -s) && echo "$TOKEN" | cut -d '.' -f2 - | base64 --decode -

**注意:**上述命令解码并返回令牌的有效内容。您可以将 f2 替换为 f1 来查看令牌的标头。

验证是否允许使用有效 JWT 向 yages 服务发出请求:

grpcurl -plaintext -H "authorization: Bearer $TOKEN" -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping

您应该看到以下响应:

{
  "text": "pong"
}

清理

按照快速入门 中的步骤卸载 Envoy Gateway 和示例清单。

删除 SecurityPolicy:

kubectl delete securitypolicy/jwt-example

后续步骤

查看开发者指南参与该项目。

3 - 安装

本节包含关于安装 Envoy Gateway 的内容。

3.1 - 使用 Helm 安装

Helm 是 Kubernetes 的包管理器,可自动在 Kubernetes 上发布和管理软件。

Envoy Gateway 可以通过 Helm Chart 经过几个简单的步骤进行安装, 具体取决于您是首次部署、从现有安装升级 Envoy Gateway 还是从 Envoy Gateway 迁移。

开始之前

Envoy Gateway Helm Chart 托管在 DockerHub 中。

它发布在 oci://docker.io/envoyproxy/gateway-helm

使用 Helm 安装

Envoy Gateway 通常从命令行部署到 Kubernetes。如果您没有 Kubernetes,则应该使用 kind 来创建一个。

安装 Gateway API CRD 和 Envoy Gateway:

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace

等待 Envoy Gateway 变为可用:

kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available

安装 GatewayClass、Gateway、HTTPRoute 和示例应用程序:

kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/quickstart.yaml -n default

注意quickstart.yaml 定义 Envoy Gateway 将侦听 80 端口及其全局可路由 IP 地址的流量, 以便轻松使用浏览器测试 Envoy Gateway。当 Envoy Gateway 发现其侦听器正在使用特权端口(<1024)时, 它会在内部将其映射到非特权端口,以便 Envoy Gateway 不需要额外的特权。了解此映射很重要,因为您在调试时可能需要考虑它。

自定义 Helm Chart

下面是使用 helm install 命令进行 Envoy Gateway 安装的一些快速方法。

增加副本数

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace --set deployment.replicas=2

更改 kubernetesClusterDomain 名称

如果您使用不同的域名安装了集群,则可以使用以下命令。

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace --set kubernetesClusterDomain=<domain name>

注意:以上是我们可以直接用于自定义安装的一些方法。但如果您正在寻找更复杂的更改, values.yaml 可以帮助您。

使用 values.yaml 文件进行复杂安装

deployment:
  envoyGateway:
    resources:
      limits:
        cpu: 700m
        memory: 128Mi
      requests:
        cpu: 10m
        memory: 64Mi
  ports:
    - name: grpc
      port: 18005
      targetPort: 18000
    - name: ratelimit
      port: 18006
      targetPort: 18001

config:
  envoyGateway:
    logging:
      level:
        default: debug

在这里,我们对 value.yaml 文件进行了三处更改。将 CPU 的资源限制增加到 700m, 将 gRPC 的端口更改为 18005,将限流端口更改为 18006,并将日志记录级别更新为 debug

您可以通过以下命令使用 value.yaml 文件安装 Envoy Gateway。

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace -f values.yaml

开放端口

这些是 Envoy Gateway 和托管 Envoy 代理使用的端口。

Envoy Gateway

Envoy Gateway地址端口是否可配置
Xds EnvoyProxy Server0.0.0.018000No
Xds RateLimit Server0.0.0.018001No
Admin Server127.0.0.119000Yes
Metrics Server0.0.0.019001No
Health Check127.0.0.18081No

EnvoyProxy

Envoy Proxy地址端口
Admin Server127.0.0.119000
Heath Check0.0.0.019001

3.2 - 使用 Kubernetes YAML 安装

此任务将引导您完成在 Kubernetes 集群中安装 Envoy Gateway。

手动安装过程不允许像 Helm 安装方法那样对配置进行更多控制, 因此如果您需要对 Envoy Gateway 安装进行更多控制,建议您使用 Helm。

开始之前

Envoy Gateway 设计为在 Kubernetes 中运行以进行生产。最重要的要求是:

  • Kubernetest 1.25+ 版本
  • kubectl 命令行工具

使用 YAML 安装

Envoy Gateway 通常从命令行部署到 Kubernetes。如果您没有 Kubernetes,则应该使用 kind 来创建一个。

  1. 在终端中,运行以下命令:

    kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/install.yaml
    
  2. 后续步骤

    Envoy Gateway 现在应该已成功安装并运行,但是为了体验 Envoy Gateway 的更多功能,您可以参考任务

3.3 - 使用自定义证书的控制平面身份验证

Envoy Gateway 为 Envoy Gateway Pod 和 Envoy 代理队列之间的控制平面通信建立了安全的 TLS 连接。 此处使用的 TLS 证书是自签名的,并使用在创建 Envoy Gateway 之前运行的 Job 生成, 并且这些证书被安装到 Envoy Gateway 和 Envoy 代理 Pod 上。

此任务将引导您完成为控制平面身份验证配置自定义证书。

开始之前

我们使用 Cert-Manager 来管理证书。 您可以按照官方指南安装它。

为控制平面配置自定义证书

  1. 首先您需要设置 CA 颁发者,在此任务中,我们以 selfsigned-issuer 为例。

    您不应在生产中使用自签名颁发者,您应该使用真实的 CA 颁发者。

    cat <<EOF | kubectl apply -f -
    apiVersion: cert-manager.io/v1
    kind: Issuer
    metadata:
      labels:
        app.kubernetes.io/name: envoy-gateway
      name: selfsigned-issuer
      namespace: envoy-gateway-system
    spec:
      selfSigned: {}
    ---
    apiVersion: cert-manager.io/v1
    kind: Certificate
    metadata:
      name: envoy-gateway-ca
      namespace: envoy-gateway-system
    spec:
      isCA: true
      commonName: envoy-gateway
      secretName: envoy-gateway-ca
      privateKey:
        algorithm: RSA
        size: 2048
      issuerRef:
        name: selfsigned-issuer
        kind: Issuer
        group: cert-manager.io
    ---
    apiVersion: cert-manager.io/v1
    kind: Issuer
    metadata:
      labels:
        app.kubernetes.io/name: envoy-gateway
      name: eg-issuer
      namespace: envoy-gateway-system
    spec:
      ca:
        secretName: envoy-gateway-ca
    EOF
    
  2. 为 Envoy Gateway 控制器创建一个证书,该证书将存储在 envoy-gatewy Secret 中。

    cat<<EOF | kubectl apply -f -
    apiVersion: cert-manager.io/v1
    kind: Certificate
    metadata:
      labels:
        app.kubernetes.io/name: envoy-gateway
      name: envoy-gateway
      namespace: envoy-gateway-system
    spec:
      commonName: envoy-gateway
      dnsNames:
      - "envoy-gateway"
      - "envoy-gateway.envoy-gateway-system"
      - "envoy-gateway.envoy-gateway-system.svc"
      - "envoy-gateway.envoy-gateway-system.svc.cluster.local"
      issuerRef:
        kind: Issuer
        name: eg-issuer
      usages:
      - "digital signature"
      - "data encipherment"
      - "key encipherment"
      - "content commitment"
      secretName: envoy-gateway
    EOF
    
  3. 为 Envoy 代理创建一个证书,该证书将存储在 envoy Secret 中。

    cat<<EOF | kubectl apply -f -
    apiVersion: cert-manager.io/v1
    kind: Certificate
    metadata:
      labels:
        app.kubernetes.io/name: envoy-gateway
      name: envoy
      namespace: envoy-gateway-system
    spec:
      commonName: "*"
      dnsNames:
      - "*.envoy-gateway-system"
      issuerRef:
        kind: Issuer
        name: eg-issuer
      usages:
      - "digital signature"
      - "data encipherment"
      - "key encipherment"
      - "content commitment"
      secretName: envoy
    EOF
    
  4. 创建限流证书,该证书将存储在 envoy-rate-limit Secret 中。

    cat<<EOF | kubectl apply -f -
    apiVersion: cert-manager.io/v1
    kind: Certificate
    metadata:
      labels:
        app.kubernetes.io/name: envoy-gateway
      name: envoy-rate-limit
      namespace: envoy-gateway-system
    spec:
      commonName: "*"
      dnsNames:
      - "*.envoy-gateway-system"
      issuerRef:
        kind: Issuer
        name: eg-issuer
      usages:
      - "digital signature"
      - "data encipherment"
      - "key encipherment"
      - "content commitment"
      secretName: envoy-rate-limit
    EOF
    
  5. 现在您可以按照 helm Chart 安装指南使用自定义证书安装 Envoy Gateway。

3.4 - gateway-helm

Version: v0.0.0-latest Type: application AppVersion: latest

The Helm chart for Envoy Gateway

Homepage: https://gateway.envoyproxy.io/

Maintainers

NameEmailUrl
envoy-gateway-steering-committeehttps://github.com/envoyproxy/gateway/blob/main/GOVERNANCE.md
envoy-gateway-maintainershttps://github.com/envoyproxy/gateway/blob/main/CODEOWNERS

Source Code

Values

KeyTypeDefaultDescription
certgen.job.annotationsobject{}
certgen.job.resourcesobject{}
certgen.job.ttlSecondsAfterFinishedint30
certgen.rbac.annotationsobject{}
certgen.rbac.labelsobject{}
config.envoyGateway.gateway.controllerNamestring"gateway.envoyproxy.io/gatewayclass-controller"
config.envoyGateway.logging.level.defaultstring"info"
config.envoyGateway.provider.typestring"Kubernetes"
createNamespaceboolfalse
deployment.envoyGateway.image.repositorystring"docker.io/envoyproxy/gateway"
deployment.envoyGateway.image.tagstring"latest"
deployment.envoyGateway.imagePullPolicystring"IfNotPresent"
deployment.envoyGateway.imagePullSecretslist[]
deployment.envoyGateway.resources.limits.cpustring"500m"
deployment.envoyGateway.resources.limits.memorystring"1024Mi"
deployment.envoyGateway.resources.requests.cpustring"100m"
deployment.envoyGateway.resources.requests.memorystring"256Mi"
deployment.pod.affinityobject{}
deployment.pod.annotations.“prometheus.io/port”string"19001"
deployment.pod.annotations.“prometheus.io/scrape”string"true"
deployment.pod.labelsobject{}
deployment.ports[0].namestring"grpc"
deployment.ports[0].portint18000
deployment.ports[0].targetPortint18000
deployment.ports[1].namestring"ratelimit"
deployment.ports[1].portint18001
deployment.ports[1].targetPortint18001
deployment.ports[2].namestring"metrics"
deployment.ports[2].portint19001
deployment.ports[2].targetPortint19001
deployment.replicasint1
kubernetesClusterDomainstring"cluster.local"

3.5 - 兼容性表格

本节包含关于 Envoy Gateway 的兼容性表格。

Envoy Gateway 依赖于 Envoy Proxy 和 Gateway API,并在 Kubernetes 集群中运行。 这些产品的所有版本并非都可以与 Envoy Gateway 一起运行。下面列出了支持的版本组合; 粗体类型表示实际编译到每个 Envoy Gateway 版本中的 Envoy Proxy 和 Gateway API 的版本。

Envoy Gateway 版本Envoy Proxy 版本Rate Limit 版本Gateway API 版本Kubernetes 版本
v1.0.0distroless-v1.29.219f2079fv1.0.0v1.26, v1.27, v1.28, v1.29
v0.6.0distroless-v1.28-latestb9796237v1.0.0v1.26, v1.27, v1.28
v0.5.0v1.27-lateste059638dv0.7.1v1.25, v1.26, v1.27
v0.4.0v1.26-latest542a6047v0.6.2v1.25, v1.26, v1.27
v0.3.0v1.25-latestf28024e3v0.6.1v1.24, v1.25, v1.26
v0.2.0v1.23-latestv0.5.1v1.24
latestdev-latestmasterv1.0.0v1.26, v1.27, v1.28, v1.29

4 - 版本

本节内容包含 Envoy Gateway 的版本。

4.1 - v1.0.1

日期:2024 年 4 月 9 日

安装

  • 将 EnvoyProxy 版本更新至 v1.29.3
  • 修复了 Certgen 以支持在升级期间创建 hmac 密钥

转换器

  • 修复了 ResourceVersionTable 中的 nil Secret 问题
  • 当启用 ClientTrafficPolicy 和 MergeGateway 时,将缺少的 HTTP 过滤器添加到 HTTP 过滤器链
  • 启用 URL 重写时允许 WebSocket
  • 设置 HTTP 健康检查器的 Host 标头
  • 修复了重定向 URL 中的双斜杠
  • 允许 ClientTrafficPolicy 附加到同一网关内的多个 HTTP(非 HTTPS)侦听器
  • 为 HTTP Ext Auth 服务的路径设置前缀
  • 设置路由匹配优先顺序为 Exact > RegularExpression > PathPrefix
  • 修复了被合并网关的 infraIR 重复端口转换
  • 将 SpawnUpstreamSpan 设置为 true
  • 允许限流与多个监听器一起使用

Infra-manager

  • 当 InfraIR 具有空侦听器时跳过创建基础设施资源

4.2 - v1.0.0

日期:2024 年 3 月 13 日

文档

  • 新增了本地限流(Local Ratelimit)的用户指南
  • 新增了熔断(Circuit Breaker)的用户指南
  • 新增了故障注入(Fault Injection)的用户指南
  • 新增了 EnvoyProxy extraArgs 的用户指南
  • 新增了在 ClientTrafficPolicy 中超时的用户指南
  • 新增了基础路由的 JWT Claim 用户指南
  • 新增了 HTTP 超时的用户指南
  • 新增了在 BackendTrafficPolicy 中重试的用户指南
  • 新增了基础身份验证(Basic Auth)的用户指南
  • 新增了 OIDC 的用户指南
  • 新增了 ClientTrafficPolicy 的用户指南
  • 新增了 BackendTrafficPolicy 的用户指南
  • 新增了使用 HTTPS 的基础身份验证(Basic Auth)的用户指南
  • 新增外部鉴权(External Authorization)的用户指南
  • 新增了 Kubernetes 外部路由的用户指南
  • 新增了 BackendTLSPolicy 的用户指南
  • 新增了从外部客户端到网关的双向 TLS 的用户指南
  • 新增了使用自定义证书进行控制平面身份验证的用户指南
  • 新增了多 GatewayClass 和合并 Gateway 部署模式的用户指南
  • 为 CRD API 添加了 Typerequired 的文档
  • 重构了用户指南文档的结构
  • 将设计文档移动到“参与”下并重构
  • 将 crd-ref-docs 更新至 0.0.10
  • 将 Envoy Proxy 镜像更新为 main 中的 envoy:distroless-dev

安装

  • 新增了对从私有仓库中提取 envoyGateway 镜像的支持
  • 新增了为 certgen Job 配置资源的支持
  • 新增了为 EnvoyGateway Pod 配置亲和力的支持

API

  • 在 ClientTrafficPolicy CRD 中添加了对下游 QUIC/HTTP3 的支持
  • 在 ClientTrafficPolicy CRD 中添加了对下游 MTLS 的支持
  • 在 ClientTrafficPolicy CRD 中添加了对 EnvoyHeaders 的启用支持
  • 在 ClientTrafficPolicy CRD 中添加了对 DisableMergeSlash 和 escapedSlashesAction 的支持
  • 在 ClientTrafficPolicy CRD 中添加了对 HTTP/1.1 中的 EnableTrailers 的支持
  • 在 ClientTrafficPolicy CRD 中添加了对 HTTP/1 上保留标头字母大小写的支持
  • 在 ClientTrafficPolicy CRD 中添加了对 HTTP/1.0 和 HTTP/0.9 启用的支持
  • 在 ClientTrafficPolicy CRD 中添加了对使用 XFF 进行客户端 IP 检测的支持
  • 在 ClientTrafficPolicy CRD 中添加了对使用自定义标头进行客户端 IP 检测的支持
  • 在 ClientTrafficPolicy CRD 中添加了对连接超时的支持
  • 在 ClientTrafficPolicy CRD 中添加了对常见 TLS 配置属性的支持
  • 在 ClientTrafficPolicy CRD 中添加了对代理协议的支持
  • 在 ClientTrafficPolicy CRD 中添加了对 TCPKeepAlive 的支持
  • 在 BackendTrafficPolicy CRD 中添加了对本地限流(Local Ratelimit)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对熔断(Circuit Breaker)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对故障注入(Fault Injection)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对被动健康检查(Passive Health Check)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对主动健康检查(Active Health Check)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对连接超时(Connection Timeout)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对压缩器/解压缩器(Compressor/Decompressor)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对重试(Retry)的支持
  • 在 BackendTrafficPolicy CRD 中添加了对慢启动模式的支持
  • 在 BackendTrafficPolicy CRD 中添加了对代理协议的支持
  • 在 BackendTrafficPolicy CRD 中添加了对 TCPKeepAlive 的支持
  • 在 BackendTrafficPolicy CRD 中添加了对 PolicyStatus 的支持
  • 在 ClientTrafficPolicy CRD 中添加了对 PolicyStatus 的支持
  • 在 SecurityPolicy CRD 中添加了对 PolicyStatus 的支持
  • 在 SecurityPolicy CRD 中添加了对 OIDC 的支持
  • 在 SecurityPolicy CRD 中添加了对基础身份验证(Basic Auth)的支持
  • 在 SecurityPolicy CRD 中添加了对 OIDC 的 RedirectURL 和 signoutPath 的支持
  • 在 SecurityPolicy CRD 中添加了对 ExtractFrom 标头和参数到 JWT 的支持
  • 在 SecurityPolicy CRD 中添加了对外部鉴权(External Authorization)的支持
  • 在 SecurityPolicy CRD 中添加了对 JWT 的 RecomputeRoute 字段的支持
  • 在 SecurityPolicy CRD 中添加了对 CORS 设置的 AllowCredentials 旋钮的支持
  • 在 SecurityPolicy CRD 中添加了对从不同标识符提取到 JWT 的支持
  • 在 EnvoyPatchPolicy CRD 中添加了对 Secret 资源的支持
  • 在 EnvoyPatchPolicy CRD 中添加了对 JSONPatchOperation 的值可选的支持
  • 在 EnvoyPatchPolicy CRD 中添加了对 JSONPatchOperation 中 From 字段的支持
  • 在 EnvoyPatchPolicy CRD 中添加了对 MergeGateways 的支持
  • 通过实施 BackendTLSPolicy CRD 添加了对上游 TLS 的支持
  • 在 EnvoyGateway 配置中添加了对 NamespaceSelectors 的 LabelSelector 类型的支持
  • 在 EnvoyGateway 配置中添加了对 Ratelimit Prometheus 的支持
  • 在 EnvoyProxy CRD 中添加了对 Pod 终止时 Envoy 关闭之前优雅地耗尽侦听器的支持
  • 在 EnvoyProxy CRD 中添加了对 Envoy 服务配置 externalTrafficPolicy 的支持
  • 在 EnvoyProxy CRD 中添加了对 Envoy 额外参数的支持
  • 在 EnvoyProxy CRD 中添加了对 Mergepatch 到 envoyproxy/ratelimit 部署的支持
  • 在 EnvoyProxy CRD 中添加了对 Mergepatch 到 envoyproxy 服务的支持
  • 在 EnvoyProxy CRD 中添加了对 NodeSelector 到 PodSpec 的支持
  • 在 EnvoyProxy CRD 中添加了对 HorizontalPodAutoscaler 的支持
  • 在 EnvoyProxy CRD 中添加了对 PodSpec 的 TopologySpreadConstraints 支持
  • 在 EnvoyProxy CRD 中添加了对 PodSpec 的 ImagePullSecrets 的支持

重大变化

  • 使用通配符将 AllowOrigins 与 SecurityPolicy CRD 中的 CORS 进行匹配
  • 删除 EnvoyProxy CRD 中的主机网络支持

一致性

  • 将后端镜像从 gcr.io/k8s-staging-ingressconformance/echoserver 替换为 gcr.io/k8s-staging-gateway-api/echo-basic

测试

  • 添加了标头中大小写保留的 e2e 测试
  • 添加了在 ClientTrafficPolicy 中超时的 e2e 测试
  • 添加了 JWT Claim 基础路由的 e2e 测试
  • 添加了 OIDC 的 e2e 测试
  • 添加了 BackendTrafficPolicy 重试(Retry)的 e2e 测试
  • 添加了后端升级的 e2e 测试
  • 添加了外部鉴权(External Authorization)的 e2e 测试
  • 添加了后端 TLS 策略的 e2e 测试
  • 添加了 Envoy Gateway 版本升级的 e2e 测试
  • 添加了加权后端的 e2e 测试
  • 添加了对 LoadBalancerIP 的验证以防止拖尾周期

转换器

  • 修复了前缀匹配,以防止具有相同前缀的路由匹配错误的问题
  • 通过为 ir.Infra 实现类似接口来修复多重调谐的问题
  • 修复了具有空条件 {} 的 EndpointSlice 问题
  • 修复了解析 http 请求超时时的错误处理
  • 修复了 EnvoyPatchPolicy 被禁用时无状态的问题
  • 修复了 xDS 和 infra IR 的可打印问题
  • 修复了跳过 backendRef 并将权重设置为 0 的问题
  • 修复了限流中的 AND 标头匹配不起作用的问题
  • 修复了不存在 GatewayClass 时的删除逻辑
  • 修复了 ClientTrafficPolicy 的 mergedGateway irKey 匹配问题
  • 修复了策略应仅被应用到 mergeGateway 为 true 的 Gateway 的问题
  • 修复了启用 mergeGateway 时不会显示网关侦听器状态的问题
  • 通过将 Web 套接字升级配置从 hcm 移动到路由,修复了 GRPCroute websocket 无法工作的问题
  • 修复了在 HTTPRoute 上设置超时时配置空闲超时的问题
  • 修复了 OIDC 令牌端点的放宽 HTTPS 限制
  • 修复了将路由转换到空的后端时出现的 Panic 问题
  • 修复了 xDS 转换应以最高效的方式完成
  • 修复了从监测中删除未被使用的状态键的问题
  • 修复了比较 Envoy Proxy 服务时忽略终结器的问题
  • 修复了如果 HTTP/3 被启用后不会覆盖 ALPN 数组的问题
  • 修复了启用 HTTP/3 时默认添加 h3 ALPN 的问题
  • 修复了 SecurityPolicy/BackendTrafficPolicy 的 Merge 行为,改为 Replace
  • 修复了启用 HTTP/3 时在 alt-svc 标头中使用服务端口的问题
  • 修复了防止针对同一端口上的非 TLS 侦听器的策略发生冲突
  • 修复了跳过所有策略的 ReasonTargetNotFound
  • 修复了跳过所有策略的空发布状态
  • 添加了在发送到 Envoy 之前正则表达式验证支持
  • 添加了当服务类型为 ClusterIP 时将 spec.addresses.value 设置为 ClusterIP 的支持
  • 为 BackendRef 中的过滤器添加了不支持的状态条件
  • 为 Provider 资源添加了 List 替代 Map,以保证稳定性
  • 添加了 OAuth Cookie 的后缀,以防止多个 OAuth 过滤器覆盖彼此的 Cookie
  • 添加了对 BackendTrafficPolicy 和 SecurityPolicy 覆盖条件的支持
  • 添加了对默认重试预计量和重试主机判断的支持
  • 添加了对 gateway.spec.infrastructural 实现的支持
  • 添加了对多个后端的上游 TLS 的支持
  • 添加了在 ClientTrafficPolicy 中对 CA 证书验证的支持

Provider

  • 添加了对每个控制器多个 GatewayClass 的支持
  • 在 Kubernetes Provider 中添加了 SecurityPolicyIndexers
  • 添加了对在 CertGen Job 中生成 HMAC 密钥的支持
  • 修复了删除 GatewayClass 时的 Finalizer 逻辑
  • 修复了重新启动控制平面时 MergeGateway 出现 Panic 的问题

xDS

  • 添加了对 EDS 缓存的支持
  • 添加了对 ADS 缓存的支持,以保证规则顺序
  • 修复了使用 RequestHeaderModifier 过滤器时出现的已弃用字段错误
  • 修复了 Envoy 在运行时拒绝 XDS 并在重新启动时丢失所有路由的问题
  • 修复了与定义的路由不匹配的请求触发每个路由过滤器的问题
  • 将 go-control-plane 升级至 v0.12.0

Cli

  • 添加了对 egctl x status 命令的支持
  • 添加了对 egctl experimental dashboard envoy-proxy 命令的支持
  • 添加了对 egctl config ratelimit 命令的支持
  • 添加了对从 gateway-api 资源到 IR 的 gctl translate from gateway-api 命令的支持