Kuma Star

Careful!

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

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

MeshGatewayInstance represents a managed instance of a dataplane proxy for a KumaGateway.

Type: object

Properties

  • apiVersion

    • APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
    • Type: string

  • kind

    • Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
    • Type: string

  • metadata

    • Type: object
    • Properties

  • spec

    • MeshGatewayInstanceSpec specifies the options available for a GatewayDataplane.

    • Type: object

    • Properties

      • podTemplate

        • PodTemplate configures the Pod owned by this config.
        • Type: object
        • Properties
          • metadata
            • Metadata holds metadata configuration for a Service.
            • Type: object
            • Properties
              • annotations
                • Annotations holds annotations to be set on an object.
                • Type: object
                • This schema accepts additional properties.
                • Properties
              • labels
                • Labels holds labels to be set on an objects.
                • Type: object
                • This schema accepts additional properties.
                • Properties
          • spec
            • Spec holds some customizable fields of a Pod.
            • Type: object
            • Properties
              • container
                • Container corresponds to PodSpec.Container
                • Type: object
                • Properties
                  • securityContext
                    • ContainerSecurityContext corresponds to PodSpec.Container.SecurityContext
                    • Type: object
                    • Properties
                      • readOnlyRootFilesystem
                        • ReadOnlyRootFilesystem corresponds to PodSpec.Container.SecurityContext.ReadOnlyRootFilesystem
                        • Type: boolean
              • securityContext
                • PodSecurityContext corresponds to PodSpec.SecurityContext
                • Type: object
                • Properties
                  • fsGroup
                    • FSGroup corresponds to PodSpec.SecurityContext.FSGroup
                    • Type: integer
              • serviceAccountName
                • ServiceAccountName corresponds to PodSpec.ServiceAccountName.
                • Type: string

      • replicas

        • Replicas is the number of dataplane proxy replicas to create. Fornow this is a fixed number, but in the future it could beautomatically scaled based on metrics.
        • Type: integer
        • Default: 1
        • Range: ≥ 1

      • resources

        • Resources specifies the compute resources for the proxy container.The default can be set in the control plane config.
        • Type: object
        • Properties
          • claims
            • Claims lists the names of resources, defined in spec.resourceClaims,that are used by this container.This is an alpha field and requires enabling theDynamicResourceAllocation feature gate.This field is immutable. It can only be set for containers.
            • Type: array
              • Items
              • ResourceClaim references one entry in PodSpec.ResourceClaims.
              • Type: object
              • Properties
                • name required
                  • Name must match the name of one entry in pod.spec.resourceClaims ofthe Pod where this field is used. It makes that resource availableinside a container.
                  • Type: string
                • request
                  • Request is the name chosen for a request in the referenced claim.If empty, everything from the claim is made available, otherwiseonly the result of this request.
                  • Type: string
          • limits
            • Limits describes the maximum amount of compute resources allowed.More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
            • Type: object
            • This schema accepts additional properties.
            • Properties
          • requests
            • Requests describes the minimum amount of compute resources required.If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,otherwise to an implementation-defined value. Requests cannot exceed Limits.More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
            • Type: object
            • This schema accepts additional properties.
            • Properties

      • serviceTemplate

        • ServiceTemplate configures the Service owned by this config.
        • Type: object
        • Properties
          • metadata
            • Metadata holds metadata configuration for a Service.
            • Type: object
            • Properties
              • annotations
                • Annotations holds annotations to be set on an object.
                • Type: object
                • This schema accepts additional properties.
                • Properties
              • labels
                • Labels holds labels to be set on an objects.
                • Type: object
                • This schema accepts additional properties.
                • Properties
          • spec
            • Spec holds some customizable fields of a Service.
            • Type: object
            • Properties
              • loadBalancerIP
                • LoadBalancerIP corresponds to ServiceSpec.LoadBalancerIP.
                • Type: string

      • serviceType

        • ServiceType specifies the type of managed Service that will becreated to expose the dataplane proxies to traffic from outsidethe cluster. The ports to expose will be taken from the matching Gatewayresource. If there is no matching Gateway, the managed Service willbe deleted.
        • Type: string
        • The value is restricted to the following:
          1. "LoadBalancer"
          2. "ClusterIP"
          3. "NodePort"
        • Default: "LoadBalancer"

      • tags

        • Tags specifies the Kuma tags that are propagated to the manageddataplane proxies. These tags should not include kuma.io/service tagsince is auto-generated, and should match exactly one Gatewayresource.
        • Type: object
        • This schema accepts additional properties.
        • Properties

  • status

    • MeshGatewayInstanceStatus holds information about the status of the gatewayinstance.

    • Type: object

    • Properties

      • conditions

        • Conditions is an array of gateway instance conditions.

        • Type: array

          • Items

          • Condition contains details for one aspect of the current state of this API Resource.

          • Type: object

          • Properties

            • lastTransitionTime required

              • lastTransitionTime is the last time the condition transitioned from one status to another.This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
              • Type: string
              • String format must be a "date-time"

            • message required

              • message is a human readable message indicating details about the transition.This may be an empty string.
              • Type: string
              • Length: ≤ 32768

            • observedGeneration

              • observedGeneration represents the .metadata.generation that the condition was set based upon.For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of datewith respect to the current state of the instance.
              • Type: integer
              • Range: ≥ 0

            • reason required

              • reason contains a programmatic identifier indicating the reason for the condition's last transition.Producers of specific condition types may define expected values and meanings for this field,and whether the values are considered a guaranteed API.The value should be a CamelCase string.This field may not be empty.
              • Type: string
              • The value must match this pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
              • Length: between 1 and 1024

            • status required

              • status of the condition, one of True, False, Unknown.
              • Type: string
              • The value is restricted to the following:
                1. "True"
                2. "False"
                3. "Unknown"

            • type required

              • type of condition in CamelCase or in foo.example.com/CamelCase.
              • Type: string
              • The value must match this pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
              • Length: ≤ 316

      • loadBalancer

        • LoadBalancer contains the current status of the load-balancer,if one is present.

        • Type: object

        • Properties

          • ingress

            • Ingress is a list containing ingress points for the load-balancer.Traffic intended for the service should be sent to these ingress points.

            • Type: array

              • Items

              • LoadBalancerIngress represents the status of a load-balancer ingress point:traffic intended for the service should be sent to an ingress point.

              • Type: object

              • Properties

                • hostname

                  • Hostname is set for load-balancer ingress points that are DNS based(typically AWS load-balancers)
                  • Type: string

                • ip

                  • IP is set for load-balancer ingress points that are IP based(typically GCE or OpenStack load-balancers)
                  • Type: string

                • ipMode

                  • IPMode specifies how the load-balancer IP behaves, and may only be specified when the ip field is specified.Setting this to "VIP" indicates that traffic is delivered to the node withthe destination set to the load-balancer's IP and port.Setting this to "Proxy" indicates that traffic is delivered to the node or pod withthe destination set to the node's IP and node port or the pod's IP and port.Service implementations may use this information to adjust traffic routing.
                  • Type: string

                • ports

                  • Ports is a list of records of service portsIf used, every port defined in the service should have an entry in it

                  • Type: array

                    • Items

                    • Type: object

                    • Properties

                      • error required

                        • Error is to record the problem with the service portThe format of the error shall comply with the following rules:- built-in error values shall be specified in this file and those shall use CamelCase names- cloud provider specific error values must have names that comply with the format foo.example.com/CamelCase.
                        • Type: string
                        • The value must match this pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
                        • Length: ≤ 316

                      • port required

                        • Port is the port number of the service port of which status is recorded here
                        • Type: integer

                      • protocol required

                        • Protocol is the protocol of the service port of which status is recorded hereThe supported values are: "TCP", "UDP", "SCTP"
                        • Type: string

Generated with json-schema-md-doc Tue Apr 01 2025 21:26:05 GMT+0000 (Coordinated Universal Time)