The Speedscale Operator is a Kubernetes operator that watches for deployments to be applied to the cluster and takes action based on annotations. The operator can inject a proxy to capture traffic into or out of applications, or setup an isolation test environment around a deployment for testing. The operator itself is a deployment that will be always present on the cluster once the helm chart is installed.
- Kubernetes 1.20+
- Helm 3+
- Appropriate network and firewall configuration for Speedscale cloud and webhook traffic
helm repo add speedscale https://speedscale.github.io/operator-helm/
helm repo updateSee helm repo for command documentation.
An API key is required. Sign up for a free Speedscale trial if you do not have one.
helm install speedscale-operator speedscale/speedscale-operator \
-n speedscale \
--create-namespace \
--set apiKey=<YOUR-SPEEDSCALE-API-KEY> \
--set clusterName=<YOUR-CLUSTER-NAME>See helm install for command documentation.
Use the same chart in a pre-existing namespace when cluster-scoped permissions, CRDs, and admission webhooks are unavailable. Create the API key Secret in that namespace first with a SPEEDSCALE_API_KEY key. The namespaced mode does not create the Secret. Set namespaced.appUrl to dev.speedscale.com or staging.speedscale.com only for environment tests; the default is app.speedscale.com.
helm install speedscale-operator speedscale/speedscale-operator \
-n <NAMESPACE> \
--set namespaced.enabled=true \
--set namespaced.apiKeySecret=speedscale-apikey \
--set namespaced.clusterName=<YOUR-CLUSTER-NAME>In this mode, the chart renders namespace-scoped resources only. Use proxymock for explicit sidecar injection and replay. eBPF capture requires node-level access and is unavailable in this mode. Inspect the rendered manifests with helm template --include-crds before installation.
Kubernetes permission scope does not choose where records are stored. namespaced.forwarder.primaryTransport defaults to aws. Set it to cloud only for Speedscale Cloud storage through the configured application host. Customer-owned BYOC report storage requires a separately configured destination.
Set image.registry to mirror Speedscale images in your registry. To select Redis or Java independently, supply full image references in a values file:
replayComponents:
redis:
image: registry.example.com/cache/redis:7.4
jks:
image: registry.example.com/java/amazoncorretto:23
image:
pullSecrets:
- name: registry-credentialsPass the file with helm install -f values.yaml or helm upgrade -f values.yaml. Image references may include tags or digests. Empty overrides retain the existing registry and tag defaults, including imageTags.redis.
The Redis image must provide redis-server on PATH and accept the standard Redis 7.4 command-line options. The operator starts it directly with persistence disabled; image entrypoint scripts are bypassed.
The Java image must provide a Java 11+ runtime on PATH and a readable default truststore with password changeit. Set jks.truststorePath if the image stores its truststore elsewhere. The chart mounts a compiled Java program that preserves the image's CA certificates, adds the Speedscale CA, and creates or patches speedscale-jks using the Job's Kubernetes service account. No compiler, shell, kubectl, curl, or operator helper command is required. Existing Secret metadata and unrelated data keys are preserved, and non-certificate entries in the source truststore are skipped. Provisioning failures fail the Job; an existing Secret is replaced only when it rejects the patch, for example because it is immutable.
The Job runs under the chart's globalPodSecurityContext and globalSecurityContext (non-root, read-only root filesystem), so a custom jks.image must expose a truststore readable by that UID. Existing registry defaults and service-mesh settings are retained. The program attempts the existing Istio shutdown request before exiting. The Job does not depend on the operator image version. createJKS: false continues to support a pre-provisioned Secret.
Create pull Secrets in the installation namespace before installing. The operator adds them to replay components and to every workload it injects a sidecar into, so the Secret must also exist in each of those namespaces. Changing replayComponents or imageTags restarts the operator so subsequent replays use the new configuration. Truststore creation remains a pre-install hook; changing the Java image during an upgrade does not regenerate an existing truststore.
We use pre-install job to check provided API key and provision some of the required resources.
If the job failed during the installation, you'll see the following error during install:
Error: INSTALLATION FAILED: failed pre-install: job failed: BackoffLimitExceeded
You can inspect the logs using this command:
kubectl -n speedscale logs job/speedscale-operator-pre-installAfter fixing the error, uninstall the helm release, delete the failed job and try installing again:
helm -n speedscale uninstall speedscale-operator
kubectl -n speedscale delete job speedscale-operator-pre-installhelm -n speedscale uninstall speedscale-operatorThis removes all the Kubernetes components associated with the chart and deletes the release.
See helm uninstall for command documentation.
CRDs created by this chart are not removed by default and should be manually cleaned up:
kubectl delete crd trafficreplays.speedscale.comhelm repo update
helm -n speedscale upgrade speedscale-operator speedscale/speedscale-operatorResources capturing traffic will need to be rolled to pick up the latest Speedscale sidecar. Use the rollout restart command for each namespace and resource type:
kubectl -n <namespace> rollout restart deploymentWith Helm v3, CRDs created by this chart are not updated by default and should be manually updated. Consult also the Helm Documentation on CRDs.
See helm upgrade for command documentation.
A major chart version change (like v1.2.3 -> v2.0.0) indicates that there is an incompatible breaking change needing manual actions.
Speedscale docs information available at docs.speedscale.com or join us on the Speedscale community Slack!