Annotations and labels in Kubernetes mode

    Enable or disable sidecar injection.

    Example

    Used on the namespace it will inject the sidecar in all pods created in the namespace:

    Used on a deployment using pod template it will inject the sidecar in all pods managed by this deployment:

    1. apiVersion: v1
    2. king: Deployment
    3. metadata:
    4.   name: my-deployment
    5. spec:
    6.   template:
    7.     metadata:
    8.       labels:
    9.         kuma.io/sidecar-injection: enabled
    10. [...]

    Labeling pods or deployments will take precedence on the namespace annotation.

    Annotations

    kuma.io/mesh

    Associate Pods with a particular Mesh. Annotation value must be the name of a Mesh resource.

    Example

    It can be used on an entire namespace:

    1. apiVersion: v1
    2. kind: Namespace
    3. metadata:
    4.  name: default
    5.  annotations:
    6.    kuma.io/mesh: default
    7. [...]

    It can be used on a pod:

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.  name: backend
    5.  annotations:
    6.    kuma.io/mesh: default
    7. [...]

    Annotating pods or deployments will take precedence on the namespace annotation.

    kuma.io/sidecar-injection

    Similar to the preferred .

    Example

    1. apiVersion: v1
    2. kind: Namespace
    3. metadata:
    4.  name: default
    5.  annotations:
    6.    kuma.io/sidecar-injection: enabled
    7. [...]

    While you can still use annotations to inject sidecar, we strongly recommend using labels. It’s the only way to guarantee that application can only be started with sidecar.

    kuma.io/gateway

    Lets you specify the Pod should run in gateway mode. Inbound listeners are not generated.

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: gateway
    5. spec:
    6.   selector:
    7.     matchLabels:
    8.       app: gateway
    9.   template:
    10.     metadata:
    11.       labels:
    12.         app: gateway
    13.       annotations:
    14.         kuma.io/gateway: enabled
    15. [...]

    kuma.io/ingress

    Marks the Pod as the Zone Ingress. Needed for multizone communication – provides the entry point for traffic from other zones.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.  name: zone-ingress
    5.  annotations:
    6.    kuma.io/ingress: enabled
    7. [...]

    kuma.io/ingress-public-address

    Specifies the public address for Ingress. If not provided, Kuma picks the address from the Ingress Service.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.  name: zone-ingress
    5.  annotations:
    6.    kuma.io/ingress: enabled
    7.    kuma.io/ingress-public-address: custom-address.com
    8. [...]

    kuma.io/ingress-public-port

    Specifies the public port for Ingress. If not provided, Kuma picks the port from the Ingress Service.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.  name: zone-ingress
    5.  annotations:
    6.    kuma.io/ingress: enabled
    7.    kuma.io/ingress-public-port: "1234"

    kuma.io/direct-access-services

    Defines a comma-separated list of Services that can be accessed directly.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/direct-access-services: test-app_playground_svc_80,test-app_playground_svc_443
    7.     kuma.io/transparent-proxying: enabled
    8.     kuma.io/transparent-proxying-inbound-port: [...]
    9.     kuma.io/transparent-proxying-outbound-port: [...]

    When you provide this annotation, Kuma generates a listener for each IP address and redirects traffic through a direct-access cluster that’s configured to encrypt connections.

    These listeners are needed because transparent proxy and mTLS assume a single IP per cluster (for example, the ClusterIP of a Kubernetes Service). If you pass requests to direct IP addresses, Envoy considers them unknown destinations and manages them in passthrough mode – which means they’re not encrypted with mTLS. The direct-access cluster enables encryption anyway.

    WARNING: You should specify this annotation only if you really need it. Generating listeners for every endpoint makes the xDS snapshot very large.

    kuma.io/virtual-probes

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/virtual-probes: enabled
    7.     kuma.io/virtual-probes-port: "9000"
    8. [...]

    kuma.io/virtual-probes-port

    Specifies the insecure port for listening on virtual probes.

    kuma.io/sidecar-env-vars

    Semicolon (;) separated list of environment variables for the Kuma sidecar.

    Example

    Specifies the list of names of ContainerPatch resources to be applied on kuma-init and kuma-sidecar containers.

    More information about how to use ContainerPatch you can find at .

    Example

    It can be used on a resource describing workload (i.e. Deployment, DaemonSet or Pod):

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   namespace: kuma-system
    5.   name: example
    6. spec:
    7.   replicas: 1
    8.   selector:
    9.     matchLabels:
    10.       app: example
    11.   template:
    12.     metadata:
    13.       labels:
    14.         app: example
    15.       annotations:
    16.         kuma.io/container-patches: container-patch-1,container-patch-2
    17.     spec: [...]

    prometheus.metrics.kuma.io/port

    Lets you override the Mesh-wide default port that Prometheus should scrape metrics from.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     prometheus.metrics.kuma.io/port: "1234"

    prometheus.metrics.kuma.io/path

    Lets you override the Mesh-wide default path that Prometheus should scrape metrics from.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     prometheus.metrics.kuma.io/path: "/custom-metrics"

    kuma.io/builtindns

    Tells the sidecar to use its builtin DNS server.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/builtindns: enabled

    kuma.io/builtindnsport

    Port the builtin DNS server should listen on for DNS queries.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/builtindns: enabled
    7.     kuma.io/builtindnsport: "15053"

    kuma.io/ignore

    A boolean to mark a resource as ignored by Kuma. It currently only works for services. This is useful when transitioning to Kuma or to temporarily ignore some entities.

    Example

    1. apiVersion: v1
    2. kind: Service
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/ignore: "true"

    traffic.kuma.io/exclude-inbound-ports

    List of inbound ports to exclude from traffic interception by the Kuma sidecar.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     traffic.kuma.io/exclude-inbound-ports: "1234,1235"

    traffic.kuma.io/exclude-outbound-ports

    List of outbound ports to exclude from traffic interception by the Kuma sidecar.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     traffic.kuma.io/exclude-outbound-ports: "1234,1235"

    kuma.io/transparent-proxying-experimental-engine

    Enable or disable experimental transparent proxy engine on Pod. Default is disabled.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/transparent-proxying-experimental-engine: enabled

    kuma.io/envoy-admin-port

    Specifies the port for Envoy Admin API. If not set, default admin port 9901 will be used.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/envoy-admin-port: "8801"

    kuma.io/service-account-token-volume

    Example

    A comma separated list of kuma.io/service to indicate which services this communicates with. For more details see the .

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: example-app
    5.   namespace: kuma-example
    6. spec:
    7.   ...
    8.   template:
    9.     metadata:
    10.       ...
    11.       annotations:
    12.         # a comma separated list of kuma.io/service values
    13.         kuma.io/transparent-proxying-reachable-services: "redis_kuma-demo_svc_6379,elastic_kuma-demo_svc_9200"
    15.         ...

    kuma.io/transparent-proxying-ebpf

    When transparent proxy is installed with ebpf mode, you can disable it for particular workloads if necessary.

    For more details see the .

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: example-app
    5.   namespace: kuma-example
    6. spec:
    7.   [...]
    8.   template:
    9.     metadata:
    10.       [...]
    11.       annotations:
    12.         kuma.io/transparent-proxying-ebpf: disabled
    13.     spec:
    14.       containers:
    15.         [...]

    kuma.io/transparent-proxying-ebpf-bpf-fs-path

    Path to BPF FS if different than default (/sys/fs/bpf)

    For more details see the .

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: example-app
    5.   namespace: kuma-example
    6. spec:
    7.   [...]
    8.   template:
    9.     metadata:
    10.       [...]
    11.       annotations:
    12.         kuma.io/transparent-proxying-ebpf-bpf-fs-path: /custom/bpffs/path
    13.     spec:
    14.       containers:
    15.         [...]

    kuma.io/transparent-proxying-ebpf-cgroup-path

    cgroup2 path if different than default (/sys/fs/cgroup)

    For more details see the .

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: example-app
    5.   namespace: kuma-example
    6. spec:
    7.   [...]
    8.   template:
    9.     metadata:
    10.       [...]
    11.       annotations:
    12.         kuma.io/transparent-proxying-ebpf-cgroup-path: /custom/cgroup2/path
    13.     spec:
    14.       containers:
    15.         [...]

    kuma.io/transparent-proxying-ebpf-programs-source-path

    Custom path for ebpf programs to be loaded when installing transparent proxy

    For more details see the .

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: example-app
    5.   namespace: kuma-example
    6. spec:
    7.   [...]
    8.   template:
    9.     metadata:
    10.       [...]
    11.       annotations:
    12.         kuma.io/transparent-proxying-ebpf-programs-source-path: /custom/ebpf/programs/source/path
    13.     spec:
    14.       containers:
    15.         [...]

    kuma.io/transparent-proxying-ebpf-tc-attach-iface

    Name of the network interface which should be used to attach to it TC-related eBPF programs. By default Kuma will use first, non-loopback interface it’ll find.

    For more details see the .

    Example

    1. apiVersion: apps/v1
    2. kind: Deployment
    3. metadata:
    4.   name: example-app
    5.   namespace: kuma-example
    6. spec:
    7.   [...]
    8.   template:
    9.     metadata:
    10.       [...]
    11.       annotations:
    12.         kuma.io/transparent-proxying-ebpf-tc-attach-iface: eth3
    13.     spec:
    14.       containers:
    15.         [...]

    prometheus.metrics.kuma.io/aggregate-<name>-enabled

    Define if kuma-dp should scrape metrics from the application that has been defined in the Mesh configuration. Default value: true. For more details see the 

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     prometheus.metrics.kuma.io/aggregate-app-enabled: "false"
    7. spec: ...

    prometheus.metrics.kuma.io/aggregate-<name>-path

    Define path, which kuma-dp sidecar has to scrape for prometheus metrics. Default value: /metrics. For more details see the

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     prometheus.metrics.kuma.io/aggregate-app-path: "/stats"
    7. spec: ...

    prometheus.metrics.kuma.io/aggregate-<name>-port

    Define port, which kuma-dp sidecar has to scrape for prometheus metrics. For more details see the

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     prometheus.metrics.kuma.io/aggregate-app-port: "1234"
    7. spec: ...

    kuma.io/transparent-proxying-inbound-v6-port

    Define the port to use for traffic. To turn off IPv6 set this to 0.

    Example

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: example
    5.   annotations:
    6.     kuma.io/transparent-proxying-inbound-v6-port: "0"

    Allows specifying drain time of Kuma DP sidecar. The default value is 30s. The default could be changed using or KUMA_RUNTIME_KUBERNETES_INJECTOR_SIDECAR_CONTAINER_DRAIN_TIME env.