Kuma

https://kuma.io/docs/
Admin
Kuma is a platform-agnostic open-source control plane for service mesh and microservices management...
Tokens:10,482
Snippets:158
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install kumactl via Homebrew (macOS)

Source: https://kuma.io/docs/latest/introduction/install

For macOS users, `kumactl` can be conveniently installed using Homebrew.

```bash
brew install kumactl
```

--------------------------------

### Add Kuma Binaries to PATH

Source: https://kuma.io/docs/latest/introduction/install

After installation, add the Kuma binaries to your PATH to easily access commands like `kuma-dp`, `kuma-cp`, and `kumactl`.

```bash
export PATH=$(pwd)/kuma-2.13.5/bin:$PATH
```

--------------------------------

### Download and Extract Kuma Installer

Source: https://kuma.io/docs/latest/introduction/install

Use this command to download and extract the latest Kuma release for Linux or macOS.

```bash
curl -L https://kuma.io/installer.sh | VERSION=2.13.5 sh -
```

--------------------------------

### Custom eBPF Programs Source Path

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Provide a custom path for eBPF programs to be loaded when installing transparent proxy.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  [...]
  template:
    metadata:
      [...]
      annotations:
        kuma.io/transparent-proxying-ebpf-programs-source-path: /custom/ebpf/programs/source/path
    spec:
      containers:
        [...]

```

--------------------------------

### Set Envoy Component Log Level

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Configure log levels for specific Envoy components using `kuma.io/envoy-component-log-level`. For example, `upstream:debug,connection:trace`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/envoy-component-log-level: "upstream:debug,connection:trace"

```

--------------------------------

### Enable Experimental Transparent Proxy Engine

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Enable or disable the experimental transparent proxy engine on a Pod by setting `kuma.io/transparent-proxying-experimental-engine`. Defaults to `disabled`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/transparent-proxying-experimental-engine: enabled

```

--------------------------------

### Enable Virtual Probes with Kuma

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Use `kuma.io/virtual-probes` to automatically convert HttpGet probes to virtual probes. Specify the insecure port with `kuma.io/virtual-probes-port`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/virtual-probes: enabled
    kuma.io/virtual-probes-port: "9000"
[...]

```

--------------------------------

### Configure Sidecar Environment Variables

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Set semicolon-separated environment variables for the Kuma sidecar using `kuma.io/sidecar-env-vars`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/sidecar-env-vars: TEST1=1;TEST2=2

```

--------------------------------

### Enable Built-in DNS Server

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Configure the Kuma sidecar to use its built-in DNS server by setting `kuma.io/builtindns` to `enabled`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/builtindns: enabled

```

--------------------------------

### Specify Reachable Services for Transparent Proxying

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

List services that this workload communicates with for transparent proxying. This is a comma-separated string of `kuma.io/service` values.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  ...
  template:
    metadata:
      ...
      annotations:
        # a comma separated list of kuma.io/service values
        kuma.io/transparent-proxying-reachable-services: "redis_kuma-demo_svc_6379,elastic_kuma-demo_svc_9200"
    spec:
      containers:
        ...

```

--------------------------------

### Prioritize Kuma init container

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Set to 'true' to ensure the Kuma init container runs before other init containers. This can enhance security by restricting network access for subsequent init containers. Note that the order is not strictly guaranteed due to other mutating admission webhooks.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/init-first: "true"
spec: ...
```

--------------------------------

### Enable Gateway Mode

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify this annotation on a pod to run it in gateway mode. Inbound listeners will not be generated.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gateway
spec:
  selector:
    matchLabels:
      app: gateway
  template:
    metadata:
      labels:
        app: gateway
      annotations:
        kuma.io/gateway: enabled
[...]

```

--------------------------------

### Enable Application Metrics Aggregation

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Enable Kuma to scrape metrics from the application defined in the `Mesh` configuration. The default value is `true`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    prometheus.metrics.kuma.io/aggregate-app-enabled: "false"
spec: ...

```

--------------------------------

### Configure Built-in DNS Server Port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Set the listening port for the Kuma sidecar's built-in DNS server using `kuma.io/builtindnsport`. Requires `kuma.io/builtindns` to be enabled.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/builtindns: enabled
    kuma.io/builtindnsport: "15053"

