Preview Environments

Ephemeral, Isolated Environments Connected to Your Cluster

Preview Environments let you deploy a new version of your code into the cluster as an isolated pod. The pod can communicate with its dependencies in the cluster and receive filtered traffic without affecting other users or live services. Unlike a regular mirrord session, a preview environment is not tied to a local process. It stays alive for a configurable TTL, making it suitable for sharing with teammates, QA, or product managers who need to validate changes asynchronously.

This feature is available to users on the Enterprise pricing plan.

With a regular mirrord session, the test environment disappears when your local process stops. Preview environments solve this: the code runs in-cluster, so it keeps serving traffic regardless of what's happening on your machine. Multiple preview environments can run side by side, each receiving only the traffic intended for them.

Prerequisites

Before you start, make sure you have:

1. Minimum versions installed: Operator 3.142.0, mirrord CLI 3.189.0 with operator.previewEnv value set to true in your chart's values.yaml.

2. The mirrord operator must be installed in the cluster with an Enterprise license.

3. The container image for the service you want to run in the preview environment must be pre-built and pushed to a registry accessible by the cluster.

Configuration

Preview environments are configured through the standard mirrord configuration file. The preview-specific fields live under feature.preview:

{
  "key": "key-my-feature",
  "target": {
    "path": "deployment/my-app",
    "namespace": "staging"
  },
  "feature": {
    "preview": {
      "image": "my-registry/my-app:feature-branch",
      "ttl_mins": 60
    },
    "network": {
      "incoming": {
        "mode": "steal",
        "http_filter": {
          "header_filter": "x-traffic: {{ key }}"
        }
      }
    }
  }
}

The target specifies which existing workload to clone the pod spec from. The operator creates a new pod using that spec but with your preview.image instead. The preview pod runs inside the cluster with native access to the cluster's network, DNS, and environment, matching the configuration and traffic behavior of the existing target.

Environment Key

Each preview environment is identified by a key (the key field). The key can be referenced in HTTP filters and other configuration fields as the template variable {{ key }}. This makes it possible to:

• Scope HTTP and queue traffic filtering to a specific preview

• Scope database branches to the preview session

• Associate multiple preview pods into a single environment

• Share access to the same environment with other teammates

If no key is provided, mirrord generates a random UUID automatically.

With the configuration above, {{ key }} is replaced with key-my-feature at load time, so only requests containing the header x-traffic: key-my-feature are routed to the preview pod.

Traffic Modes

Preview environments support the same incoming traffic modes as regular mirrord sessions:

• Stealing: requests matching an HTTP filter are redirected to the preview pod instead of the original target. Other traffic is unaffected. This is the most common mode for preview environments.

• Mirroring (filtered or unfiltered): a copy of incoming traffic is sent to the preview pod. The preview pod's responses are discarded, the original target still serves all real traffic. Useful for observing how new code handles production-like requests without any risk of disruption.

Unfiltered stealing is not supported for preview environments. If you use steal mode, you must configure an HTTP filter to scope which requests the preview pod receives.

Here is an example using unfiltered mirroring:

{
  "key": "key-my-feature",
  "target": {
    "path": "deployment/my-app",
    "namespace": "staging"
  },
  "feature": {
    "preview": {
      "image": "my-registry/my-app:feature-branch"
    },
    "network": {
      "incoming": {
        "mode": "mirror"
      }
    }
  }
}

In this mode, all traffic to the target is duplicated to the preview pod, but the original target still serves every response.

Starting a Preview Environment

The mirrord preview start command creates a preview environment from a configuration file:

$ mirrord preview start -f mirrord.json

To view the entire list of arguments, run mirrord preview start --help.

The image and target can also be provided via CLI flags (-i for image, -t for target, -k for key), which override the corresponding configuration file fields.

Once the preview pod is ready, you'll see a summary:

  ✓ mirrord preview start
    ✓ configuration loaded
    ✓ connected to operator
    ✓ preview session resource created
    ✓ preview pod is ready
  info:
    * key: key-my-feature
    * namespace: staging
    * pod: preview-session-deployment-my-app-a1b2c3d4

At this point, the preview pod is running in the cluster and receiving traffic according to your configuration. You can share the key with teammates so they can route their requests to the preview, for example by using the browser extension.

Checking Status

Use mirrord preview status to see active preview environments:

$ mirrord preview status
  ✓ mirrord preview status
    ✓ configuration loaded
    ✓ found 2 sessions
  key-my-feature:
    * preview-pod-deployment-my-app-a1b2c3d4 (deployment/my-app @ staging): running
  key-another-feature:
    * preview-pod-deployment-api-e5f6g7h8 (deployment/api @ staging): running

Sessions are grouped by key. You can filter by key with -k or by namespace with -n.

Stopping a Preview Environment

When you're done, stop the preview environment by key:

$ mirrord preview stop --key key-my-feature
  ✓ mirrord preview stop
    ✓ configuration loaded
    ✓ found 1 session to delete
    ✓ all sessions deleted

This removes the preview pod and all associated resources from the cluster. If you don't stop it manually, the session will be automatically cleaned up when its TTL expires.

Current Limitations

• No in-place updates: you can't update the image or configuration of a running preview session. To deploy a new version, stop the existing session and start a new one.

• Targetless mode not yet supported: preview environments currently require a target workload to clone the pod spec from. Support for targetless preview environments, creating a fresh, isolated pod without an existing target, is not yet available.