From e3f008e8bfb8c4f21b06dc75500d36c52c54da6a Mon Sep 17 00:00:00 2001 From: AliceProxy Date: Thu, 9 Feb 2023 09:26:05 -0800 Subject: [PATCH] add gatewayapi support doc Signed-off-by: AliceProxy --- docs/v0.2.0/design/gatewayapi-support.md | 76 ++++++++++++++++++++++++ docs/v0.2.0/design_docs.rst | 1 + 2 files changed, 77 insertions(+) create mode 100644 docs/v0.2.0/design/gatewayapi-support.md diff --git a/docs/v0.2.0/design/gatewayapi-support.md b/docs/v0.2.0/design/gatewayapi-support.md new file mode 100644 index 000000000000..27dd2bd61f0e --- /dev/null +++ b/docs/v0.2.0/design/gatewayapi-support.md @@ -0,0 +1,76 @@ +# Gateway API Support + +As mentioned in the [SystemDesign][] document, Envoy Gateway's managed data plane is configured dynamically through +Kubernetes resources, primarily [Gateway API][] objects. Envoy Gateway supports configuration using the following Gateway API resources. + +## **GatewayClass** + +[GatewayClasses][] are used to configure which Gateways and other reliant resources should be managed by Envoy Gateway. + +## **Gateway** + +When a [Gateway][] resource is created that references the GatwewayClass Envoy Gateway is managing then Envoy Gateway will +create and manage a new Envoy Proxy deployment. All other Gateway API resources that are managed by this Gateway will be used +to configure the Envoy Proxy deployment that it created. + +## **HTTPRoute** + +[HTTPRoutes][] are supported as the primary way to configure HTTP traffic in Envoy Gateway. +All of the following HTTPRoute filters are supported by Envoy Gateway. + +- `requestHeaderModifier`: [RequestHeaderModifiers](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteFilter) can be used to modify or add request headers before the request is proxied to its destination. +- `responseHeaderModifier`: [ResponseHeaderModifiers](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteFilter) can be used to modify or add response headers before the response is sent back to the client. +- `requestMirror`: [RequestMirrors](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteFilter) configure destinations where the requests should also be mirrored to. Responses to mirrored requests will be ignored. +- `requestRedirect`: [RequestRedirects](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteFilter) configure policied for how requests that match the HTTPRoute should be modified and then redirected. +- `urlRewrite`: [UrlRewrites](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRouteFilter) allow for modification of the request's hostname and path before it is proxied to its destination. +- filters... + +**Note:** currently the only kind of [BackendRef][] kind (the destination where traffic should be sent to) that Envoy Gateway supports are Kubernetes services. Routing traffic to other destinations such as arbitrary URLs is not currently possible. + +## **TCPRoute** + +[TCPRoutes][] are used to configure routing of raw TCP traffic. Traffic can be forwarded to the desired BackendRef(s) based on a port. + +**Note:** TCPRoutes only support proxying in non-transparent mode i.e. the backend will see the source IP and port of the deployed +Envoy instance instead of the client. + +## **UDPRoute** + +[UDPRoutes][] are used to configure routing of raw UDP traffic. Traffic can be forwarded to the desired BackendRef(s) based on a port. + +**Note:** Similar to TCPRoutes, UDPRoutes only support proxying in non-transparent mode i.e. the backend will see the source IP and port of the deployed +Envoy instance instead of the client. + +## **GRPCRoute** + +[GRPCRoutes][] configure routing of [gRPC][] requests. They offer request matching by hostname, gRPC service, gRPC method, or HTTP/2 Header. +Similar to HTTPRoutes, Envoy Gateway supports the following filters on GRPCRoutes to provide additional traffic processing. + +- `requestHeaderModifier`: [RequestHeaderModifiers](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteFilter) can be used to modify or add request headers before the request is proxied to its destination. +- `responseHeaderModifier`: [ResponseHeaderModifiers](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteFilter) can be used to modify or add response headers before the response is sent back to the client. +- `requestMirror`: [RequestMirrors](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteFilter) configure destinations where the requests should also be mirrored to. Responses to mirrored requests will be ignored. + +**Note:** currently the only kind of [BackendRef](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRouteFilter) kind (the destination where traffic should be sent to) that Envoy Gateway supports are Kubernetes services. Routing traffic to other destinations such as arbitrary URLs is not currently possible + +## **TLSRoute** + +[TLSRoutes][] are used similarly to TCPRoutes to configure routing of TCP traffic; however, unlike TCPRoutes, TLSRoutes can match against TLS-Specific Metadata. + +## **ReferenceGrant** + +[ReferenceGrants][] are used as a way to configure which resources in other namespaces are allowed to reference specific kinds of resources in +the namespace of the ReferenceGrant. Normally an HTTPRoute created in namespace `foo` is not allowed to specify a service in the `bar` namespace as the +one of its BackendRefs. ReferenceGrants are commonly used to permit these types of cross-namespace references. + +[SystemDesign]: system-design.md +[Gateway API]: https://gateway-api.sigs.k8s.io/ +[GatewayClasses]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.GatewayClass +[Gateway]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.Gateway +[HTTPRoutes]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPRoute +[BackendRef]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.BackendRef +[TCPRoutes]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute +[UDPRoutes]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.UDPRoute +[GRPCRoutes]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.GRPCRoute +[gRPC]: https://grpc.io/ +[TLSRoutes]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute +[ReferenceGrants]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io%2fv1beta1.ReferenceGrant \ No newline at end of file diff --git a/docs/v0.2.0/design_docs.rst b/docs/v0.2.0/design_docs.rst index 4e95a518d1e9..b1e41a6132b1 100644 --- a/docs/v0.2.0/design_docs.rst +++ b/docs/v0.2.0/design_docs.rst @@ -10,3 +10,4 @@ Learn about the internal details of Envoy Gateway. design/gatewayapi-translator design/watching design/config-api + design/gatewayapi-support \ No newline at end of file