Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Multi-zone deployment
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Non-mesh traffic
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Understanding TargetRef policies
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshAccessLog (Beta)
    • MeshCircuitBreaker (Beta)
    • MeshFaultInjection (Beta)
    • MeshHealthCheck (Beta)
    • MeshHTTPRoute (Beta)
    • MeshProxyPatch (Beta)
    • MeshRateLimit (Beta)
    • MeshRetry (Beta)
    • MeshTimeout (Beta)
    • MeshTrace (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference
    • Open source License
    • Contribute to Mesh

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Installation
  • Usage
  • TLS termination
  • Customization
  • Multi-mesh
  • Cross-mesh
  • Multi-zone
  • How it works
Kong Mesh
2.1.x (latest)
  • Home
  • Kong Mesh
  • Explore
  • Kubernetes Gateway API

Kubernetes Gateway API

Kong Mesh supports configuring built-in gateway using Kubernetes Gateway API.

Installation

Kubernetes Gateway API is still beta, therefore Kong Mesh’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.

    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.

    Standard install
    Custom install

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

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

    echo "apiVersion: gateway.networking.k8s.io/v1beta1
     kind: GatewayClass
     metadata:
       name: kuma
     spec:
       controllerName: gateways.kuma.io/controller
     " | kubectl apply -f -
     
     echo "apiVersion: gateway.networking.k8s.io/v1beta1
     kind: Gateway
     metadata:
       name: kuma
       namespace: kuma-demo
     spec:
       gatewayClassName: kuma
       listeners:
       - name: proxy
         port: 8080
         protocol: HTTP
     " | kubectl apply -f -
    

    When a user applies a Gateway resource, Kong Mesh automatically creates a Deployment of built-in gateways 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      10.43.223.223   <none>        6379/TCP         3m27s
     demo-app     ClusterIP      10.43.216.203   <none>        5000/TCP         3m27s
     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.

  1. Add an HTTPRoute.

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

    echo "apiVersion: gateway.networking.k8s.io/v1beta1
    kind: HTTPRoute
    metadata:
      name: echo
      namespace: kuma-demo
    spec:
      parentRefs:
      - group: gateway.networking.k8s.io
        kind: Gateway
        name: kuma
        namespace: kuma-demo
      rules:
      - backendRefs:
        - group: ''
          kind: Service
          name: demo-app
          port: 5000
          weight: 1
        matches:
        - path:
            type: PathPrefix
            value: /
    " | kubectl apply -f -
    

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

    curl 172.20.0.3:8080/ -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
    
    <html>
    <head>
    ...
    

TLS termination

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

Here is an example

apiVersion: v1
kind: Secret
metadata:
  name: secret-tls
  namespace: kuma-demo
type: kubernetes.io/tls
data:
  tls.crt: "MIIEOzCCAyO..." # redacted
  tls.key: "MIIEowIBAAKC..." # redacted
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: kuma
  namespace: kuma-demo
spec:
  gatewayClassName: kuma
  listeners:
    - name: proxy
      port: 8080
      hostname: test.kuma.io
      protocol: HTTPS
      tls:
        certificateRefs:
          - name: secret-tls

Under the hood, Kong Mesh CP copies the Secret to kong-mesh-system namespace and converts it to Kong Mesh 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 Kong Mesh, you can refer to a MeshGatewayConfig resource:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: kuma
spec:
  controllerName: gateways.kuma.io/controller
  parametersRef:
    kind: MeshGatewayConfig
    group: kuma.io
    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:

---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: kuma-cross-mesh
spec:
  controllerName: gateways.kuma.io/controller
  parametersRef:
    group: kuma.io
    kind: MeshGatewayConfig
    name: default-cross-mesh
---
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayConfig
metadata:
  name: default-cross-mesh
spec:
  crossMesh: true

and then reference it in your Gateway:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: kuma
  namespace: default
spec:
  gatewayClassName: kuma-cross-mesh

Multi-zone

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

How it works

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

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

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023