You are browsing documentation for a version of Kuma that is not the latest release.

Looking for even older versions? Learn more.

Kubernetes Gateway API

Kuma supports configuring Built-in Gateway using Kubernetes Gateway API.


Gateway API support is an experimental feature that has to be explicitly enabled.

  1. Install Gateway API CRDs

    The Gateway API CRDs are not yet available by default in Kubernetes. You must first install them.

  2. Enable Built-in Gateway and Gateway API support

    Gateway API can only be used when Kuma built-in Gateway is enabled.

    When Kuma is installed with kumactl, use --experimental-meshgateway and --experimental-gatewayapi.

    When Kuma is installed with HELM, use experimental.meshGateway=true value and experimental.gatewayAPI=true.


  1. Setup counter demo application

    kumactl install demo | kubectl apply -f -
  2. Add GatewayClass and Gateway

    The Gateway resource represents the proxy instance that handles traffic for a set of Gateway API routes, and a GatewayClass describes characteristics shared by all Gateways of a given type.

    echo "apiVersion:
    kind: GatewayClass
      name: kuma
    " | kubectl apply -f -
    echo "apiVersion:
    kind: Gateway
      name: kuma
      namespace: kuma-demo
      gatewayClassName: kuma
      - name: proxy
        port: 8080
        protocol: HTTP
    " | kubectl apply -f -

    When Gateway resource is applied, Kuma automatically creates an instance of a built-in Gateway with a corresponding Service.

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

    Gateway can now be accessed using address.

  3. Add an HTTPRoute

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

    echo "apiVersion:
    kind: HTTPRoute
      name: echo
      namespace: kuma-demo
      - group:
        kind: Gateway
        name: kuma
        namespace: kuma-demo
      - backendRefs:
        - group: ''
          kind: Service
          name: demo-app
          port: 5000
          weight: 1
        - path:
            type: PathPrefix
            value: /
    " | kubectl apply -f -

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

    curl -i
    HTTP/1.1 200 OK
    x-powered-by: Express
    accept-ranges: bytes
    cache-control: public, max-age=0
    last-modified: Tue, 20 Oct 2020 17:16:41 GMT
    etag: W/"2b91-175470350a8"
    content-type: text/html; charset=UTF-8
    content-length: 11153
    date: Fri, 18 Mar 2022 11:33:29 GMT
    x-envoy-upstream-service-time: 2
    server: Kuma Gateway

TLS Termination

Gateway API supports TLS termination by using standard Secrets.

Here is an example

apiVersion: v1
kind: Secret
  name: secret-tls
  namespace: kuma-demo
  tls.crt: "MIIEOzCCAyO..." # redacted
  tls.key: "MIIEowIBAAKC..." # redacted
kind: Gateway
  name: kuma
  namespace: kuma-demo
  gatewayClassName: kuma
  - name: proxy
    port: 8080
    protocol: HTTPS
      - 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 if the original secret is deleted.


Gateway API is not supported with multizone deployments, use Mesh Gateway CRDs instead.

How does it work

When the feature is enabled, Kubernetes Gateway API CRDs are automatically converted to Kuma Mesh Gateway CRDs. This is the reason why in the GUI we will see Kuma Mesh Gateway and not Kubernetes Gateway API resources.

When using Kubernetes Gateway API CRDs, it is a source of truth, so do not edit Kuma Mesh Gateway CRDs directly.

Last Updated: 1/16/2023, 13:14:43 PM