Kubernetes Gateway API

Kuma supports configuring built-in gateway using Kubernetes Gateway API.

Installation

Kubernetes Gateway API is still beta, therefore Kuma’s integration provides the same level of stability.

Gateway API is not supported in multi-zone. To use the builtin Gateway, you need to use the MeshGateway resources.

  1. Install the Gateway API CRDs.

    The Gateway API CRDs aren’t available in Kubernetes by default yet. You must first install the experimental release that includes those CRDs as well as the admission webhook.

  2. Enable Gateway API support.

    • With kumactl, use the --experimental-gatewayapi flag.
    • With Helm, use the experimental.gatewayAPI=true value.

Usage

  1. Install the counter demo.

    1. kumactl install demo | kubectl apply -f -

  2. Add a Gateway.

    The Gateway resource represents the proxy instance that handles traffic for a set of Gateway API routes.

    Every Gateway refers to a GatewayClass by name.

    For Helm and kumactl installations, a GatewayClass named kuma is automatically installed if the Gateway API CRDs are present.

    If you’ve installed Kuma some other way, you can create your own GatewayClass using the controllerName: gateways.kuma.io/controller:

    1. echo "apiVersion: gateway.networking.k8s.io/v1beta1
    2. kind: GatewayClass
    3. metadata:
    4.   name: kuma
    5. spec:
    6.   controllerName: gateways.kuma.io/controller
    7. " | kubectl apply -f -
    1. echo "apiVersion: gateway.networking.k8s.io/v1beta1
    2. kind: Gateway
    3. metadata:
    4.   name: kuma
    5.   namespace: kuma-demo
    6. spec:
    7.   gatewayClassName: kuma
    8.   listeners:
    9.   - name: proxy
    10.     port: 8080
    11.     protocol: HTTP
    12. " | kubectl apply -f -

    When a user applies a Gateway resource, Kuma automatically creates a Deployment of built-in gateways with a corresponding Service.

    1. kubectl get pods -n kuma-demo
    2. NAME                          READY   STATUS    RESTARTS   AGE
    3. redis-59c9d56fc-6gcbc         2/2     Running   0          2m8s
    4. demo-app-5845d6447b-v7npw     2/2     Running   0          2m8s
    5. kuma-4j6wr-58998b5576-25wl6   1/1     Running   0          30s
    7. kubectl get svc -n kuma-demo
    8. NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
    9. redis        ClusterIP      10.43.223.223   <none>        6379/TCP         3m27s
    10. demo-app     ClusterIP      10.43.216.203   <none>        5000/TCP         3m27s
    11. kuma-pfh4s   LoadBalancer   10.43.122.93    172.20.0.3    8080:30627/TCP   87s

    The Gateway is now accessible using the external address 172.20.0.3:8080.

  3. Add an HTTPRoute.

    HTTPRoute resources contain a set of matching criteria for HTTP requests and upstream Services to route those requests to.

    1. echo "apiVersion: gateway.networking.k8s.io/v1beta1
    2. kind: HTTPRoute
    3. metadata:
    4.   name: echo
    5.   namespace: kuma-demo
    6. spec:
    7.   parentRefs:
    8.   - group: gateway.networking.k8s.io
    9.     kind: Gateway
    10.     name: kuma
    11.     namespace: kuma-demo
    12.   rules:
    13.   - backendRefs:
    14.     - group: ''
    15.       kind: Service
    16.       name: demo-app
    17.       port: 5000
    18.       weight: 1
    19.     matches:
    20.     - path:
    21.         type: PathPrefix
    22.         value: /
    23. " | kubectl apply -f -

    After creating an HTTPRoute, accessing / forwards a request to the demo app:

    1. curl 172.20.0.3:8080/ -i
    1. HTTP/1.1 200 OK
    2. x-powered-by: Express
    3. accept-ranges: bytes
    4. cache-control: public, max-age=0
    5. last-modified: Tue, 20 Oct 2020 17:16:41 GMT
    6. etag: W/"2b91-175470350a8"
    7. content-type: text/html; charset=UTF-8
    8. content-length: 11153
    9. date: Fri, 18 Mar 2022 11:33:29 GMT
    10. x-envoy-upstream-service-time: 2
    11. server: Kuma Gateway
    13. <html>
    14. <head>
    15. ...

