Configure a built-in gateway

The built-in gateway is configured using a combination of MeshGateway, MeshHTTPRoute and MeshTCPRoute, and served by Envoy instances represented by Dataplanes configured as built-in gateways. Kuma policies are then used to configure built-in gateways.

New to Kuma? Checkout our guide to get quickly started with builtin gateways!

Deploying gateways

The process for deploying built-in gateways is different depending on whether you’re running in Kubernetes or Universal mode.

For managing gateway instances on Kubernetes, Kuma provides a MeshGatewayInstance CRD.

This resource launches kuma-dp in your cluster. If you are running a multi-zone Kuma, MeshGatewayInstance needs to be created in a specific zone, not the global cluster. See the dedicated section for using built-in gateways on multi-zone.

This resource manages a Kubernetes Deployment and Service suitable for providing service capacity for the MeshGateway with the matching kuma.io/service tag.

The kuma.io/service value you select will be used in MeshGateway to configure listeners.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGatewayInstance
  3. metadata:
  4.   name: edge-gateway
  5.   namespace: default
  6. spec:
  7.   replicas: 1
  8.   serviceType: LoadBalancer
  9.   tags:
  10.     kuma.io/service: edge-gateway

See the MeshGatewayInstance docs for more options.

You’ll need to create a Dataplane object for your gateway:

  1. type: Dataplane
  2. mesh: default
  3. name: gateway-instance-1
  4. networking:
  5.   address: 127.0.0.1
  6.   gateway:
  7.     type: BUILTIN
  8.     tags:
  9.       kuma.io/service: edge-gateway

Note that this gateway has an identifying kuma.io/service tag.

Now you need to explicitly run kuma-dp:

  1. kuma-dp run \
  2.   --cp-address=https://localhost:5678/ \
  3.   --dns-enabled=false \
  4.   --dataplane-token-file=kuma-token-gateway \ # this needs to be generated like for regular Dataplane
  5.   --dataplane-file=my-gateway.yaml # the Dataplane resource described above

Using MeshGatewayInstance is highly recommended. If for any reason you are unable to use MeshGatewayInstance to deploy builtin gateways, you can manually create a Deployment and Service to manage kuma-dp instances and forward traffic to them. Keep in mind however, that you’ll need to keep the listeners of your MeshGateway in sync with your Service.

These instructions will use the resources created by MeshGatewayInstance with version 2.6.2 as a guide but remember to create a MeshGatewayInstance for your version to configure as much as you can and use it as a basis for these self-managed resources.

Given a MeshGateway spec:

  1. spec:
  2.   conf:
  3.     listeners:
  4.     - port: 80
  5.       protocol: HTTP
  6.   selectors:
  7.   - match:
  8.       kuma.io/service: demo-app_gateway

Service

The Service will forward traffic to the kuma-dp we’ll configure in the next section. Its ports need to be in sync with the MeshGateway listeners.

  1. metadata:
  2.   annotations:
  3.     kuma.io/gateway: builtin
  4.   name: demo-app-gateway
  5.   namespace: kuma-demo
  6. spec:
  7.   ports:
  8.   - name: "80"
  9.     port: 80
  10.     protocol: TCP
  11.     targetPort: 80
  12.   selector:
  13.     app: demo-app-gateway

The selector should match the Pod template created in the next section.

Deployment

The Deployment we’ll create will manage running some number of kuma-dp instances that are configured to serve traffic for your MeshGateway.

We’ll cover just spec.selector and spec.template here because other parts of the Deployment can be configured arbitrarily. Most importantly you’ll need to change:

  • kuma.io/tags annotation - must match the MeshGateway selectors
  • KUMA_CONTROL_PLANE_CA_CERT environment variable - can be retrieved with kubectl get secret kuma-tls-cert -n kuma-system -o=jsonpath='{.data.ca\.crt}' | base64 -d
  • containers[0].image field - should be the version of Kuma you’re using

