---
title: "Kubernetes Annotations | Speedscale Docs"
description: "Configure Kubernetes eBPF capture and Java Agent injection, with common operator annotations and legacy sidecar settings."
canonical: "https://docs.speedscale.com/reference/kubernetes-annotations/"
---

[Documentation index](https://docs.speedscale.com/reference/llms.txt) | [Markdown](https://docs.speedscale.com/reference/kubernetes-annotations/index.md) | [Canonical page](https://docs.speedscale.com/reference/kubernetes-annotations/)

# Kubernetes Annotations

Start with [Kubernetes capture with eBPF and Java Agent](https://docs.speedscale.com/guides/capture/kubernetes/) for prerequisites, manifest placement, rollout requirements, persistence, and capture verification. The capture annotations below configure the standard operator's capture path. Replays are controlled using [Custom Resource Definitions](https://docs.speedscale.com/reference/replay-crd/).

<a id="capture-annotations"></a>

## Capture annotations

Set these on the workload's top-level `metadata.annotations`, outside the pod template. The eBPF controller supports Deployments, StatefulSets, DaemonSets, Jobs, and installed Argo Rollouts. The standard operator and collector must be installed and permitted to watch the namespace. A strict [namespace-scoped installation](https://docs.speedscale.com/getting-started/installation/install/kubernetes-namespaced/) has no collector or injection webhook and uses a separate [sidecar capture workflow](https://docs.speedscale.com/guides/capture/sidecar-namespaced/).

| Annotation | Values | Effect |
| --- | --- | --- |
| `capture.speedscale.com/enabled` | `"true"` or `"false"`; default `"false"` | Selects the workload's pods for eBPF capture. Requires `ebpf.enabled: true` in the Speedscale Helm release. |
| `capture.speedscale.com/java-agent` | `"true"` or `"false"`; default `"false"` | Adds the Java Agent init container, volume, and JVM startup option. Can be combined with eBPF capture. Requires new pods and a JVM restart. See [compatibility](https://docs.speedscale.com/reference/java/agent/#compatibility). |
| `capture.speedscale.com/java-agent-tag` | Agent image tag; omitted uses the installation's default nettap component tag | Overrides the Java Agent init-container image tag. Check the image on a new pod when comparing agent versions. |
| `capture.speedscale.com/ignore-ports` | Comma-separated port numbers, `1` to `65535`; omitted excludes no ports through this annotation | Excludes the listed ports from eBPF capture for this workload. Invalid entries are skipped and logged by the operator. |

Keep annotations in the workload's [Helm/GitOps source](https://docs.speedscale.com/guides/capture/kubernetes/#preserve-capture-across-redeploys) so they survive workload recreation or reconciliation. Do not enable `sidecar.speedscale.com/inject` together with either eBPF capture or Java Agent injection; the standard operator rejects those combinations.

<a id="common-annotations"></a>

## Common annotations

These annotations are common across workloads and Speedscale's Custom Resources.

<a id="operatorspeedscalecomignore"></a>

### `operator.speedscale.com/ignore`

Instructs the Speedscale operator to skip processing of this workload regardless of any other Speedscale annotations. Changes made to a workload manually AFTER this annotation was added won’t be reverted by the operator.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="operatorspeedscalecomsut"></a>

### `operator.speedscale.com/sut`

Indicates that this workload is the System Under Test, or SUT, that has a sidecar injected AND/OR replay running. This boolean value is assigned automatically by the Speedscale operator.

* * *

<a id="operatorspeedscalecommanaged-by"></a>

### `operator.speedscale.com/managed-by`

Unique name of the Speedscale operator instance which manages this workload or `TrafficReplay` CR. This prevents contention between operators in the event that there are multiple operator instances in different namespaces. This string value is assigned automatically by the Speedscale operator.

<a id="sidecar-annotations"></a>

## Legacy sidecar annotations

These settings apply to the [legacy sidecar fallback](https://docs.speedscale.com/getting-started/installation/sidecar/install/). Use the capture annotations above for standard Kubernetes capture.

Sidecar capture is deprecated

For standard Kubernetes capture, follow [Kubernetes capture with eBPF and Java Agent](https://docs.speedscale.com/guides/capture/kubernetes/). The annotations in this reference are retained for existing sidecar deployments and workloads that do not meet the eBPF requirements.

<a id="sidecarspeedscalecominject"></a>

### `sidecar.speedscale.com/inject`

Add the sidecar to your: deployment, job, stateful set or daemon set.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecominsert-init-first"></a>

### `sidecar.speedscale.com/insert-init-first`

Add Speedscale's init container as the first in the list on the target workload.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomcapture-mode"></a>

### `sidecar.speedscale.com/capture-mode`

Sidecar capture mode. The only supported value is `proxy` (default)

*   Accepted Values
    *   `proxy` (default)

* * *

<a id="sidecarspeedscalecomcapture-node-traffic"></a>

### `sidecar.speedscale.com/capture-node-traffic`

Configure inbound traffic originating from underlying Kubernetes node on which a pod is running to be routed through the proxy. The default behavior is to ignore inbound Kubernetes node traffic (e.g. readiness and liveness checks). Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomhost-resolution"></a>

### `sidecar.speedscale.com/host-resolution`

Configure how the sidecar determines a hostname for requests to IP addresses for which there is no clear way to determine the target host, such as undecrypted TLS and unknown protocols. By default, the sidecar uses a `smart` host resolution mode that maps IP addresses to hostnames based on observed DNS A record requests. Alternatively, if set to `standard`, host resolution is done with a DNS PTR record query. Setting this to `none` will disable automatic host resolution.

Important

Using `standard` mode host resolution is not guaranteed to discover a hostname for an IP address nor is it guaranteed to be accurate if it does, as it requires a PTR record to exist for the address.

*   Accepted Values:
    *   `smart` (default)
    *   `standard`
    *   `none`

* * *

<a id="sidecarspeedscalecomprometheus-port"></a>

### `sidecar.speedscale.com/prometheus-port`

Determines the port that the sidecar will expose for Prometheus scraping. This tells the operator to add a containerPort to the sidecar's pod and configure goproxy's environemnt variables. This is not the same thing as prometheus.io/port because that may be pre-existing and/or be merged with our value.

* * *

<a id="sidecarspeedscalecomprometheus-enable-scrape-annotations"></a>

### `sidecar.speedscale.com/prometheus-enable-scrape-annotations`

If true, tells the operator to add Prometheus scrape annotations to the sidecar's pod. This is not the same thing as prometheus.io/scrape because that tells Prometheus what to do. This tells the Speedscale operator what to do.

* * *

<a id="sidecarspeedscalecomproxy-type"></a>

### `sidecar.speedscale.com/proxy-type`

Type of proxy the sidecar should operate as. Only valid if `capture-mode` is `proxy`, ignored otherwise. See [proxy modes](https://docs.speedscale.com/getting-started/installation/sidecar/proxy-modes/) for more information on how each mode functions.

*   Accepted Values:
    *   `transparent` (default)
    *   `reverse`
    *   `forward`
    *   `dual`

* * *

<a id="sidecarspeedscalecomproxy-protocol"></a>

### `sidecar.speedscale.com/proxy-protocol`

Set the protocol clients should use when connecting to the sidecar when operating in one of `reverse`, `forward`, or `dual` proxy types. This setting is ignored if `proxy-type` is `transparent`. See [proxy modes](https://docs.speedscale.com/getting-started/installation/sidecar/proxy-modes/) for more information.

*   Accepted Values:
    *   `tcp` (only valid for `reverse` proxies)
    *   `http` (default)
    *   `socks`
    *   `tcp:http` (only valid for `dual` proxies)
    *   `tcp:socks` (only valid for `dual` proxies)

* * *

<a id="sidecarspeedscalecomproxy-host"></a>

### `sidecar.speedscale.com/proxy-host`

Sets the host to where the sidecar should forward inbound traffic. This is only valid when `capture-mode` is set to `proxy` and if `proxy-type` is either `reverse` or `dual`. Ignored otherwise.

*   Default: `localhost`

* * *

<a id="sidecarspeedscalecomproxy-port"></a>

### `sidecar.speedscale.com/proxy-port`

Sets the port to where the sidecar should forward inbound traffic. This is only valid when `capture-mode` is set to `proxy` and if `proxy-type` is either `reverse` or `dual`. Ignored otherwise.

*   Default: `80`

* * *

<a id="sidecarspeedscalecomproxy-in-port"></a>

### `sidecar.speedscale.com/proxy-in-port`

Sets the listening port exposed by the sidecar for proxying inbound traffic. Only valid when operating as a reverse proxy with proxy types `transparent`, `reverse`, and `dual`.

*   Default: `4143`

* * *

<a id="sidecarspeedscalecomproxy-out-port"></a>

### `sidecar.speedscale.com/proxy-out-port`

Sets the listening port exposed by the sidecar for proxying outbound traffic. Only valid when operating as a forward proxy with proxy types `transparent`, `forward`, and `dual`.

*   Default: `4140`

* * *

<a id="sidecarspeedscalecomtls-out"></a>

### `sidecar.speedscale.com/tls-out`

Enables or disables TLS outbound interception and unwrapping. If disabled, encrypted traffic will not be viewable in the Speedscale UI. See [TLS](https://docs.speedscale.com/getting-started/installation/sidecar/tls/) for more information.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomtls-java-tool-options"></a>

### `sidecar.speedscale.com/tls-java-tool-options`

Configures the operator to add `JAVA_TOOL_OPTIONS` with TLS certificate overrides as additional container env vars. This setting is only used when `tls-out` is enabled. It only covers Java truststore configuration and does not configure outbound proxy routing for `forward` or `dual` proxy modes.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomtls-java-tool-options-value"></a>

### `sidecar.speedscale.com/tls-java-tool-options-value`

Overrides `JAVA_TOOL_OPTIONS` with a custom value. Use this when you need the operator to write the full merged JVM flag string, such as proxy flags, truststore flags, and your existing application-specific Java options.

If both `sidecar.speedscale.com/tls-java-tool-options` and `sidecar.speedscale.com/tls-java-tool-options-value` are set, the custom value takes precedence.

* * *

<a id="sidecarspeedscalecomtls-in-secret"></a>

### `sidecar.speedscale.com/tls-in-secret`

Kubernetes [TLS secret](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) containing the TLS private key and public certificate that should be used for inbound client requests. Setting this enables inbound TLS interception and unwrapping. See [TLS](https://docs.speedscale.com/getting-started/installation/sidecar/tls/) for more information.

* * *

<a id="sidecarspeedscalecomtls-in-private"></a>

### `sidecar.speedscale.com/tls-in-private`

If `tls-in-secret` is provided, this is the filename of the TLS private key. If it is not provided, this must be a full path to the TLS private key file already mounted in the container.

*   Default: `tls.key`

* * *

<a id="sidecarspeedscalecomtls-in-public"></a>

### `sidecar.speedscale.com/tls-in-public`

If `tls-in-secret` is provided, this is the filename of the TLS public key. If it is not provided, this must be a full path to the TLS public key file already mounted in the container.

*   Default: `tls.crt`

* * *

<a id="sidecarspeedscalecomtls-mutual-secret"></a>

### `sidecar.speedscale.com/tls-mutual-secret`

Kubernetes [TLS secret](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) containing the client TLS private key and public certificate that should be used for outbound requests requiring mutual TLS. Do not set this unless your application uses mutual TLS. See [TLS](https://docs.speedscale.com/getting-started/installation/sidecar/tls/) for more information.

* * *

<a id="sidecarspeedscalecomtls-mutual-private"></a>

### `sidecar.speedscale.com/tls-mutual-private`

If `tls-mutual-secret` is provided, this is the filename of the TLS private key. If it is not provided, this must be a full path to the TLS private key file already mounted in the container.

*   Default: `tls.key`

* * *

<a id="sidecarspeedscalecomtls-mutual-public"></a>

### `sidecar.speedscale.com/tls-mutual-public`

If `tls-mutual-secret` is provided, this is the filename of the TLS public key. If it is not provided, this must be a full path to the TLS public key file already mounted in the container.

*   Default: `tls.crt`

* * *

<a id="sidecarspeedscalecomignore-src-ips"></a>

### `sidecar.speedscale.com/ignore-src-ips`

Comma separated list of inbound IPv4 addresses or IPv4 CIDR blocks that should be **excluded** from the traffic captured by the sidecar. Inbound requests from these sources will bypass the proxy entirely and will route directly to your application. Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

*   Example: `sidecar.speedscale.com/ignore-src-ips: "10.10.0.40,10.200.10.0/24"`

tip

To have _ALL_ inbound traffic to your application bypass the sidecar entirely, use the following format:

```text
sidecar.speedscale.com/ignore-src-ips: "*"
```

* * *

<a id="sidecarspeedscalecomignore-src-hosts"></a>

### `sidecar.speedscale.com/ignore-src-hosts`

Comma separated list of hostnames whose traffic should be **excluded** from the traffic captured by the sidecar. Inbound requests from these sources will bypass the proxy entirely and will route directly to your application. Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

caution

`iptables` performs a DNS lookup when adding hostnames to rules and only does so **once** when the rule is added. DNS changes that modify a host's source IP address will cause its traffic to no longer bypass the sidecar.

*   Example: `sidecar.speedscale.com/ignore-src-hosts: "example.com,mysvc.internal"`

* * *

<a id="sidecarspeedscalecomignore-inbound-ports"></a>

### `sidecar.speedscale.com/ignore-inbound-ports`

Comma separated list of port numbers whose traffic should be **excluded** from the traffic captured by the sidecar. Inbound requests to these ports will bypass the proxy entirely and will route directly to your application. Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

*   Example: `sidecar.speedscale.com/ignore-inbound-ports: "443,8888"`

* * *

<a id="sidecarspeedscalecomignore-dst-ips"></a>

### `sidecar.speedscale.com/ignore-dst-ips`

Comma separated list of outbound IPv4 addresses or IPv4 CIDR blocks that should be **excluded** from the traffic captured by the sidecar. Outbound requests to these destinations will bypass the proxy entirely and will route directly from your application to the intended destination. Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

*   Example: `sidecar.speedscale.com/ignore-dst-ips: "10.10.0.40,10.200.10.0/24"`

tip

To have _ALL_ outbound traffic from your application bypass the sidecar entirely, use the following format:

```text
sidecar.speedscale.com/ignore-dst-ips: "*"
```

* * *

<a id="sidecarspeedscalecomignore-dst-hosts"></a>

### `sidecar.speedscale.com/ignore-dst-hosts`

Comma separated list of hostnames whose traffic should be **excluded** from the outbound traffic captured by the sidecar. Outbound requests to these destinations will bypass the proxy entirely and will route directly from your application to the intended destination. Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

caution

`iptables` performs a DNS lookup when adding hostnames to rules and only does so **once** when the rule is added. DNS changes that modify a host's source IP address will cause its traffic to no longer bypass the sidecar.

*   Example: `sidecar.speedscale.com/ignore-dst-hosts: "example.com,mysvc.internal"`

* * *

<a id="sidecarspeedscalecomignore-outbound-ports"></a>

### `sidecar.speedscale.com/ignore-outbound-ports`

Comma separated list of port numbers whose traffic should be **excluded** from the traffic captured by the sidecar. Outbound requests to these ports will bypass the proxy entirely and will route directly from your application to the intended destination. Only valid if `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

*   Example: `sidecar.speedscale.com/ignore-outbound-ports: "27017"`

* * *

<a id="sidecarspeedscalecomignore-loopback"></a>

### `sidecar.speedscale.com/ignore-loopback`

If set to `true`, any traffic whose target is the loopback interface `lo`. This has the effect of discarding pod-local traffic **AND** [port forwarded](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/) traffic. Only valid when `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomtrack-loopback"></a>

### `sidecar.speedscale.com/track-loopback`

If set to `true`, instructs the sidecar to track and redirect outbound traffic based on its destination interface, specifically the loopback interface `lo`. Outbound traffic on `lo` will be redirected to `proxy-in-port`, while all other traffic is redirected to `proxy-out-port` as normal. Only valid when `capture-mode` is `proxy` and `proxy-type` is `transparent`, ignored otherwise.

tip

Enable this setting if you need to capture [port forwarded](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/) traffic.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomcpu-limit"></a>

### `sidecar.speedscale.com/cpu-limit`

CPU resource limit value for the sidecar container. Refer to [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) for more information about resource limits.

*   Default: unset
*   Recommended Value: `2`

* * *

<a id="sidecarspeedscalecomcpu-request"></a>

### `sidecar.speedscale.com/cpu-request`

CPU resource request value for the sidecar container. Refer to [CPU resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu) for more information about resource limits.

*   Default: 10m
*   Recommended Value: `10m`

* * *

<a id="sidecarspeedscalecommemory-limit"></a>

### `sidecar.speedscale.com/memory-limit`

Memory resource limit value for the sidecar container. Refer to [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) for more information about resource limits.

*   Default: unset
*   Recommended value: `1Gi`

* * *

<a id="sidecarspeedscalecommemory-request"></a>

### `sidecar.speedscale.com/memory-request`

Memory resource request value for the sidecar container. Refer to [Memory resource units](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory) for more information about resource limits.

*   Default: 32Mi
*   Recommended value: `32Mi`

* * *

<a id="sidecarspeedscalecomkube-api-support"></a>

### `sidecar.speedscale.com/kube-api-support`

When set to `true`, the sidecar will be configured to proxy and capture requests to the Kubernetes API. This feature is disabled by default and requires that `tls-out` is enabled. Use this if your application makes requests to the Kubernetes API that you want to observe and/or replay.

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomistio-cni"></a>

### `sidecar.speedscale.com/istio-cni`

Set this annotation to `true` if your Kubernetes cluster has Istio installed and configured to use the [Istio CNI Agent](https://istio.io/latest/docs/setup/additional-setup/cni/).

*   Accepted Values:
    *   `true`
    *   `false` (default)

* * *

<a id="sidecarspeedscalecomextra-container-env-vars"></a>

### `sidecar.speedscale.com/extra-container-env-vars`

Allows adding arbitrary environment variables into OTHER containers in a workload. These will be applied to your workload containers, NOT to the goproxy sidecar container. Each environment variable should be on a separate line.

*   Example to set multiple environment variables:

```text
    sidecar.speedscale.com/extra-container-env-vars: |-
      GRPC_GO_LOG_VERBOSITY_LEVEL=99
      GRPC_GO_LOG_SEVERITY_LEVEL=info
```

* * *

<a id="sidecarspeedscalecommount-known-ca"></a>

### `sidecar.speedscale.com/mount-known-ca`

Mounts the Speedscale cert to a list of well known locations for implicit trust for eg. `/etc/ssl/certs/ca-certificates.crt`. Note that existing files or mounts to these locations can cause conflicts and the use of environment variables is preferred.

*   Accepted Values:
    *   `true`
    *   `false` (default)
