Kuma Star

Careful!

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

Data plane proxy

A data plane proxy (DPP) is the part of Kuma that runs next to each workload that is a member of the mesh. A DPP is composed of the following components:

  • a Dataplane entity defines the configuration of the DPP
  • a kuma-dp binary runs on each instance that is part of the mesh. This binary spawns the following subprocesses:
    • Envoy receives configuration from the control-plane to manage traffic correctly
    • core-dns resolves Kuma specific DNS entries

Data plane proxies are also called sidecars.

We have one instance of kuma-dp for every instance of every service.

Concepts

Inbound

An inbound consists of:

  • a set of tags
  • the port the workload listens on

Most of the time a DPP exposes a single inbound. When a workload exposes multiple ports, multiple inbounds can be defined.

Tags

Tags are a set of key-value pairs (.e.g version=v2) that are defined for each DPP inbound. These tags serve the following purposes:

  • specifying the service this DPP inbound is part of
  • adding metadata about the exposed service
  • allowing subsets of DPPs to be selected by these tags

Tags prefixed with kuma.io are reserved:

  • kuma.io/service identifies the service name. On Kubernetes this tag is automatically created, while on Universal it must be specified manually. This tag must always be present.
  • kuma.io/zone identifies the zone name in a multi-zone deployment. This tag is automatically created and cannot be overwritten.
  • kuma.io/protocol identifies the protocol of the service exposed by this inbound. Accepted values are tcp, http, http2, grpc and kafka.

Service

A service is a group of all DPP inbounds that have the same kuma.io/service tag.

Outbounds

An outbound allows the workload to consume a service in the mesh using a local port. This is only useful when not using (/docs/2.8.x/production/dp-config/transparent-proxying/).

Dataplane entity

The Dataplane entity consists of:

  • the IP address used by other DPPs to connect to this DPP
  • inbounds
  • outbounds

A Dataplane entity must be present for each DPP. Dataplane entities are managed differently depending on the environment:

Dynamic configuration of the data plane proxy

When the DPP runs:

  • The kuma-dp retrieves Envoy startup configuration from the control plane.
  • The kuma-dp process starts Envoy with this configuration.
  • Envoy connects to the control plane using XDS and receives configuration updates when the state of the mesh changes.

The control plane uses policies and Dataplane entities to generate the DPP configuration.

Data plane proxy ports

The kuma-dp process and its child process offer a number of services, these services need to listen to a few ports to provide their functionalities.

When we start a data-plane via kuma-dp we expect all the inbound and outbound service traffic to go through it. The inbound and outbound ports are defined in the dataplane specification when running in universal mode, while on Kubernetes the service-to-service traffic always runs on port 15001.

In addition to the service traffic ports, the data plane proxy also opens the following ports:

  • TCP
    • 9901: the HTTP server that provides the Envoy administration interface, It’s bound onto the loop-back interfaces, and can be customized using these methods:
      • On Universal: data field networking.admin.port on the data plane object
      • On Kubernetes: pod annotation kuma.io/envoy-admin-port
    • 9000: the HTTP server that provides the Virtual Probes functionalities. It is automatically enabled on Kubernetes; on Universal, it needs to be enabled explicitly.

Schema

$schema: http://json-schema.org/draft-04/schema#

$ref: #/definitions/Dataplane

definitions

