Kubernetes annotations and labels

This page provides a complete list of all the annotations you can specify when you run Kuma in Kubernetes mode.

Labels

kuma.io/sidecar-injection

Enable or disable sidecar injection.

Example

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

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

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

  1. apiVersion: v1
  2. kind: 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/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"
  8. [...]

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

Enables automatic converting of HttpGet probes to virtual probes. The virtual probe is served on a sub-path of the insecure port specified with kuma.io/virtual-probes-port – for example, :8080/health/readiness -> :9000/8080/health/readiness, where 9000 is the value of the kuma.io/virtual-probes-port annotation.

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

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. name: example
  5. annotations:
  6. kuma.io/sidecar-env-vars: TEST1=1;TEST2=2

kuma.io/container-patches

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 Custom Container Configuration .

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

Volume (specified in the pod spec) containing a service account token for Kuma to inject into the sidecar.

Example

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. name: example
  5. annotations:
  6. kuma.io/service-account-token-volume: "token-vol"
  7. spec:
  8. automountServiceAccountToken: false
  9. serviceAccount: example
  10. containers:
  11. - image: busybox
  12. name: busybox
  13. volumes:
  14. - name: token-vol
  15. projected:
  16. sources:
  17. - serviceAccountToken:
  18. expirationSeconds: 7200
  19. path: token
  20. audience: "https://kubernetes.default.svc"
  21. - configMap:
  22. items:
  23. - key: ca.crt
  24. path: ca.crt
  25. name: kube-root-ca.crt
  26. - downwardAPI:
  27. items:
  28. - fieldRef:
  29. apiVersion: v1
  30. fieldPath: metadata.namespace
  31. path: namespace

kuma.io/transparent-proxying-reachable-services

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

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"
  14. spec:
  15. containers:
  16. ...

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 transparent proxying with ebpf docs .

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 transparent proxying with ebpf docs .

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 transparent proxying with ebpf docs .

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 transparent proxying with ebpf docs .

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 transparent proxying with ebpf docs .

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. [...]

kuma.io/wait-for-dataplane-ready

Define if you want the kuma-sidecar container to wait for the dataplane to be ready before starting app container. Read relevant Data plane on Kubernetes section for more information.

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 applications metrics docs

  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 applications metrics docs

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 applications metrics docs

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 IPv6 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"
  7. spec: ...

kuma.io/sidecar-drain-time

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

Example

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. name: example
  5. annotations:
  6. kuma.io/sidecar-drain-time: "10s"
  7. spec: ...

kuma.io/init-first

Allows specifying that the Kuma init container should run first (ahead of any other init containers). The default is false if omitted. Setting this to true may be desirable for security, as it would prevent network access for other init containers. The order is not guaranteed, as other mutating admission webhooks may further manipulate this ordering.

Example

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. name: example
  5. annotations:
  6. kuma.io/init-first: "true"
  7. spec: ...