```

--------------------------------

### Configure Service Account Token Volume

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify a volume to provide a service account token for Kuma to inject into the sidecar. Ensure `automountServiceAccountToken` is set to `false`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/service-account-token-volume: "token-vol"
spec:
  automountServiceAccountToken: false
  serviceAccount: example
  containers:
    - image: busybox
      name: busybox
  volumes:
    - name: token-vol
      projected:
        sources:
          - serviceAccountToken:
              expirationSeconds: 7200
              path: token
              audience: "https://kubernetes.default.svc"
          - configMap:
              items:
                - key: ca.crt
                  path: ca.crt
              name: kube-root-ca.crt
          - downwardAPI:
              items:
                - fieldRef:
                    apiVersion: v1
                    fieldPath: metadata.namespace
                  path: namespace

```

--------------------------------

### Associate Pods with a Mesh on Namespace

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Label a namespace to associate all its pods with a specific Kuma Mesh. The label value must be the name of an existing Mesh resource.

```yaml
apiVersion: v1
kind: Namespace
metadata:
 name: default
 labels:
   kuma.io/mesh: default
[...]

```

--------------------------------

### Enable Sidecar Injection on Namespace

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Apply this label to a namespace to enable sidecar injection for all pods within that namespace.

```yaml
apiVersion: v1
kind: Namespace
metadata:
 name: default
 labels:
   kuma.io/sidecar-injection: enabled
[...]

```

--------------------------------

### Configure Prometheus metrics scrape path

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Define the path for Prometheus metrics scraping by the kuma-dp sidecar. Default is /metrics.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    prometheus.metrics.kuma.io/aggregate-app-path: "/stats"
spec: ...
```

--------------------------------

### Custom BPF File System Path for eBPF

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify a custom path for the BPF file system if it differs from the default (`/sys/fs/bpf`).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  [...]
  template:
    metadata:
      [...]
      annotations:
        kuma.io/transparent-proxying-ebpf-bpf-fs-path: /custom/bpffs/path
    spec:
      containers:
        [...]

```

--------------------------------

### Direct Access Services Configuration

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Provide a comma-separated list of services accessible directly. This annotation, when used with transparent proxying, generates listeners to encrypt traffic through a direct-access cluster.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/direct-access-services: test-app_playground_svc_80,test-app_playground_svc_443
    kuma.io/transparent-proxying: enabled
    kuma.io/transparent-proxying-inbound-port: [...] 
    kuma.io/transparent-proxying-outbound-port: [...] 

```

--------------------------------

### Custom cgroup2 Path for eBPF

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify a custom path for cgroup2 if it differs from the default (`/sys/fs/cgroup`).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  [...]
  template:
    metadata:
      [...]
      annotations:
        kuma.io/transparent-proxying-ebpf-cgroup-path: /custom/cgroup2/path
    spec:
      containers:
        [...]

```

--------------------------------

### Configure Application Probe Proxy Port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Set the port for the Application Probe Proxy. Setting this to '0' disables the proxy and enables 'Virtual Probes', unless 'Virtual Probes' are also explicitly disabled.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/application-probe-proxy-port: "9001"
[...]

```

--------------------------------

### Configure Prometheus metrics scrape port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Define the port for Prometheus metrics scraping by the kuma-dp sidecar. Ensure this port is accessible by the sidecar.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    prometheus.metrics.kuma.io/aggregate-app-port: "1234"
spec: ...
```

--------------------------------

### Enable Sidecar Injection on Deployment

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Apply this label to a deployment's pod template to enable sidecar injection for all pods managed by that deployment.

```yaml
apiVersion: v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  template:
    metadata:
      labels:
        kuma.io/sidecar-injection: enabled
[...]

```

--------------------------------

### Apply Container Patches to Kuma Containers

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Use `kuma.io/container-patches` to specify `ContainerPatch` resources for `kuma-init` and `kuma-sidecar` containers. This is applied on workload resources like Deployments.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: kuma-system
  name: example
spec:
  replicas: 1
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
      annotations:
        kuma.io/container-patches: container-patch-1,container-patch-2
    spec: [...]
```

--------------------------------

### Associate Pods with a Mesh on Pod

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Label a pod to associate it with a specific Kuma Mesh. The label value must be the name of an existing Mesh resource.

```yaml
apiVersion: v1
kind: Pod
metadata:
 name: backend
 labels:
   kuma.io/mesh: default
