diff --git a/calico-enterprise/networking/gateway-api.mdx b/calico-enterprise/networking/gateway-api.mdx new file mode 100644 index 0000000000..d40de8a3f4 --- /dev/null +++ b/calico-enterprise/networking/gateway-api.mdx @@ -0,0 +1,418 @@ +--- +description: Enable support for the Kubernetes Gateway API. +--- + +# Gateway API + +## Big picture + +Enable support for the Kubernetes Gateway API. + +:::note + +This feature is tech preview. Tech preview features may be subject to significant changes before they become GA. + +::: + +## Value + +{{prodname}} includes support for the Kubernetes Gateway API, which allows advanced routing to services in a cluster, including weighted or blue-green load balancing. + +## Concepts + +### Gateway API + +The Gateway API is an official Kubernetes API for advanced routing to services in a cluster. To read about its use cases, structure and design, please see [the official docs](https://gateway-api.sigs.k8s.io/). {{prodname}} provides the following resources and versions of the Gateway API. + +| Resource | Versions | +| ---------------- | ----------------- | +| BackendLBPolicy | v1alpha2 | +| BackendTLSPolicy | v1alpha3 | +| GatewayClass | v1, v1beta1 | +| Gateway | v1, v1beta1 | +| GRPCRoute | v1, v1alpha2 | +| HTTPRoute | v1, v1beta1 | +| ReferenceGrant | v1beta1, v1alpha2 | +| TCPRoute | v1alpha2 | +| TLSRoute | v1alpha2 | +| UDPRoute | v1alpha2 | + +### Envoy Gateway + +Several implementations of the Gateway API are available, one of which is the [Envoy Gateway](https://gateway.envoyproxy.io/). {{prodname}} integrates the Envoy Gateway implementation in order to provide support for the Gateway API. + +### Access into a cluster from outside + +The Gateway API only provides access into a cluster from outside when the cluster is _also_ provisioned to support Kubernetes Services with `type: LoadBalancer`. When a Gateway is configured, {{prodname}} creates a Deployment that does the actual work of routing and load balancing, etc., and a Service with `type: LoadBalancer` that fronts that Deployment. If the cluster has a `type: LoadBalancer` provider, it will then allocate an IP outside the cluster and arrange for requests to that IP to be forwarded to the Gateway Service. + +Managed Kubernetes services like AKS, EKS and GKE include a `type: LoadBalancer` provider that automatically integrates with Azure, AWS and GCP respectively. On-prem clusters and non-managed clusters in the cloud need to set up their own `type: LoadBalancer` support. + +## Before you begin + +**Unsupported** + +- Windows + +## How to + +- [Enable Gateway API support](#enable-gateway-api-support) +- [Use the Gateway API](#use-the-gateway-api) +- [Disable Gateway API support](#disable-gateway-api-support) + +### Enable Gateway API support + +To enable Gateway API support, create a `GatewayAPI` resource with name `tigera-secure`: + +```bash +kubectl apply -f - < 18000/TCP,18001/TCP,18002/TCP,19001/TCP 36m + ``` + + The Service for the Gateway is the one beginning with `envoy-default-`, followed by the name of the Gateway resource. So the correct cluster IP in this case is 10.0.20.19. (The `envoy-gateway` Service represents the gateway controller, which is the component that monitors for Gateway API resources and creates corresponding components to implement those.) + +- Curl from the test client pod to a URL that should be handled by the echo server in namespace `ns1`, via the Gateway: + + ```bash + kubectl exec -it test-client -- curl http://10.0.20.19/ns1/subpath?query=demo | jq + ``` + +- The output confirms - see the `"HOSTNAME"` line - that the request was handled by the echo server in namespace `ns1`: + + ``` + { + "host": { + "hostname": "10.0.20.19", + "ip": "::ffff:10.224.0.10", + "ips": [] + }, + "http": { + "method": "GET", + "baseUrl": "", + "originalUrl": "/ns1/subpath?query=demo", + "protocol": "http" + }, + "request": { + "params": { + "0": "/ns1/subpath" + }, + "query": { + "query": "demo" + }, + "cookies": {}, + "body": {}, + "headers": { + "host": "10.0.20.19", + "user-agent": "curl/8.5.0", + "accept": "*/*", + "x-forwarded-for": "10.224.0.18", + "x-forwarded-proto": "http", + "x-envoy-internal": "true", + "x-request-id": "375a5b78-60fc-4a87-89b0-b4c6501115ca" + } + }, + "environment": { + "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "HOSTNAME": "echoserver-ns1", + "NODE_VERSION": "20.11.0", + "YARN_VERSION": "1.22.19", + "PORT": "80", + "ECHOSERVER_SERVICE_HOST": "10.0.111.210", + "ECHOSERVER_PORT": "tcp://10.0.111.210:80", + "ECHOSERVER_PORT_80_TCP": "tcp://10.0.111.210:80", + "KUBERNETES_SERVICE_HOST": "10.0.0.1", + "KUBERNETES_SERVICE_PORT": "443", + "KUBERNETES_SERVICE_PORT_HTTPS": "443", + "ECHOSERVER_PORT_80_TCP_ADDR": "10.0.111.210", + "KUBERNETES_PORT": "tcp://10.0.0.1:443", + "ECHOSERVER_SERVICE_PORT": "80", + "ECHOSERVER_PORT_80_TCP_PORT": "80", + "KUBERNETES_PORT_443_TCP_PORT": "443", + "ECHOSERVER_PORT_80_TCP_PROTO": "tcp", + "KUBERNETES_PORT_443_TCP": "tcp://10.0.0.1:443", + "KUBERNETES_PORT_443_TCP_PROTO": "tcp", + "KUBERNETES_PORT_443_TCP_ADDR": "10.0.0.1", + "HOME": "/root" + } + } + ``` + +- Curl from the test client pod to a URL that should be handled by the echo server in namespace `ns2`, via the Gateway: + + ```bash + kubectl exec -it test-client -- curl http://10.0.20.19/ns2/subpath?query=demo | jq + ``` + +- The output confirms that the request was handled by the echo server in namespace `ns2`: + + ``` + ... + "HOSTNAME": "echoserver-ns2", + ... + ``` + +### Disable Gateway API support + +To disable Gateway API support, first delete all the Gateway API resources that you have configured yourself. In the example above, that would be the ReferenceGrants, the HTTPRoutes and the Gateway. Then delete the `GatewayAPI` resource with name `tigera-secure`: + +```bash +kubectl delete -f - <