Running built-in gateway pods on Kubernetes

MeshGatewayInstance is a Kubernetes-only resource for deploying Kuma’s builtin gateway.

MeshGateway and MeshHTTPRoute/MeshTCPRoute allow specifying builtin gateway listener and route configuration but don’t handle deploying kuma-dp instances that listen and serve traffic.

Kuma offers MeshGatewayInstance to manage a Kubernetes Deployment and Service that together provide service capacity for the MeshGateway.

Heads up! In previous versions of Kuma, setting the kuma.io/service tag directly within a MeshGatewayInstance resource was used to identify the service. However, this practice is deprecated and no longer recommended for security reasons since Kuma version 2.7.0.

We’ve automatically switched to generating the service name for you based on your MeshGatewayInstance resource name and namespace (format: {name}_{namespace}_svc).

If you’re not using the default Mesh, you’ll need to label the MeshGatewayInstance using kuma.io/mesh.

Consider the following example:

apiVersion: kuma.io/v1alpha1
kind: MeshGatewayInstance
metadata:
  name: edge-gateway
  namespace: default
  labels:
    kuma.io/mesh: default # only necessary if not using default Mesh
spec:
  replicas: 2
  serviceType: LoadBalancer

Once a MeshGateway exists with kuma.io/service: edge-gateway_default_svc, the control plane creates a new Deployment in the default namespace. This Deployment deploys 2 replicas of kuma-dp and corresponding builtin gateway Dataplane running with kuma.io/service: edge-gateway_default_svc.

The control plane also creates a new Service to send network traffic to the builtin Dataplane pods. The Service is of type LoadBalancer, and its ports are automatically adjusted to match the listeners on the corresponding MeshGateway.

Customization

Additional customization of the generated Service or Pods is possible via spec.serviceTemplate and spec.podTemplate.

For example, you can add annotations and/or labels to the generated objects:

apiVersion: kuma.io/v1alpha1
kind: MeshGatewayInstance
metadata:
  name: edge-gateway
  namespace: default
spec:
  replicas: 1
  serviceType: LoadBalancer
  serviceTemplate:
    metadata:
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-internal: "true"
  podTemplate:
    metadata:
      labels:
        app-name: my-app

You can also modify several resource limits or security-related parameters for the generated Pods or specify a loadBalancerIP for the Service:

apiVersion: kuma.io/v1alpha1
kind: MeshGatewayInstance
metadata:
  name: edge-gateway
  namespace: default
spec:
  replicas: 1
  serviceType: LoadBalancer
  resources:
    requests:
      memory: 64Mi
      cpu: 250m
    limits:
      memory: 128Mi
      cpu: 500m
  serviceTemplate:
    metadata:
      labels:
        svc-id: "19-001"
    spec:
      loadBalancerIP: 172.17.0.1
  podTemplate:
    metadata:
      annotations:
        app-monitor: "false"
    spec:
      serviceAccountName: my-sa
      securityContext:
        fsGroup: 2000
      container:
        securityContext:
          readOnlyRootFilesystem: true

Schema