Skip to main content

Install the standard Kubernetes operator

The Speedscale operator runs in your cluster and manages the components used to capture and replay traffic. This installation creates cluster-scoped RBAC, a Speedscale CRD, and admission webhooks. If your installer can write only in one existing namespace, use the namespace-scoped installation. See Kubernetes installation options to compare both modes.

Prerequisites​

  • A Kubernetes cluster and kubectl access with permission to install cluster-scoped resources.
  • A service account API key from Tenant Settings. Ask a tenant administrator to create one if needed.
  • Helm 3 for the Helm and rendered-manifest methods, or speedctl for the CLI method.
  • The network access described in Evaluation prerequisites.

Check platform requirements before installing on OpenShift, GKE Autopilot, EKS Auto Mode, or a cluster running Istio. The Helm and manifest examples below enable eBPF capture; confirm the eBPF system requirements first. Use the platform-specific values where required.

Install with your coding agent​

This platform install deliberately installs both speedctl and proxymock. For proxymock alone without cluster setup, use the proxymock-only agent install.

Let your coding agent (Claude Code, Cursor, Codex, Gemini CLI, Kiro, or any assistant that can read a URL and run commands) do the whole install. Paste this into the chat:

Install Speedscale for me. First fetch the agent skill at
https://raw.githubusercontent.com/speedscale/skills/main/skills/install-speedscale/SKILL.md
and the references/ and scripts/ files it links to (same base URL), save them
under your skills directory, then follow the skill. Ask me before touching a
Kubernetes cluster.

The install-speedscale skill follows the same steps as the manual install below. It installs speedctl and proxymock, adds Helm and kubectl if they are missing, sets up your API key without ever printing it, and picks Helm values for your platform (EKS, GKE, AKS, minikube, kind, OpenShift). Then it verifies the operator and, only for the agent you select, offers to add the proxymock MCP server and bundled skills after previewing the paths. The agent announces every step that changes something before running it. It stops for you at browser sign-in and before touching a cluster whose name looks like production. With no cluster available, it installs just the CLIs.

Already have proxymock? proxymock mcp install --client claude-code --skills offers MCP and bundled skills for that selected client, preferring project scope. Add --dry-run to preview paths. You can also add it as a Claude Code plugin with /plugin marketplace add speedscale/skills, or add it to other agents with npx skills add speedscale/skills.

See Agent skills for the other skills.

Retrieve your API key​

For manual installation, use a service account API key so the cluster's access is independent of an employee's account. With the Helm, Argo CD, and rendered-manifest methods, create the namespace and load the key from a protected file into a Secret. Write the file without a trailing newline, for example printf %s "$KEY" > /secure/path/to/key; a newline becomes part of the key and authentication fails:

kubectl create namespace speedscale
kubectl -n speedscale create secret generic speedscale-apikey \
  --from-file=SPEEDSCALE_API_KEY=/secure/path/to/key \
  --from-literal=SPEEDSCALE_APP_URL=app.speedscale.com

If the namespace or Secret already exists, use your platform's provisioning process to manage it. For speedctl install, supply the service account key when prompted by the wizard.

Choose an installation method​

For Helm and rendered manifests, add the public chart repository:

helm repo add speedscale https://speedscale.github.io/operator-helm/
helm repo update

Create speedscale-values.yaml with your cluster name and any required platform settings. The key itself stays in the Secret:

apiKeySecret: speedscale-apikey
clusterName: YOUR-CLUSTER-NAME
ebpf:
  enabled: true

Use ebpf.enabled: false if your cluster cannot run eBPF and follow the sidecar fallback. Review the chart's install and upgrade lifecycle for resource ownership, hooks, and CRD handling.

Install with the values file:

helm install speedscale-operator speedscale/speedscale-operator \
  --namespace speedscale \
  --values speedscale-values.yaml

Keep this values file for upgrades. See the Helm values reference for additional configuration.

Verify installation​

Check that the operator and forwarder pods are running:

kubectl -n speedscale get pods

Expect at least the operator and forwarder pods in Running state; the suffixes differ on your cluster:

NAME                                    READY   STATUS    RESTARTS   AGE
speedscale-forwarder-xxxxxxxxxx-xxxxx   1/1     Running   0          5s
speedscale-operator-xxxxxxxxxx-xxxxx    1/1     Running   0          15s

When eBPF is enabled, also check the collector pods:

kubectl -n speedscale get pods -l app=speedscale-nettap

If proxymock is installed, check component readiness, connectivity, and your kubeconfig permissions:

proxymock cluster status --speedscale-namespace speedscale

For failures, see installation troubleshooting or ask in the Speedscale Community.

Kerberos cloud proxy​

If your outbound proxy requires Kerberos, follow Kerberos proxy authentication to configure the operator override and mount credentials. The operator propagates these settings to forwarder and inspector.

Private registry images​

If your organization requires approved Redis or Java runtime images, configure replayComponents.redis.image and jks.image in your Helm values. The Helm values reference covers runtime requirements and truststore behavior, with a private registry example for Artifactory.

Next steps​

Use the tutorial to record and replay a demo application, or follow cluster capture and replay with proxymock. See eBPF capture targets to select workloads for capture.