Make sure containers[0].resources is appropriate for your use case.

  1.   selector:
  2.     matchLabels:
  3.       app: demo-app-gateway
  4.   template:
  5.     metadata:
  6.       annotations:
  7.         kuma.io/gateway: builtin
  8.         kuma.io/mesh: default
  9.         kuma.io/tags: '{"kuma.io/service":"demo-app_gateway"}'
  10.       creationTimestamp: null
  11.       labels:
  12.         app: demo-app-gateway
  13.         kuma.io/sidecar-injection: disabled
  14.     spec:
  15.       containers:
  16.       - args:
  17.         - run
  18.         - --log-level=info
  19.         - --concurrency=2
  20.         env:
  21.         - name: INSTANCE_IP
  22.           valueFrom:
  23.             fieldRef:
  24.               apiVersion: v1
  25.               fieldPath: status.podIP
  26.         - name: KUMA_CONTROL_PLANE_CA_CERT
  27.           value: |
  28.             -----BEGIN CERTIFICATE-----
  29.             MIIDDzCCAfegAwIBAgIQJlMQnmK1ZfnjhDt1KvTvQTANBgkqhkiG9w0BAQsFADAS
  30.             MRAwDgYDVQQDEwdrdW1hLWNhMB4XDTI0MDQxNTEyMzkxNFoXDTM0MDQxMzEyMzkx
  31.             NFowEjEQMA4GA1UEAxMHa3VtYS1jYTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
  32.             AQoCggEBALp6skN+nPPRQQ7Z2ZH4eDjcTtKnO/9n/ExM99tRuMgZCdaZe7zp5g6L
  33.             1wvdgi3mtOlplplFaYvLlC9QPn6A7TQSCOPd28vhTIqoUhZ4V7yjr54h0bn6wmH+
  34.             BdVXgnalXDb+mQtyDF4dvAY3f0QyOQAK3TjRp32OX+dYKsGGWtch1yiIPf7VnWPx
  35.             4/K2v4DTjRuDcXg6S0x4GskGZ9zAhR1WJYEa/2uM+XBmy0GmF9INn0WOeje7Jf3c
  36.             G5tCd+fPP6qEk5Q+tBVHd7Pz3xfD9TZjIfY1+h00UkpC50n/yE5FDK8aUpR17SUc
  37.             QKJUskOivKAqRD1pI9zfhnHBJ2URfbcCAwEAAaNhMF8wDgYDVR0PAQH/BAQDAgKk
  38.             MB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAPBgNVHRMBAf8EBTADAQH/
  39.             MB0GA1UdDgQWBBQRT2hdjPpIt/FzcLJo/EWPFafCQzANBgkqhkiG9w0BAQsFAAOC
  40.             AQEAO0Gfe750KCk+gMtBQHfHzEyQocO2qg2JXfZrBP/+rqeozbjXQj0BLYR9NXnp
  41.             tLrxJHoBHdeE+TOnTFsxB7IRIkF1njEElKX4DVx7MjZCL1qLeWDuaXQmEgtFoWDM
  42.             o4NqPZ4BIyuZZ9IVtYdeod5g5ucRopOP66zWr/RuwKFzdzni79BGaWuA3dNmLWcn
  43.             MdsbZ165hdXstF6b48yPFKFrOdGgLpJheSCLlR/6vp5a+pA03fQZ6qV2j2uSqvAm
  44.             XYl8Q3CdoI/yAX9p4mxkcYK7xaz0fQTrD/UyGD6l2cXgY90NP6LDAW1oYKHSD7Qc
  45.             Y8vutIcexOtJfAdTZ3/GxBxH1Q==
  46.             -----END CERTIFICATE-----
  47.         - name: KUMA_CONTROL_PLANE_URL
  48.           value: https://kuma-control-plane.kuma-system:5678
  49.         - name: KUMA_DATAPLANE_DRAIN_TIME
  50.           value: 30s
  51.         - name: KUMA_DATAPLANE_MESH
  52.           value: default
  53.         - name: KUMA_DATAPLANE_RUNTIME_TOKEN_PATH
  54.           value: /var/run/secrets/kubernetes.io/serviceaccount/token
  55.         - name: KUMA_DNS_CORE_DNS_BINARY_PATH
  56.           value: coredns
  57.         - name: KUMA_DNS_CORE_DNS_EMPTY_PORT
  58.           value: "15054"
  59.         - name: KUMA_DNS_CORE_DNS_PORT
  60.           value: "15053"
  61.         - name: KUMA_DNS_ENABLED
  62.           value: "true"
  63.         - name: KUMA_DNS_ENABLE_LOGGING
  64.           value: "false"
  65.         - name: KUMA_DNS_ENVOY_DNS_PORT
  66.           value: "15055"
  67.         - name: POD_NAME
  68.           valueFrom:
  69.             fieldRef:
  70.               apiVersion: v1
  71.               fieldPath: metadata.name
  72.         - name: POD_NAMESPACE
  73.           valueFrom:
  74.             fieldRef:
  75.               apiVersion: v1
  76.               fieldPath: metadata.namespace
  77.         - name: KUMA_DATAPLANE_RESOURCES_MAX_MEMORY_BYTES
  78.           valueFrom:
  79.             resourceFieldRef:
  80.               containerName: kuma-gateway
  81.               divisor: "0"
  82.               resource: limits.memory
  83.         image: docker.io/kumahq/kuma-dp:2.6.2
  84.         livenessProbe:
  85.           failureThreshold: 12
  86.           httpGet:
  87.             path: /ready
  88.             port: 9901
  89.             scheme: HTTP
  90.           initialDelaySeconds: 60
  91.           periodSeconds: 5
  92.           successThreshold: 1
  93.           timeoutSeconds: 3
  94.         name: kuma-gateway
  95.         readinessProbe:
  96.           failureThreshold: 12
  97.           httpGet:
  98.             path: /ready
  99.             port: 9901
  100.             scheme: HTTP
  101.           initialDelaySeconds: 1
  102.           periodSeconds: 5
  103.           successThreshold: 1
  104.           timeoutSeconds: 3
  105.         resources:
  106.           limits:
  107.             cpu: "1"
  108.             ephemeral-storage: 1G
  109.             memory: 512Mi
  110.           requests:
  111.             cpu: 50m
  112.             ephemeral-storage: 50M
  113.             memory: 64Mi
  114.         securityContext:
  115.           allowPrivilegeEscalation: false
  116.           runAsGroup: 5678
  117.           runAsUser: 5678
  118.         volumeMounts:
  119.         - mountPath: /tmp
  120.           name: tmp
  121.       securityContext:
  122.         sysctls:
  123.         - name: net.ipv4.ip_unprivileged_port_start
  124.           value: "0"
  125.       volumes:
  126.       - emptyDir: {}
  127.         name: tmp

Kuma gateways are configured with the Envoy best practices for edge proxies.

Multi-zone

The Kuma Gateway resource types, MeshGateway, MeshHTTPRoute and MeshTCPRoute, are synced across zones by the Kuma control plane. If you have a multi-zone deployment, follow existing Kuma practice and create any Kuma Gateway resources in the global control plane. Once these resources exist, you can provision serving capacity in the zones where it is needed by deploying built-in gateway Dataplanes (in Universal zones) or MeshGatewayInstances (Kubernetes zones).

See the multi-zone docs for a refresher.