TLS termination

Gateway API supports TLS termination by using standard kubernetes.io/tls Secrets.

Here is an example

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: secret-tls
  5.   namespace: kuma-demo
  6. type: kubernetes.io/tls
  7. data:
  8.   tls.crt: "MIIEOzCCAyO..." # redacted
  9.   tls.key: "MIIEowIBAAKC..." # redacted
  1. apiVersion: gateway.networking.k8s.io/v1beta1
  2. kind: Gateway
  3. metadata:
  4.   name: kuma
  5.   namespace: kuma-demo
  6. spec:
  7.   gatewayClassName: kuma
  8.   listeners:
  9.     - name: proxy
  10.       port: 8080
  11.       hostname: test.kuma.io
  12.       protocol: HTTPS
  13.       tls:
  14.         certificateRefs:
  15.           - name: secret-tls

Under the hood, Kuma CP copies the Secret to kuma-system namespace and converts it to Kuma secret. It tracks all the changes to the secret and deletes it upon deletion of the original secret.

Customization

Gateway API provides the parametersRef field on GatewayClass.spec to provide additional, implementation-specific configuration to Gateways. When using Gateway API with Kuma, you can refer to a MeshGatewayConfig resource:

  1. apiVersion: gateway.networking.k8s.io/v1beta1
  2. kind: GatewayClass
  3. metadata:
  4.   name: kuma
  5. spec:
  6.   controllerName: gateways.kuma.io/controller
  7.   parametersRef:
  8.     kind: MeshGatewayConfig
  9.     group: kuma.io
  10.     name: kuma

This resource has the same structure as the MeshGatewayInstance resource except that the tags field is optional. With a MeshGatewayConfig you can then customize the generated Service and Deployment resources.

Multi-mesh

You can specify a Mesh for Gateway and HTTPRoute resources by setting the kuma.io/mesh annotation Note that HTTPRoutes must also have the annotation to reference a Gateway from a non-default Mesh.

Cross-mesh

Cross-mesh gateways are supported with Gateway API. You’ll just need to create a corresponding GatewayClass pointing to a MeshGatewayConfig that sets crossMesh: true:

  1. ---
  2. apiVersion: gateway.networking.k8s.io/v1beta1
  3. kind: GatewayClass
  4. metadata:
  5.   name: kuma-cross-mesh
  6. spec:
  7.   controllerName: gateways.kuma.io/controller
  8.   parametersRef:
  9.     group: kuma.io
  10.     kind: MeshGatewayConfig
  11.     name: default-cross-mesh
  12. ---
  13. apiVersion: kuma.io/v1alpha1
  14. kind: MeshGatewayConfig
  15. metadata:
  16.   name: default-cross-mesh
  17. spec:
  18.   crossMesh: true

and then reference it in your Gateway:

  1. apiVersion: gateway.networking.k8s.io/v1beta1
  2. kind: Gateway
  3. metadata:
  4.   name: kuma
  5.   namespace: default
  6. spec:
  7.   gatewayClassName: kuma-cross-mesh

Multi-zone

Gateway API isn’t supported with multi-zone deployments, use Kuma’s MeshGateways/MeshGatewayRoutes instead.

How it works

Kuma includes controllers that reconcile Gateway API CRDs and convert them into the corresponding Kuma gateway CRDs. This is why in the GUI, Kuma MeshGateways/MeshGatewayRoutes are visible and not Kubernetes Gateway API resources.

Kubernetes Gateway API resources serve as the source of truth for Kuma gateways and any edits to Kuma gateway resources are overwritten.