Skip to main content

Kubernetes Annotations

Below are all the relevant Kubernetes annotations for Speedscale.

Sidecar Annotations

These annotations relate to the proxy sidecar that the Speedscale operator attaches to your workload.

sidecar.speedscale.com/inject

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

  • Accepted Values:
    • true
    • false (default)

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)

sidecar.speedscale.com/capture-mode

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

  • Accepted Values
    • proxy (default)

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)

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

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 for more information on how each mode functions.

  • Accepted Values:
    • transparent (default)
    • reverse
    • forward
    • dual

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

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

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

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

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

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 for more information.

  • Accepted Values:
    • true
    • false (default)

sidecar.speedscale.com/tls-in-secret

Kubernetes TLS secret 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 for more information.


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

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

sidecar.speedscale.com/tls-mutual-secret

Kubernetes TLS secret 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 for more information.


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

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

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:

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

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"

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"

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:

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

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"

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"

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 traffic. Only valid when capture-mode is proxy and proxy-type is transparent, ignored otherwise.

  • Accepted Values:
    • true
    • false (default)

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 traffic.

  • Accepted Values:
    • true
    • false (default)

sidecar.speedscale.com/cpu-limit

CPU resource limit value for the sidecar container. Refer to CPU resource units for more information about resource limits.

  • Default: unset
  • Recommended Value: 2

sidecar.speedscale.com/cpu-request

CPU resource request value for the sidecar container. Refer to CPU resource units for more information about resource limits.

  • Default: 10m
  • Recommended Value: 10m

sidecar.speedscale.com/memory-limit

Memory resource limit value for the sidecar container. Refer to Memory resource units for more information about resource limits.

  • Default: unset
  • Recommended value: 1Gi

sidecar.speedscale.com/memory-request

Memory resource request value for the sidecar container. Refer to Memory resource units for more information about resource limits.

  • Default: 32Mi
  • Recommended value: 32Mi

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)

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.

  • Accepted Values:
    • true
    • false (default)

Replay Annotations

These annotations control traffic replay for your workload.

replay.speedscale.com/env-id

Name of the TrafficReplay Custom Resource tied to a replay for this workload. This value is automatically assigned by the Speedscale operator.


replay.speedscale.com/snapshot-id

ID of the Snapshot that is used to recreate traffic.

  • Accepted Values: any valid snapshot UUID

replay.speedscale.com/testconfig-id

ID of the test configuration used to recreate to traffic.


replay.speedscale.com/build-tag

Optional unique tag, build hash, etc. to attach to the Speedscale report. Use this as a way to correlate Speedscale report results to the version of your code that was tested.


replay.speedscale.com/mode

Configure how a traffic replay will test your system by instructing the Speedscale operator to deploy either generators to recreate observed requests TO your application, or responders to recreate observed responses to requests FROM your application, or both. Setting this to full-replay, both generators and responders are deployed, while generator-only will only deploy generators. Setting this to responder-only will only responders which will run indefinitely until removed.

  • Accepted Values:
    • full-replay (default)
    • generator-only
    • responder-only

replay.speedscale.com/timeout

Specifies the maximum amount of time a generator for a replay is allowed to be idle (i.e. fails to send a heartbeat event) before the Speedscale operator forcibly ends the replay. This does NOT enforce a static timeout for the replay itself. Ignored when replay mode is responder-only.

  • Default: 20m
  • Accepted Values: a valid duration string according to Go's ParseDuration() function

replay.speedscale.com/secrets

Comma separated list of Kubernetes secrets such as JWT tokens, passwords, etc. to attach as volume mounts to deployed generators and responders.


replay.speedscale.com/cleanup

Configures how the Speedscale operator cleans up provisioned resources after a traffic replay. If set to inventory, the operator removes objects related to Speedscale's replay of traffic, as well as reverts changes to the SUT. If set to all, the operator removes all replay objects, as well as the SUT. If set to none, the operator will leave all resources on the system after a replay.

  • Accepted Values:
    • inventory (default)
    • all
    • none

replay.speedscale.com/sut-url

Overrides the SUT URL determinited automatically by the generator when replaying traffic. This is useful if you have customized your service definition.

  • Accepted Values: a valid URL

replay.speedscale.com/generator-low-data

If set to true, the generator is forced into a high efficiency/low data output mode in which individual transaction assertions are disabled and only overall replay aggregates are calculated and reported.

tip

This setting is ideal and recommended for high volume performance tests.

  • Accepted Values:
    • true
    • false (default)

replay.speedscale.com/responder-low-data

If set to true, the responder is forced into a high efficiency/low data output mode in which individual transaction assertions are disabled and only overall replay aggregates are calculated and reported.

tip

This setting is ideal and recommended for high volume performance tests.

  • Accepted Values:
    • true
    • false (default)

Important

The operator will remove all listed replay annotations from the workload during admission review and move them into an associated TrafficReplay Custom Resource. This prevents side effects such as the operator observing and executing the same replay after it has finished. It also allows subsequent runs of the same replay by applying the same manifests, or incorporating the annotations into a GitOps workflow.

Common Annotations

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

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)

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.


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.