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

接下来

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

3 - 安装

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

3.1 - 兼容性表格

本节包含关于 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