From dc5b71a93e27542a4c855f76cdb0f0592885bc1b Mon Sep 17 00:00:00 2001 From: Wilson Wu Date: Mon, 13 May 2024 16:27:30 +0800 Subject: [PATCH 1/4] Translate Developer Guide and related docs into Chinese Signed-off-by: Wilson Wu --- site/content/zh/contributions/DEVELOP.md | 156 ++++++++++ site/content/zh/latest/tasks/quickstart.md | 2 +- .../tasks/security/jwt-authentication.md | 164 +++++++++++ .../zh/latest/tasks/traffic/grpc-routing.md | 271 ++++++++++++++++++ 4 files changed, 592 insertions(+), 1 deletion(-) create mode 100644 site/content/zh/contributions/DEVELOP.md create mode 100644 site/content/zh/latest/tasks/security/jwt-authentication.md create mode 100644 site/content/zh/latest/tasks/traffic/grpc-routing.md diff --git a/site/content/zh/contributions/DEVELOP.md b/site/content/zh/contributions/DEVELOP.md new file mode 100644 index 00000000000..afd2a49381c --- /dev/null +++ b/site/content/zh/contributions/DEVELOP.md @@ -0,0 +1,156 @@ +--- +title: "开发者指南" +description: "本节介绍如何开发 Envoy Gateway。" +weight: 2 +--- + +Envoy Gateway 使用基于 [make][] 的构建系统进行构建。我们的 CI 使用基于 [Github Actions][] 的[工作流][]建设。 + +## 先决条件 {#prerequisites} + +### go {#go} + +* 版本：1.20 +* 安装指南：https://go.dev/doc/install + +### make {#make} + +* 推荐版本：4.0 或更高 +* 安装指南：https://www.gnu.org/software/make + +### docker {#docker} + +* 当您想要构建 Docker 镜像或在 Docker 内运行 `make` 时可选。 +* 推荐版本：20.10.16 +* 安装指南：https://docs.docker.com/engine/install + +### python3 {#python3} + +* 需要一个 `python3` 程序 +* 必须有一个正常运行的 `venv` 模块；这是标准库的一部分，但某些发行版使用 stub 将其替换（例如 Debian 和 Ubuntu）， + 并要求您单独安装 `python3-venv` 包。 + +## 快速开始 {#quickstart} + +* 运行 `make help` 以查看构建、测试和运行 Envoy Gateway 的所有可用目标。 + +### 构建 {#building} + +* 运行 `make build` 来构建所有二进制文件。 +* 运行 `make build BINS="envoy-gateway"` 来构建 Envoy Gateway 二进制文件。 +* 运行 `make build BINS="egctl"` 来构建 egctl 二进制文件。 + +**注意：**二进制文件在 `bin/$OS/$ARCH` 目录中生成，例如，`bin/linux/amd64/`。 + +### 测试 {#testing} + +* 运行 `make test` 来运行 golang 测试。 + +* 运行 `make testdata` 生成黄金 YAML 测试数据文件。 + +### 运行 Linter {#running-linters} + +* 运行 `make lint` 以确保您的代码通过所有 Linter 检查。 + +**注意：**`golangci-lint` 配置位于[此处](https://github.com/envoyproxy/gateway/blob/main/tools/linter/golangci-lint/.golangci.yml)。 + +### 构建并推送镜像 {#building-and-pushing-the-image} + +* 运行 `IMAGE=docker.io/you/gateway-dev make image` 来构建 Docker 镜像。 +* 运行 `IMAGE=docker.io/you/gateway-dev make push-multiarch` 来构建并推送多架构 Docker 镜像。 + +**注意：**将 `IMAGE` 替换为您的仓库的镜像名称。 + +### 部署 Envoy Gateway 进行测试/开发 {#deploying-envoy-gateway-for-testdev} + +* 运行 `make create-cluster` 创建一个 [Kind][] 集群。 + +#### 选项 1：使用最新的 [gateway-dev][] 镜像 {#option-1-use-the-latest-gateway-dev-image} + +* 运行 `TAG=latest make kube-deploy` 以使用最新镜像在 Kind 集群中部署 Envoy Gateway。 + 替换 `latest` 以使用不同的镜像标签。 + +#### 选项 2：使用自定义镜像 {#option-2-use-a-custom-image} + +* 运行 `make kube-install-image` 从当前分支的最新构建镜像并将其加载到 Kind 集群中。 +* 运行 `IMAGE_PULL_POLICY=IfNotPresent make kube-deploy` 以使用自定义镜像将 Envoy Gateway 安装到 Kind 集群中。 + +### 在 Kubernetes 中部署 Envoy Gateway {#deploying-envoy-gateway-in-kubernetes} + +* 运行 `TAG=latest make kube-deploy` 以使用最新镜像将 Envoy Gateway 部署到 Kubernetes 集群（链接到当前 kube 上下文）。 + 在命令前面加上 `IMAGE` 或替换 `TAG` 以使用不同的 Envoy Gateway 镜像或标签。 +* 运行 `make kube-undeploy` 从集群中卸载 Envoy Gateway。 + +**注意：**Envoy Gateway 针对 Kubernetes v1.24.0 进行了测试。 + +### 演示设置 {#demo-setup} + +* 运行 `make kube-demo` 来部署演示后端服务、GatewayClass、Gateway 和 HTTPRoute 资源 + （类似于[快速入门][]文档中概述的步骤）并测试配置。 +* 运行 `make kube-demo-undeploy` 删除 `make kube-demo` 命令创建的资源。 + +### 运行 Gateway API 一致性测试 {#run-gateway-api-conformance-tests} + +通过以下命令将 Envoy Gateway 部署到 Kubernetes 集群并运行 Gateway API 一致性测试。 +请参阅 Gateway API [一致性主页][]以了解有关测试的更多信息。如果 Envoy Gateway 已安装， +请运行 `TAG=latest make run-conformance` 来运行一致性测试。 + +#### 在 Linux 主机上 {#on-a-linux-host} + +* 运行 `TAG=latest make conformance` 来创建 Kind 集群， + 使用最新的 [gateway-dev][] 镜像安装 Envoy Gateway，并运行 Gateway API 一致性测试。 + +#### 在 Mac 主机上 {#on-a-mac-host} + +由于 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][mac_connect]，然后运行 `TAG=latest make conformance`。 + +**注意：**在命令前加上 `IMAGE` 或替换 `TAG` 以使用不同的 Envoy Gateway 镜像或标签。如果未指定 `TAG`，则使用当前分支的短 SHA。 + +### 调试 Envoy 配置 {#debugging-the-envoy-config} + +查看 Envoy Gateway 正在使用的 Envoy 配置的一种简单方法是将端口转发到与 Gateway +对应的 Envoy 部署上的管理界面端口（当前为 `19000`），以便可以在本地访问它。 + +获取 Envoy 部署的名称。以下示例适用于 `default` 命名空间中的网关 `eg`： + +```shell +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}') +``` + +通过端口转发管理接口端口： + +```shell +kubectl port-forward deploy/${ENVOY_DEPLOYMENT} -n envoy-gateway-system 19000:19000 +``` + +现在，您可以通过导航到 `127.0.0.1:19000/config_dump` 来查看正在运行的 Envoy 配置。 + +[Envoy 管理接口][]上还有许多其他端点在调试时可能会有所帮助。 + +### JWT 测试 {#jwt-testing} + +[JSON Web Token（JWT）][jwt]和 [JSON Web Key Set（JWKS）][jwks]示例用于[请求身份验证][]任务。 +JWT 由 [JWT Debugger][] 使用 `RS256` 算法创建。JWT 验证签名中的公钥已复制到 [JWK Creator][] 以生成 JWK。 +JWK Creator 配置了匹配的设置，即 `Signing` 公钥使用和 `RS256` 算法。生成的 JWK 包装在 JWKS 结构中并托管在仓库中。 + +[快速入门]: https://github.com/envoyproxy/gateway/blob/main/docs/latest/user/quickstart.md +[make]: https://www.gnu.org/software/make/ +[Github Actions]: https://docs.github.com/en/actions +[工作流]: https://github.com/envoyproxy/gateway/tree/main/.github/workflows +[Kind]: https://kind.sigs.k8s.io/ +[一致性主页]: https://gateway-api.sigs.k8s.io/concepts/conformance/ +[直接暴露]: https://kind.sigs.k8s.io/docs/user/loadbalancer/ +[Kubernetes 支持]: https://docs.docker.com/desktop/kubernetes/ +[gateway-dev]: https://hub.docker.com/r/envoyproxy/gateway-dev/tags +[mac_connect]: https://github.com/chipmk/docker-mac-net-connect +[Envoy 管理接口]: https://www.envoyproxy.io/docs/envoy/latest/operations/admin#operations-admin-interface +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[请求身份验证]: ../latest/tasks/security/jwt-authentication +[JWT Debugger]: https://jwt.io/ +[JWK Creator]: https://russelldavies.github.io/jwk-creator/ diff --git a/site/content/zh/latest/tasks/quickstart.md b/site/content/zh/latest/tasks/quickstart.md index aa94962e71a..8e32fdf5aa3 100644 --- a/site/content/zh/latest/tasks/quickstart.md +++ b/site/content/zh/latest/tasks/quickstart.md @@ -1,5 +1,5 @@ --- -title: "快速开始" +title: "快速入门" weight: 1 description: 只需几个简单的步骤即可开始使用 Envoy Gateway。 --- diff --git a/site/content/zh/latest/tasks/security/jwt-authentication.md b/site/content/zh/latest/tasks/security/jwt-authentication.md new file mode 100644 index 00000000000..a06399bc33f --- /dev/null +++ b/site/content/zh/latest/tasks/security/jwt-authentication.md @@ -0,0 +1,164 @@ +--- +title: "JWT 身份验证" +--- + +此任务提供有关配置 [JSON Web Token（JWT）][jwt]身份验证的说明。 +JWT 身份验证在将请求路由到后端服务之前检查传入请求是否具有有效的 JWT。 +目前，Envoy Gateway 仅支持通过 HTTP 标头验证 JWT，例如 `Authorization: Bearer `。 + +Envoy Gateway 引入了一个名为 [SecurityPolicy][SecurityPolicy] 的新 CRD，允许用户配置 JWT 身份验证。 +该实例化资源可以链接到 [Gateway][Gateway]、[HTTPRoute][HTTPRoute] 或 [GRPCRoute][GRPCRoute] 资源。 + +## 先决条件 {#prerequisites} + +按照[快速入门](../quickstart)中的步骤安装 Envoy Gateway 和示例清单。 +对于 GRPC - 请按照 [GRPC 路由](../traffic/grpc-routing)示例中的步骤操作。 +在继续之前，您应该能够使用 HTTP 或 GRPC 查询示例程序后端。 + +## 配置 {#configuration} + +通过创建 [SecurityPolicy][SecurityPolicy] 并将其附加到示例 HTTPRoute 或 GRPCRoute，允许使用具有有效 JWT 的请求。 + +### HTTPRoute {#httproute} + +```shell +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 配置和状态： + +```shell +kubectl get httproute/foo -o yaml +kubectl get httproute/bar -o yaml +``` + +SecurityPolicy 配置为 JWT 身份验证，并使用单个 [JSON Web Key Set（JWKS）][jwks]提供程序来对 JWT 进行身份验证。 + +验证 SecurityPolicy 配置： + +```shell +kubectl get securitypolicy/jwt-example -o yaml +``` + +### GRPCRoute {#grpcroute} + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/jwt/grpc-jwt.yaml +``` + +已创建 SecurityPolicy 并针对 GRPCRoute yages 来验证 `yages` 服务的所有请求。 + +验证 GRPCRoute 配置和状态： + +```shell +kubectl get grpcroute/yages -o yaml +``` + +SecurityPolicy 配置为 JWT 身份验证，并使用单个 [JSON Web Key Set（JWKS）][jwks]提供程序来对 JWT 进行身份验证。 + +验证 SecurityPolicy 配置： + +```shell +kubectl get securitypolicy/jwt-example -o yaml +``` + +## 测试 {#testing} + +确保设置了[快速入门](../../quickstart) 中的 `GATEWAY_HOST` 环境变量。如果没有，请按照快速入门说明设置变量。 + +```shell +echo $GATEWAY_HOST +``` + +### HTTPRoute {#httproute-1} + +验证在没有 JWT 的情况下对 `/foo` 的请求是否被拒绝： + +```shell +curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/foo +``` + +应返回一个 `401` HTTP 响应码。 + +获取用于测试请求身份验证的 JWT： + +```shell +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` 发出请求： + +```shell +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` 发出请求： + +```shell +curl -sS -o /dev/null -H "Host: www.example.com" -w "%{http_code}\n" http://$GATEWAY_HOST/bar +``` + +### GRPCRoute {#grpcroute-1} + +验证是否在没有 JWT 的情况下拒绝对 `yages` 服务的请求： + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +您应该看到以下响应： + +```shell +Error invoking method "yages.Echo/Ping": rpc error: code = Unauthenticated desc = failed to query for service descriptor "yages.Echo": Jwt is missing +``` + +获取用于测试请求身份验证的 JWT： + +```shell +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` 服务发出请求： + +```shell +grpcurl -plaintext -H "authorization: Bearer $TOKEN" -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +您应该看到以下响应： + +```shell +{ + "text": "pong" +} +``` + +## 清理 {#clean-up} + +按照[快速入门](../../quickstart) 中的步骤卸载 Envoy Gateway 和示例清单。 + +删除 SecurityPolicy： + +```shell +kubectl delete securitypolicy/jwt-example +``` + +## 后续步骤 {#next-steps} + +查看[开发者指南](../../../contributions/develop)参与该项目。 + +[SecurityPolicy]: ../../../contributions/design/security-policy +[jwt]: https://tools.ietf.org/html/rfc7519 +[jwks]: https://tools.ietf.org/html/rfc7517 +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway +[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute diff --git a/site/content/zh/latest/tasks/traffic/grpc-routing.md b/site/content/zh/latest/tasks/traffic/grpc-routing.md new file mode 100644 index 00000000000..6acffe4e32a --- /dev/null +++ b/site/content/zh/latest/tasks/traffic/grpc-routing.md @@ -0,0 +1,271 @@ +--- +title: "GRPC 路由" +--- + +[GRPCRoute][] 资源允许用户通过匹配 HTTP/2 流量并将其转发到后端 gRPC 服务器来配置 gRPC 路由。 +要了解有关 gRPC 路由的更多信息，请参阅[Gateway API 文档][]。 + +## 先决条件 {#prerequisites} + +按照[快速入门](../quickstart)中的步骤安装 Envoy Gateway 和示例清单。 +在继续之前，您应该能够使用 HTTP 查询示例程序后端。 + +## 安装 {#installation} + +安装 gRPC 路由示例资源： + +```shell +kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/examples/kubernetes/grpc-routing.yaml +``` + +该清单安装 [GatewayClass][]、[Gateway][]、Deployment、Service 和 GRPCRoute 资源。 +GatewayClass 是集群范围的资源，表示可以被实例化的一类 Gateway。 + +**注意：**Envoy Gateway 默认被配置为使用 `controllerName: gateway.envoyproxy.io/gatewayclass-controller` 管理 GatewayClass。 + +## 验证 {#verification} + +检查 GatewayClass 的状态： + +```shell +kubectl get gc --selector=example=grpc-routing +``` + +状态应反映为 `Accepted=True`，表示 Envoy Gateway 正在管理 GatewayClass。 + +Gateway 代表基础设施的配置。创建 Gateway 时，[Envoy 代理][]基础设施由 Envoy Gateway 预配或配置。 +`gatewayClassName` 定义此 Gateway 使用的 GatewayClass 的名称。检查 Gateway 状态： + +```shell +kubectl get gateways --selector=example=grpc-routing +``` + +状态应反映为 `Ready=True`，表示 Envoy 代理基础设施已被配置。 +该状态还提供 Gateway 的地址。该地址稍后用于测试与代理后端服务的连接。 + +检查 GRPCRoute 的状态： + +```shell +kubectl get grpcroutes --selector=example=grpc-routing -o yaml +``` + +GRPCRoute 的状态应显示 `Accepted=True` 和引用示例 Gateway 的 `parentRef`。 +`example-route` 匹配 `grpc-example.com` 的任何流量并将其转发到 `yages` 服务。 + +## 测试配置 {#testing-the-configuration} + +在测试到 `yages` 后端的 GRPC 路由之前，请获取 Gateway 的地址。 + +```shell +export GATEWAY_HOST=$(kubectl get gateway/example-gateway -o jsonpath='{.status.addresses[0].value}') +``` + +使用 [grpcurl][] 命令测试到 `yages` 后端的 GRPC 路由。 + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +您应该看到以下响应： + +```shell +{ + "text": "pong" +} +``` + +Envoy Gateway 还支持此配置的 [gRPC-Web][] 请求。下面的 `curl` 命令可用于通过 HTTP/2 发送 grpc-Web 请求。 +您应该收到与上一个命令相同的响应。 + +正文 `AAAAAAA=` 中的数据是 Ping RPC 接受的空消息（数据长度为 0）的 Base64 编码表示。 + +```shell +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 匹配 {#grpcroute-match} + +`matches` 字段可用于根据 GRPC 的服务和/或方法名称将路由限制到一组特定的请求。 +它支持两种匹配类型：`Exact`（精准）和 `RegularExpression`（正则）。 + +### 精准 {#exact} + +`Exact`（精准）匹配是默认匹配类型。 + +以下示例显示如何根据 `grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo` 的服务和方法名称来匹配请求， +以及如何在我们的部署中匹配方法名称为 `Ping` 且与 `yages.Echo/Ping` 匹配的所有服务。 + +{{< tabpane text=true >}} +{{% tab header="通过标准输入应用" %}} + +```shell +cat <}} + +验证 GRPCRoute 状态： + +```shell +kubectl get grpcroutes --selector=example=grpc-routing -o yaml +``` + +使用 [grpcurl][] 命令测试到 `yages` 后端的 GRPC 路由。 + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +### 正则 {#regularexpression} + +以下示例演示如何根据服务和方法名称将请求与匹配类型 `RegularExpression` 进行匹配。 +它与模式 `/.*.Echo/Pin.+` 匹配所有服务和方法，该模式与我们部署中的 `yages.Echo/Ping` 匹配。 + +{{< tabpane text=true >}} +{{% tab header="通过标准输入应用" %}} + +```shell +cat <}} + +检查 GRPCRoute 状态： + +```shell +kubectl get grpcroutes --selector=example=grpc-routing -o yaml +``` + +使用 [grpcurl][] 命令测试到 `yages` 后端的 GRPC 路由。 + +```shell +grpcurl -plaintext -authority=grpc-example.com ${GATEWAY_HOST}:80 yages.Echo/Ping +``` + +[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute/ +[Gateway API 文档]: https://gateway-api.sigs.k8s.io/ +[GatewayClass]: https://gateway-api.sigs.k8s.io/api-types/gatewayclass/ +[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway/ +[Envoy 代理]: https://www.envoyproxy.io/ +[grpcurl]: https://github.com/fullstorydev/grpcurl +[gRPC-Web]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md#protocol-differences-vs-grpc-over-http2 From 991afb2632a37ec63e68140dfd640c1effd56555 Mon Sep 17 00:00:00 2001 From: Wilson Wu Date: Tue, 14 May 2024 10:47:01 +0800 Subject: [PATCH 2/4] Update site/content/zh/contributions/DEVELOP.md Co-authored-by: sh2 Signed-off-by: Wilson Wu --- site/content/zh/contributions/DEVELOP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/zh/contributions/DEVELOP.md b/site/content/zh/contributions/DEVELOP.md index afd2a49381c..b1b270dbe97 100644 --- a/site/content/zh/contributions/DEVELOP.md +++ b/site/content/zh/contributions/DEVELOP.md @@ -46,7 +46,7 @@ Envoy Gateway 使用基于 [make][] 的构建系统进行构建。我们的 CI * 运行 `make test` 来运行 golang 测试。 -* 运行 `make testdata` 生成黄金 YAML 测试数据文件。 +* 运行 `make testdata` 生成标准的 YAML 测试数据文件。 ### 运行 Linter {#running-linters} From 2677650fee9c5352d29c3628bc546940a036d61c Mon Sep 17 00:00:00 2001 From: Wilson Wu Date: Tue, 14 May 2024 16:02:00 +0800 Subject: [PATCH 3/4] Translate missed security policy design Signed-off-by: Wilson Wu --- .../contributions/design/security-policy.md | 114 ++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 site/content/zh/contributions/design/security-policy.md diff --git a/site/content/zh/contributions/design/security-policy.md b/site/content/zh/contributions/design/security-policy.md new file mode 100644 index 00000000000..09b8ea023e8 --- /dev/null +++ b/site/content/zh/contributions/design/security-policy.md @@ -0,0 +1,114 @@ +--- +title: "SecurityPolicy" +--- + +## 概述 {#overview} + +本设计文档引入了 `SecurityPolicy` API，允许系统管理员为进入网关的流量配置身份验证和鉴权策略。 + +## 目标 {#goals} + +* 添加 API 定义以保存用于配置进入网关的流量的身份验证和鉴权规则的设置。 + +## 非目标 {#non-goals} + +* 定义该 API 中的 API 配置字段。 + +## 实现 {#implementation} + +`SecurityPolicy` 是一个[策略附件][]类型的 API，可用于扩展 [Gateway API][] 来定义身份验证和鉴权规则。 + +### 示例 {#example} + +以下示例重点介绍了用户如何配置此 API。 + +``` +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: eg +spec: + controllerName: gateway.envoyproxy.io/gatewayclass-controller +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: eg + namespace: default +spec: + gatewayClassName: eg + listeners: + - name: https + protocol: HTTPS + port: 443 +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: backend + namespace: default +spec: + parentRefs: + - name: eg + hostnames: + - "www.example.com" + rules: + - backendRefs: + - group: "" + kind: Service + name: backend + port: 3000 + weight: 1 + matches: + - path: + type: PathPrefix + value: / +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: SecurityPolicy +metadata: + name: jwt-authn-policy + namespace: default +spec: + jwt: + providers: + - name: example + remoteJWKS: + uri: https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/jwt/jwks.json + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: eg + namespace: default +``` + +## 功能及 API 字段 {#features-api-fields} + +以下是此 API 中包含的功能列表： +* JWT 基础鉴权 +* OIDC 鉴权 +* 外部认证 +* Basic Auth +* API Key Auth +* CORS（跨域） + +## 设计决策 {#design-decisions} + +* 此 API 仅支持单个 `targetRef`，并且可以绑定到 `Gateway` 资源或 `HTTPRoute` 或 `GRPCRoute`。 +* 此 API 资源**必须**与 targetRef 资源属于同一命名空间 +* 只能有**一个**策略资源附加到特定的 targetRef，例如 `Gateway` 内的 `Listener`（部分） +* 如果策略针对某个资源但无法附加到该资源，则应使用 `Conflicted=True` 条件将该信息反映在“策略状态”字段中。 +* 如果多个策略针对同一资源，则最旧的资源（基于创建时间戳）将附加到网关侦听器，其他资源则不会。 +* 如果策略 A 具有包含 `sectionName` 的 `targetRef`，即它以 `Gateway` 内的特定侦听器为目标， + 并且策略 B 具有以同一整个 Gateway 为目标的 `targetRef`，则 + * 策略 A 将应用/附加到 `targetRef.SectionName` 中定义的特定监听器 + * 策略 B 将应用于 Gateway 内的其余侦听器。策略 B 将具有附加状态条件 `Overridden=True`。 +* 针对拥有具体范围的策略胜过针对缺少具体范围的策略。即，针对 xRoute（`HTTPRoute` 或 `GRPCRoute`）的策略会覆盖针对侦听器的策略， + 该侦听器是该路由的 parentRef，而侦听器又会覆盖针对侦听器/部分所属 Gateway 的策略。 + +## 替代方案 {#alternatives} + +* 项目可以无限期地等待这些配置参数成为 [Gateway API][] 的一部分。 + +[策略附件]: https://gateway-api.sigs.k8s.io/references/policy-attachment +[Gateway API]: https://gateway-api.sigs.k8s.io/ From c9bb05734e79eb5ce70126a65004292fb23f5121 Mon Sep 17 00:00:00 2001 From: Wilson Wu Date: Wed, 15 May 2024 12:31:52 +0800 Subject: [PATCH 4/4] Update site/content/zh/contributions/design/security-policy.md Co-authored-by: sh2 Signed-off-by: Wilson Wu --- site/content/zh/contributions/design/security-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/zh/contributions/design/security-policy.md b/site/content/zh/contributions/design/security-policy.md index 09b8ea023e8..50bacc040a5 100644 --- a/site/content/zh/contributions/design/security-policy.md +++ b/site/content/zh/contributions/design/security-policy.md @@ -22,7 +22,7 @@ title: "SecurityPolicy" 以下示例重点介绍了用户如何配置此 API。 -``` +```yaml apiVersion: gateway.networking.k8s.io/v1 kind: GatewayClass metadata: