Kuma Star

Careful!

You are browsing documentation for the next version of Kuma. Use this version at your own risk.

MeshService

MeshService represents a destination for traffic within the mesh. It defines which data plane proxies serve traffic for a service, exposes ports, and tracks health status. Think of it as the Kuma equivalent of a Kubernetes Service.

Kuma automatically generates MeshService resources:

  • Kubernetes: From Service resources, reusing ClusterIPs and DNS names
  • Universal: From Dataplane inbounds with kuma.io/service tags

For concepts, migration guidance, and usage patterns, see the MeshService guide.

Spec fields

Field Description
selector Defines which data plane proxies belong to this service. Use either dataplaneTags or dataplaneRef.
selector.dataplaneTags Match proxies by tags on their inbounds. All specified tags must match.
selector.dataplaneRef.name Match a specific proxy by name. Used for headless services.
ports List of ports exposed by this service.
ports[].port Service port number (required).
ports[].targetPort Port on the data plane proxy. Can be a number or inbound name. Defaults to port value.
ports[].name Optional port name for referencing in policies via sectionName.
ports[].appProtocol Protocol hint: tcp (default), http, http2, grpc.
identities Service identities (auto-populated). Contains ServiceTag or SpiffeID entries.
state Service availability: Available (healthy endpoints exist) or Unavailable.

Status fields

The status is managed by Kuma and provides runtime information:

Field Description
addresses Generated hostnames from HostnameGenerators.
vips Virtual IP addresses assigned to the service (Kubernetes ClusterIP or Kuma VIP).
tls.status mTLS readiness: Ready or NotReady.
dataplaneProxies.total Total proxies matching this service.
dataplaneProxies.connected Proxies connected to control plane.
dataplaneProxies.healthy Proxies with all inbound ports healthy.
hostnameGenerators Status of hostname generation from each generator.

Examples

Basic MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshService
metadata:
  name: redis
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplaneTags:
      app: redis
      k8s.kuma.io/namespace: kuma-demo
  ports:
    - port: 6379
      targetPort: 6379
      appProtocol: tcp

MeshService with multiple ports

apiVersion: kuma.io/v1alpha1
kind: MeshService
metadata:
  name: backend
  namespace: app
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplaneTags:
      app: backend
      k8s.kuma.io/namespace: app
  ports:
    - name: http
      port: 80
      targetPort: 8080
      appProtocol: http
    - name: grpc
      port: 9000
      targetPort: 9000
      appProtocol: grpc
    - name: metrics
      port: 9090
      targetPort: 9090
      appProtocol: http

MeshService with named targetPort

Reference inbound ports by name instead of number:

apiVersion: kuma.io/v1alpha1
kind: MeshService
metadata:
  name: api
  namespace: app
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplaneTags:
      app: api
      k8s.kuma.io/namespace: app
  ports:
    - name: main
      port: 80
      targetPort: http-port  # references inbound name
      appProtocol: http

MeshService for headless service (single pod)

Use dataplaneRef to target a specific proxy instance:

apiVersion: kuma.io/v1alpha1
kind: MeshService
metadata:
  name: postgres-0
  namespace: database
  labels:
    kuma.io/mesh: default
    k8s.kuma.io/is-headless-service: "true"
spec:
  selector:
    dataplaneRef:
      name: postgres-0  # specific pod name
  ports:
    - port: 5432
      targetPort: 5432
      appProtocol: tcp

MeshService with custom labels

Add labels for policy targeting and organization:

apiVersion: kuma.io/v1alpha1
kind: MeshService
metadata:
  name: payment-service
  namespace: payments
  labels:
    kuma.io/mesh: default
    team: payments
    tier: backend
    pci-compliant: "true"
spec:
  selector:
    dataplaneTags:
      app: payment-service
      k8s.kuma.io/namespace: payments
  ports:
    - port: 443
      targetPort: 8443
      appProtocol: http2

Targeting MeshService in policies

In policy targetRef

Target a specific port using sectionName:

spec:
  to:
    - targetRef:
        kind: MeshService
        name: backend
        namespace: app      # Kubernetes only
        sectionName: http   # port name

In route backendRefs

Direct traffic to a MeshService:

spec:
  to:
    - targetRef:
        kind: MeshService
        name: frontend
        namespace: app
      rules:
        - default:
            backendRefs:
              - kind: MeshService
                name: backend
                namespace: app
                port: 80

Using labels for cross-zone targeting

Select MeshServices across zones:

spec:
  to:
    - targetRef:
        kind: MeshService
        labels:
          kuma.io/display-name: backend
          kuma.io/zone: east

Naming constraints

MeshService names must:

  • Be 63 characters or fewer
  • Conform to DNS-1035 (lowercase alphanumeric, hyphens allowed, cannot start/end with hyphen)

See also

All options

kind string
Kind is a string value representing the REST resource this object represents. Servers may infer this...
spec object
Spec is the specification of the Kuma MeshService resource.
state enum
State of MeshService. Available if there is at least one healthy endpoint. Otherwise, Unavailable. I...
Values: Available | Unavailable
Default: "Unavailable"
name string
port integer required
targetPort any
appProtocol string
Protocol identifies a protocol supported by a service.
Default: "tcp"
name string
dataplaneTags object
type enum required
Values: ServiceTag | SpiffeID
value string required
status object
Status is the current status of the Kuma MeshService resource.
status enum
Values: Ready | NotReady
ip string
origin string
hostname string
coreName string required
Data plane proxies statistics selected by this MeshService.
total integer
Total number of data plane proxies.
healthy integer
Number of data plane proxies with all healthy inbounds selected by this MeshService.
connected integer
Number of data plane proxies connected to the zone control plane
Conditions is an array of hostname generator conditions.
type string required
type of condition in CamelCase or in foo.example.com/CamelCase.
reason string required
reason contains a programmatic identifier indicating the reason for the condition's last transition....
status enum required
status of the condition, one of True, False, Unknown.
Values: True | False | Unknown
message string required
message is a human readable message indicating details about the transition. This may be an empty st...
coreName string required
metadata object
apiVersion string
APIVersion defines the versioned schema of this representation of an object. Servers should convert ...