[...]

```

--------------------------------

### Set Envoy Log Level

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Control the log level for Envoy system logs using `kuma.io/envoy-log-level`. Available levels include trace, debug, info, warning, error, critical, and off. Defaults to `info`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/envoy-log-level: "warning"

```

--------------------------------

### Mark Pod as Zone Ingress

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Use this annotation to mark a pod as the Zone Ingress, which is essential for multizone communication by providing an entry point for traffic from other zones.

```yaml
apiVersion: v1
kind: Pod
metadata:
 name: zone-ingress
 annotations:
   kuma.io/ingress: enabled
[...]

```

--------------------------------

### Configure IPv6 transparent proxying port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Define the port for IPv6 traffic. Set to 0 to disable IPv6 transparent proxying.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/transparent-proxying-inbound-v6-port: "0"
spec: ...
```

--------------------------------

### Specify TC Attach Interface for eBPF

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Define the network interface for attaching TC-related eBPF programs. If not specified, Kuma uses the first non-loopback interface found.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  [...]
  template:
    metadata:
      [...]
      annotations:
        kuma.io/transparent-proxying-ebpf-tc-attach-iface: eth3
    spec:
      containers:
        [...]

```

--------------------------------

### Ignore Service with Kuma

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Mark a Kubernetes Service as ignored by Kuma using the `kuma.io/ignore: "true"` annotation. Useful for gradual adoption or temporary exclusion.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: example
  annotations:
    kuma.io/ignore: "true"

```

--------------------------------

### Specify Envoy Admin Port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Set the port for the Envoy Admin API using `kuma.io/envoy-admin-port`. Defaults to 9901 if not specified.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/envoy-admin-port: "8801"

```

--------------------------------

### Override Prometheus Metrics Port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Customize the Prometheus metrics scraping port for a Pod using the `prometheus.metrics.kuma.io/port` annotation.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    prometheus.metrics.kuma.io/port: "1234"

```

--------------------------------

### Configure Kuma DP sidecar drain time

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify the drain time for the Kuma DP sidecar. Default is 30s, but can be overridden by control-plane configuration or environment variables.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    kuma.io/sidecar-drain-time: "10s"
spec: ...
```

--------------------------------

### Specify Ingress Public Port

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Define the public port for the Ingress. If this annotation is omitted, Kuma will use the port from the Ingress Service.

```yaml
apiVersion: v1
kind: Pod
metadata:
 name: zone-ingress
 annotations:
   kuma.io/ingress: enabled
   kuma.io/ingress-public-port: "1234"
[...]

```

--------------------------------

### Override Prometheus Metrics Path

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify a custom path for Prometheus to scrape metrics from a Pod using the `prometheus.metrics.kuma.io/path` annotation.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    prometheus.metrics.kuma.io/path: "/custom-metrics"

```

--------------------------------

### Specify Ingress Public Address

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Define the public address for the Ingress. If this annotation is omitted, Kuma will use the address from the Ingress Service.

```yaml
apiVersion: v1
kind: Pod
metadata:
 name: zone-ingress
 annotations:
   kuma.io/ingress: enabled
   kuma.io/ingress-public-address: custom-address.com
[...]

```

--------------------------------

### Disable Transparent Proxying with eBPF

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Disable transparent proxying for specific workloads when using eBPF mode. This annotation should be set to `disabled`.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-app
  namespace: kuma-example
spec:
  [...]
  template:
    metadata:
      [...]
      annotations:
        kuma.io/transparent-proxying-ebpf: disabled
    spec:
      containers:
        [...]

```

--------------------------------

### Exclude Inbound Ports from Interception

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify a comma-separated list of inbound ports to exclude from Kuma sidecar traffic interception using `traffic.kuma.io/exclude-inbound-ports`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    traffic.kuma.io/exclude-inbound-ports: "1234,1235"

```

--------------------------------

### Exclude Outbound Ports from Interception

Source: https://kuma.io/docs/latest/reference/kubernetes-annotations

Specify a comma-separated list of outbound ports to exclude from Kuma sidecar traffic interception using `traffic.kuma.io/exclude-outbound-ports`.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: example
  annotations:
    traffic.kuma.io/exclude-outbound-ports: "1234,1235"

```
Tokens:
Raw