diff --git a/docs/content/usage/integrations/.pages b/docs/content/usage/integrations/.pages index b0579ff79..1da4d15d4 100644 --- a/docs/content/usage/integrations/.pages +++ b/docs/content/usage/integrations/.pages @@ -1,3 +1,4 @@ nav: - cert-manager.md - crossplane.md + - kro.md diff --git a/docs/content/usage/integrations/kro-gw-api.png b/docs/content/usage/integrations/kro-gw-api.png new file mode 100644 index 000000000..8fc3309d7 Binary files /dev/null and b/docs/content/usage/integrations/kro-gw-api.png differ diff --git a/docs/content/usage/integrations/kro.md b/docs/content/usage/integrations/kro.md new file mode 100644 index 000000000..74e7ebd91 --- /dev/null +++ b/docs/content/usage/integrations/kro.md @@ -0,0 +1,518 @@ +--- +title: kro +description: | + Guide on integrating kube-bind with kro and Envoy Gateway for serving LoadBalancer as a Service. +weight: 30 +--- + +# kro Integration (providing LoadBalancer as a Service) + +This guide demonstrates how to use [kro](https://kro.run/) and +[Envoy Gateway](https://gateway.envoyproxy.io/) to offer a "LoadBalancer as a Service" API in +multi-cluster environments. + +When operating multiple clusters on-premises, managing load balancer infrastructure separately +for each cluster becomes operationally expensive. This integration enables a centralized load +balancer cluster that serves all tenant clusters connected via converged networking solutions. +By running load balancer resources in a dedicated load balancer cluster, organizations can simplify +operations for application teams who can self-service load balancers without managing the +underlying infrastructure and enforce consistent security policies and configuration across +gateways. + +![kro gateway-api example architecture diagram](kro-gw-api.png) + +In this guide in the consumer cluster we create a simple `LoadBalancer` object, and the provider +automatically provisions an Envoy Gateway infrastructure and related `Gateway` and `HTTPRoute` to +expose the service between two kind clusters. + +This example includes support for syncing **custom configuration (via ConfigMaps or Secrets)** from +consumer clusters to the provider. + +!!! note + For this to work end-to-end, the consumer's service (`backend`) must be reachable from the + provider cluster (e.g., via multi-cluster networking). + + In this example, we simulate multi-cluster networking by exposing the consumer's backend + service via NodePort and creating corresponding Service/EndpointSlice in the provider cluster. + In production, you would use proper multi-cluster networking solutions like Submariner or + Cilium cluster mesh. + +## Prerequisites + +In this integration guide, we will be using `kubectl bind dev` command to provision two kind +clusters. More details on the command you can find [here](../../developers/dev-environments.md). + +* **Provider Cluster:** Runs kro, Envoy Gateway, and the kube-bind backend. +* **Consumer Cluster:** Runs the kube-bind konnector. + +## Setup On The Provider Cluster + +The following sections will guide you through the one-time setup that is required for providing +LoadBalancer as a Service using kro and kube-bind. + +### Install Envoy Gateway + +This component will handle the actual traffic routing. + +```bash +helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.6.1 -n envoy-gateway-system --create-namespace +``` + +Install GatewayClass to be managed by Envoy Gateway. + +```yaml +kubectl apply -f - < 18000/TCP,18001/TCP,18002/TCP,19001/TCP,9443/TCP 4d23h +envoy-kube-bind-wz2g5-default-my-lb-gw-9f962ab2 LoadBalancer 10.96.231.200 80:32515/TCP 4d19h +``` + +Port forward the related service. + +```bash +kubectl -n envoy-gateway-system port-forward service/envoy-kube-bind-wz2g5-default-my-lb-gw-9f962ab2 8888:80 +``` + +Send the request through the gateway service to your backend application. + +```bash +curl --verbose --header "Host: www.example.com" http://localhost:8888/headers +``` +```text +* Host localhost:8888 was resolved. +* IPv6: ::1 +* IPv4: 127.0.0.1 +* Trying [::1]:8888... +* Connected to localhost (::1) port 8888 +> GET /headers HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.7.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 200 OK +< content-type: application/json +< x-content-type-options: nosniff +< date: Fri, 19 Dec 2025 19:50:35 GMT +< content-length: 521 +< x-response-message: hello-kube-bind +< +{ + "path": "/headers", + "host": "www.example.com", + "method": "GET", + "proto": "HTTP/1.1", + "headers": { + "Accept": [ + "*/*" + ], + "User-Agent": [ + "curl/8.7.1" + ], + "X-Custom-Message": [ + "hello-kube-bind" + ], + "X-Envoy-External-Address": [ + "172.18.0.2" + ], + "X-Forwarded-For": [ + "172.18.0.2" + ], + "X-Forwarded-Proto": [ + "http" + ], + "X-Request-Id": [ + "8c23f131-a328-485f-b7e1-2e6b20362af1" + ] + }, + "namespace": "default", + "ingress": "", + "service": "", + "pod": "backend-77d4d5968-glxtp" +} +* Connection #0 to host localhost left intact +```