Annotations and labels in Kubernetes mode

This page provide 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. 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 prefered label.

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"
  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

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/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"