Replay With speedctl

speedctl gives you the options of running a replay locally or against a deployment in a cluster.

Replay in a Cluster

Whether it's the same cluster where you captured traffic or a different one, you need an active inspector in your cluster.

speedctl infra replay --snapshot-id {snapshot_id} --cluster {cluster_name} --service {workload_name}

This runs a replay against your workload in the specified cluster. Run speedctl infra replay --help to see all available flags.

Namespace inference

If --namespace is omitted and the snapshot was captured from a single namespace, that namespace is inferred automatically. If the snapshot spans multiple namespaces you must pass --namespace.

Wait for service mocks

Use speedctl wait replay before an external test driver sends traffic. This workflow requires Speedscale v2.5.789 or newer in the cluster and speedctl v2.5.789 or newer on the client. Older operators do not publish the MocksReady condition consumed by the CLI.

REPORT_ID=$(speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --namespace {namespace} \
  --service {workload_name} \
  --test-config-id {responder_only_test_config} \
  --id-only)

speedctl wait replay "$REPORT_ID" \
  --for mocks-ready \
  --timeout 10m \
  --poll-interval 5s

mocks-ready waits for operator provisioning, ready responder deployments, responder configuration, and the target workload. It does not wait for the Speedscale traffic generator. The command returns a nonzero exit code on failure or timeout.

Use a test config with cluster.replayMode set to responder-only when another tool will generate inbound traffic. This is separate from --mock-only, which selects a subset of outbound dependencies to mock during a replay.

Always cancel a responder-only replay when the driver finishes:

speedctl infra cancel-replay "$REPORT_ID"

See Use Your Existing Test Driver for a complete CI lifecycle with k6 and Postman.

Targeting Specific Services (--test-against)

You can map replay traffic to different endpoints. This is useful when you want to test a sub-system or a newer version of a service.

# Redirect all traffic to a single URL
speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --test-against http://example.com

# Override specific services while using a default
speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --service my-service \
  --test-against auth=auth.example.com \
  --test-against frontend=http://localhost:8080

Note: --test-against is mutually exclusive with specifying a positional {workload_name} argument.

---

Controlling Outbound Mocks

By default, speedctl infra replay mocks all outbound dependencies recorded in the snapshot. The flags below let you customize which outbound services are mocked.

--no-mocks

Disable all outbound mocking. Real outbound traffic is sent to downstream services.

speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --service my-service \
  --no-mocks

--mocks <mode>

Set a base mocking mode. Accepted values:

Mode	Behaviour
all	Mock all outbound services (default when flag is omitted)
none	Disable all mocks (same as --no-mocks)
external-only	Mock only external (non-cluster) services (not yet supported; falls back to all)
internal-only	Mock only internal (cluster) services (not yet supported; falls back to all)

--mock-only <selector>

Repeatable. Mock only the outbound services that match the given selectors — everything else is called live.

speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --service my-service \
  --mock-only 'svc:payments' \
  --mock-only 'host:api.stripe.com'

--mock-except <selector>

Repeatable. Start from the base mock mode (--mocks or all by default) and exclude matching services from being mocked.

speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --service my-service \
  --mock-except 'svc:db' \
  --mock-except 'glob:payments:*:443'

Selector syntax

--mock-only, --mock-except, and --exclude-in all accept the same selector formats:

Selector	Example	Matches
Exact key	payments:grpc:443	Exact out-service key
svc:<substring>	svc:payments	Keys containing the substring (case-insensitive)
host:<hostname>	host:api.stripe.com	Services with a matching recorded hostname
glob:<pattern>	glob:payments:*:443	Shell-style glob on the out-service key

Shell quoting

Wrap selectors in single quotes to prevent your shell from expanding globs or interpreting colons, e.g. --mock-only 'glob:payments:*:443'.

---

Excluding Inbound Services (--exclude-in)

Repeatable. Exclude specific inbound services from being replayed. All other inbound services are replayed normally.

speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --namespace staging \
  --service my-service \
  --exclude-in 'svc:frontend' \
  --exclude-in 'auth:auth.example.com:443'

Selectors use the same syntax as --mock-only/--mock-except (see table above).

---

Previewing the Mock Plan (--dry-run-mocks)

Resolve and print the mocking plan without starting a replay. Combine with -o pretty or -o json to control output format.

speedctl infra replay \
  --snapshot-id {snapshot_id} \
  --cluster {cluster_name} \
  --service my-service \
  --mock-only 'svc:payments' \
  --dry-run-mocks -o pretty

Example output:

Mocks: 2 out-service(s)
  - payments:grpc:443
  - payments:http:80

---

Advanced Mock Attachments

By default all mocks are attached to the workload specified by --service. The flags below allow mocks to be split across multiple workloads — useful in multi-service replay scenarios.

--mock-attach-default <workloadRef>

Override the default attachment workload for all mocks. Format: [<namespace>/]<type>/<name>.

--mock-attach-default staging/deployment/payments-sidecar

--mock-attach <selector>=<workloadRef>

Repeatable. Route mocks matching a selector to a specific workload.

--mock-attach 'svc:payments=staging/deployment/payments-sidecar' \
--mock-attach 'host:api.stripe.com=staging/deployment/stripe-proxy'

--mock-attach-file <path>

Load attachment rules from a YAML or JSON file. Accepts either a wrapper format or a bare array:

# wrapper format
mocks:
  - selector: "svc:payments"
    attach: "staging/deployment/payments-sidecar"
  - selector: "host:api.stripe.com"
    attach: "staging/deployment/stripe-proxy"

[
  { "selector": "svc:payments", "attach": "staging/deployment/payments-sidecar" }
]

---

Replay Locally

See the full guide on the CLI page.