Dataplane

  • ## Dataplane

  • Dataplane defines a configuration of a side-car proxy.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • networking
    • metrics
      • Configuration for metrics that should be collected and exposed by the data plane proxy. Settings defined here will override their respective defaults defined at a Mesh level.
      • Type: object
      • $ref: #/definitions/kuma.mesh.v1alpha1.MetricsBackend
      • This schema accepts additional properties.
      • Properties
    • probes
      • Probes describe a list of endpoints that will be exposed without mTLS. This is useful to expose the health endpoints of the application so the orchestration system (e.g. Kubernetes) can still health check the application. See https://kuma.io/docs/latest/policies/service-health-probes/#virtual-probes for more information.
      • Type: object
      • $ref: #/definitions/kuma.mesh.v1alpha1.Dataplane.Probes
      • This schema accepts additional properties.
      • Properties kuma.mesh.v1alpha1.Dataplane.Networking

  • ## Networking

  • Networking describes inbound and outbound interfaces of a data plane proxy.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • address
      • IP on which the data plane proxy is accessible to the control plane and other data plane proxies in the same network. This can also be a hostname, in which case the control plane will periodically resolve it.
      • Type: string
    • advertisedAddress
      • In some situations, a data plane proxy resides in a private network (e.g. Docker) and is not reachable via address to other data plane proxies. advertisedAddress is configured with a routable address for such data plane proxy so that other proxies in the mesh can connect to it over advertisedAddress and not via address. Envoy still binds to the address, not advertisedAddress.
      • Type: string
    • gateway
    • inbound
      • Inbound describes a list of inbound interfaces of the data plane proxy. Inbound describes a service implemented by the data plane proxy. All incoming traffic to a data plane proxy is going through inbound listeners. For every defined Inbound there is a corresponding Envoy Listener.
      • Type: array
    • outbound
    • transparent_proxying
    • admin
      • Admin describes configuration related to Envoy Admin API. Due to security, all the Envoy Admin endpoints are exposed only on localhost. Additionally, Envoy will expose /ready endpoint on networking.address for health checking systems to be able to check the state of Envoy. The rest of the endpoints exposed on networking.address are always protected by mTLS and only meant to be consumed internally by the control plane.
      • Type: object
      • $ref: #/definitions/kuma.mesh.v1alpha1.EnvoyAdmin
      • This schema accepts additional properties.
      • Properties kuma.mesh.v1alpha1.Dataplane.Networking.Gateway

  • ## Gateway

  • Gateway describes a service that ingress should not be proxied.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • tags
      • Tags associated with a gateway of this data plane to, e.g. kuma.io/service=gateway, env=prod. kuma.io/service tag is mandatory.
      • Type: object
      • This schema accepts additional properties.
      • Properties
    • type
      • #### Gateway Type
      • The value is restricted to the following:
        1. "DELEGATED"
        2. 0
        3. "BUILTIN"
        4. 1 kuma.mesh.v1alpha1.Dataplane.Networking.Inbound

  • ## Inbound

  • Inbound describes a service implemented by the data plane proxy. All incoming traffic to a data plane proxy are going through inbound listeners. For every defined Inbound there is a corresponding Envoy Listener.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • port
      • Port of the inbound interface that will forward requests to the service. When transparent proxying is used, it is a port on which the service is listening to. When transparent proxying is not used, Envoy will bind to this port.
      • Type: integer
    • servicePort
      • Port of the service that requests will be forwarded to. Defaults to the same value as port.
      • Type: integer
    • serviceAddress
      • Address of the service that requests will be forwarded to. Defaults to 'inbound.address', since Kuma DP should be deployed next to the service.
      • Type: string
    • address
      • Address on which inbound listener will be exposed. Defaults to networking.address.
      • Type: string
    • tags
      • Tags associated with an application this data plane proxy is deployed next to, e.g. kuma.io/service=web, version=1.0. You can then reference these tags in policies like MeshTrafficPermission. kuma.io/service tag is mandatory.
      • Type: object
      • This schema accepts additional properties.
      • Properties
    • health
      • Health describes the status of an inbound. If 'health' is nil we consider data plane proxy as healthy. Unhealthy data plane proxies are excluded from Endpoints Discovery Service (EDS). On Kubernetes, it is filled automatically by the control plane if Pod has readiness probe configured. On Universal, it can be set by the external health checking system, but the most common way is to use service probes. See https://kuma.io/docs/latest/documentation/health for more information.
      • Type: object
      • $ref: #/definitions/kuma.mesh.v1alpha1.Dataplane.Networking.Inbound.Health
      • This schema accepts additional properties.
      • Properties
    • serviceProbe
      • ServiceProbe defines parameters for probing the service next to sidecar. When service probe is defined, Envoy will periodically health check the application next to it and report the status to the control plane. On Kubernetes, Kuma deployments rely on Kubernetes probes so this is not used. See https://kuma.io/docs/latest/documentation/health for more information.
      • Type: object
      • $ref: #/definitions/kuma.mesh.v1alpha1.Dataplane.Networking.Inbound.ServiceProbe
      • This schema accepts additional properties.
      • Properties
    • state
      • #### State
      • The value is restricted to the following:
        1. "Ready"
        2. 0
        3. "NotReady"
        4. 1
        5. "Ignored"
        6. 2
    • name
      • Name adds another way of referencing this port, usable with MeshService
      • Type: string kuma.mesh.v1alpha1.Dataplane.Networking.Inbound.Health

  • ## Health

  • Health describes the status of an inbound

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • ready
      • Ready indicates if the data plane proxy is ready to serve the traffic.
      • Type: boolean kuma.mesh.v1alpha1.Dataplane.Networking.Inbound.ServiceProbe

  • ## Service Probe

  • ServiceProbe defines parameters for probing service's port

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • interval
      • Interval between consecutive health checks.
      • Type: string
      • String format must be a "regex"
      • The value must match this pattern: ^([0-9]+\.?[0-9]*|\.[0-9]+)s$
    • timeout
      • Maximum time to wait for a health check response.
      • Type: string
      • String format must be a "regex"
      • The value must match this pattern: ^([0-9]+\.?[0-9]*|\.[0-9]+)s$
    • unhealthy_threshold
      • Number of consecutive unhealthy checks before considering a host unhealthy.
      • Type: integer
    • healthy_threshold
      • Number of consecutive healthy checks before considering a host healthy.
      • Type: integer
    • tcp

  • ## Tcp

  • Type: object

  • This schema accepts additional properties.

  • Properties kuma.mesh.v1alpha1.Dataplane.Networking.Outbound

  • ## Outbound

  • Outbound describes a service consumed by the data plane proxy. For every defined Outbound there is a corresponding Envoy Listener.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • address
      • IP on which the consumed service will be available to this data plane proxy. On Kubernetes, it's usually ClusterIP of a Service or PodIP of a Headless Service. Defaults to 127.0.0.1
      • Type: string
    • port
      • Port on which the consumed service will be available to this data plane proxy. When transparent proxying is not used, Envoy will bind to this port.
      • Type: integer
    • tags
      • Tags of consumed data plane proxies. kuma.io/service tag is required. These tags can then be referenced in destinations section of policies like TrafficRoute or in to section in policies like MeshAccessLog. It is recommended to only use kuma.io/service. If you need to consume specific data plane proxy of a service (for example: version=v2) the better practice is to use TrafficRoute.
      • Type: object
      • This schema accepts additional properties.
      • Properties
    • backendRef

  • ## Backend Ref

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • kind
      • Kind is a type of the object to target. Allowed: MeshService
      • Type: string
    • name
      • Name of the targeted object
      • Type: string
    • port
      • Port of the targeted object. Required when kind is MeshService.
      • Type: integer kuma.mesh.v1alpha1.Dataplane.Networking.TransparentProxying

  • ## Transparent Proxying

  • TransparentProxying describes configuration for transparent proxying.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • redirectportinbound
      • Port on which all inbound traffic is being transparently redirected.
      • Type: integer
    • redirectportoutbound
      • Port on which all outbound traffic is being transparently redirected.
      • Type: integer
    • directaccessservices
      • List of services that will be accessed directly via IP:PORT Use * to indicate direct access to every service in the Mesh. Using * to directly access every service is a resource-intensive operation, use it only if needed.
      • Type: array
        • Items
        • Type: string
    • redirectportinbound_v6
      • Port on which all IPv6 inbound traffic is being transparently redirected.
      • Type: integer
    • reachable_services
      • List of reachable services (represented by the value of kuma.io/service) via transparent proxying. Setting an explicit list can dramatically improve the performance of the mesh. If not specified, all services in the mesh are reachable.
      • Type: array
        • Items
        • Type: string
    • ipfamilymode
      • #### Ip Family Mode
      • The value is restricted to the following:
        1. "UnSpecified"
        2. 0
        3. "DualStack"
        4. 1
        5. "IPv4"
        6. 2
        7. "IPv6"
        8. 3 kuma.mesh.v1alpha1.Dataplane.Probes

  • ## Probes

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • port
      • Port on which the probe endpoints will be exposed. This cannot overlap with any other ports.
      • Type: integer
    • endpoints

  • ## Endpoint

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • inbound_port
      • Inbound port is a port of the application from which we expose the endpoint.
      • Type: integer
    • inbound_path
      • Inbound path is a path of the application from which we expose the endpoint. It is recommended to be as specific as possible.
      • Type: string
    • path
      • Path is a path on which we expose inbound path on the probes port.
      • Type: string kuma.mesh.v1alpha1.EnvoyAdmin

  • ## Envoy Admin

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • port
      • Port on which Envoy Admin API server will be listening
      • Type: integer kuma.mesh.v1alpha1.MetricsBackend

  • ## Metrics Backend

  • MetricsBackend defines metric backends

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • name
      • Name of the backend, can be then used in Mesh.metrics.enabledBackend
      • Type: string
    • type
      • Type of the backend (Kuma ships with 'prometheus')
      • Type: string
    • conf
      • Configuration of the backend
      • Type: object
      • This schema accepts additional properties.
      • Properties

Generated with json-schema-md-doc Fri May 09 2025 20:05:07 GMT+0000 (Coordinated Universal Time)