mirrord Operator
How to install and manage the mirrord Operator, which runs in your cluster for Team and Enterprise.
The mirrord Operator is a Kubernetes operator that runs persistently in your cluster and manages mirrord sessions. It's the central component that enables all [Teams] features.
Why the Operator?
In the open-source version of mirrord, each session is standalone - mirrord injects itself into the local process and creates an agent pod directly. This works well for individual use, but doesn't support coordination between users.
The Operator solves this by acting as a centralized control plane:
Better security - Users no longer need permissions to create privileged pods. Only the Operator does. Permissions are managed through Kubernetes RBAC.
Concurrent use - The Operator coordinates multiple mirrord sessions on the same cluster, preventing conflicts.
Advanced features - Support for policies, profiles, queue splitting, DB branching, and more.
Installation
You'll need a mirrord for Teams license. Register here to get started. Once you have an organization, mirrord operator install logs you in, creates your organization's operator API key, and installs the Operator with the default Helm values. Creating the key needs an organization admin and works only while the organization has no operator API key yet; otherwise, install with mirrord operator install --api-key <key>. For anything custom, use the Helm chart below.
Requirements
Before you install the Operator, make sure that your cluster and network meet these requirements.
Kubernetes version
The Operator needs Kubernetes 1.22 or later. Some features need a newer version. See Cluster Requirements.
Permissions
The Helm chart makes cluster-scoped objects: CRDs, ClusterRoles, an APIService, and a PriorityClass for agent pods. The user who installs the chart needs permission to make these objects. In most clusters, this is the cluster-admin role.
Nodes
The Operator and agent images are available for
linux/amd64andlinux/arm64.The nodes where agents run need Linux kernel 5.4 or later and a containerd, CRI-O, or Docker container runtime. Most features work with older kernels, but traffic stealing can be unreliable before 5.4. An agent for a target runs on the same node as the target pod. A targetless agent can run on any node.
Network
API server to Operator: The Kubernetes API server sends mirrord requests to the Operator through the APIService. The API server must be able to reach the Operator pods over TCP, on the port in the
operator.portHelm value (443 by default). Private clusters often need a firewall rule for this. For an example, see this GKE issue.Operator to MetalBear: A cloud-connected Operator sends HTTPS requests to
app.metalbear.com(license) andanalytics.metalbear.com(telemetry). Team and Free licenses require telemetry. If the Operator cannot reach the telemetry endpoint for more than one hour, new sessions are blocked. For Enterprise licenses, telemetry is optional. For more details, see Licensing. If your cluster cannot send outbound traffic, you need an Enterprise license certificate (license.pem). Give it to the Operator directly (see Air-gapped / offline clusters), or install it in an Enterprise License Server that your Operators connect to.Image pulls: Your nodes pull the mirrord images from
ghcr.io/metalbear-co. Some features use other public images, for example the database images for DB branching. If your nodes cannot reach these registries, see Using an Internal Registry.
Resources
The Operator runs as one pod by default. Agents run only while sessions use them. For the default CPU and memory values, see Scalability.
Helm
Add the MetalBear Helm repository:
Download the accompanying values.yaml:
Cloud API key
The Operator authenticates to the mirrord cloud with a cloud API key and uses it to obtain its license over the API. This is the default way to install the Operator. Generate a key in the dashboard under Settings at app.metalbear.com — it's shown only once, so store it then.
If you have no organization yet and an AI agent is doing the install, Agent-Started Trials mints the same kind of key without a dashboard visit.
When generating the key you also choose whether to enable identity sharing. With it on, usage metrics include developer usernames and session targets so the usage dashboard can show them by name; with it off, usage metrics stay anonymized. The fields are listed under What data does the Operator send to MetalBear cloud. Set cloud.anonymizeData: true in your Helm values to keep metrics anonymized regardless of the key.
Provide the key to the chart in one of three ways:
Kubernetes secret (recommended) — reference a secret via cloud.apiKey.keyRef, so the key never lives in your values.yaml:
This only points the chart at a secret name, it doesn't require the secret to exist yet. Install the chart first (this also creates the mirrord namespace), then create the secret in it:
The Operator pod will wait until the secret exists and start automatically once it's created, no restart needed. If you create the secret before installing instead, make sure the mirrord namespace already exists and is Helm-managed, otherwise helm install will fail to adopt it.
Google Secret Manager — store the key in GSM and reference it via cloud.apiKey.gsmRef. The Operator reads it using Application Default Credentials (see sa.gcpSa):
Inline (dev/test) — set the value directly, keeping in mind it then lives in your Helm values:
Then install:
Rotating and revoking the key are done from the dashboard. When you revoke, you can choose a grace window so the current key keeps working while you roll the Operator over to the new one.
Air-gapped / offline clusters (Enterprise)
Air-gapped or offline clusters can't reach the cloud to exchange an API key for a license, so Enterprise deployments in that situation use an offline license certificate instead. If you have a license.pem file, set license.file.secret.data.license.pem in values.yaml using a YAML literal block:
Alternatively, reference a Kubernetes secret via license.pemRef in values.yaml:
This only points the chart at a secret name, it doesn't require the secret to exist yet. Install the chart first (this also creates the mirrord namespace), then create the secret in it:
The Operator pod will wait until the secret exists and start automatically once it's created, no restart needed. If you create the secret before installing instead, make sure the mirrord namespace already exists and is Helm-managed, otherwise helm install will fail to adopt it.
For a fully self-hosted setup, see the license server.
License key
Set license.key to your key, then install:
Alternatively, reference a Kubernetes secret via license.keyRef in values.yaml:
This only points the chart at a secret name, it doesn't require the secret to exist yet. Install the chart first (this also creates the mirrord namespace), then create the secret in it:
The Operator pod will wait until the secret exists and start automatically once it's created, no restart needed. If you create the secret before installing instead, make sure the mirrord namespace already exists and is Helm-managed, otherwise helm install will fail to adopt it.
Using an Internal Registry (Optional)
Using an internal registry reduces startup time, ingress costs, and removes dependency on GitHub's registry.
Feature-specific images
These images are only pulled when the corresponding feature is enabled:
Kafka splitting sidecar
ghcr.io/metalbear-co/operator-kafka-proxy
Same as operator
JVM sidecar for Kafka splitting (only when operator.kafkaSplittingSidecar.enabled is true).
operator.kafkaSplittingSidecar.image
MSSQL tools
ghcr.io/metalbear-co/mssql-tools
latest
Sidecar for MSSQL DB branching (provides sqlcmd, sqlpackage, bcp).
Env MSSQL_TOOLS_IMAGE via operator.extraEnv
Flyway
flyway/flyway
12
Flyway migration runner for DB branching.
Per-branch migrations.image, or dbPod.migrationImages.flyway.registry
Liquibase
liquibase/liquibase
4.33
Liquibase migration runner for DB branching.
Per-branch migrations.image, or dbPod.migrationImages.liquibase.registry
DB branching default database images
DB branch pods pull a database image matching the engine. These are the defaults when no custom image is specified in the branch config:
PostgreSQL
docker.io/library/postgres:{version}
operator.pgBranchConfig - dbPod.image
MySQL
docker.io/library/mysql:{version}
operator.mysqlBranchConfig - dbPod.image
MariaDB
docker.io/library/mariadb:{version}
operator.mariadbBranchConfig - dbPod.image
MongoDB
docker.io/library/mongo:{version}
operator.mongodbBranchConfig - dbPod.image
MSSQL
mcr.microsoft.com/mssql/server:{version}
operator.mssqlBranchConfig - dbPod.image
Redis
docker.io/library/redis:{version}
operator.redisBranchConfig - dbPod.image
DynamoDB
amazon/dynamodb-local:{version}
operator.dynamodbBranchConfig - dbPod.image
ClickHouse
docker.io/clickhouse/clickhouse-server:{version}
operator.clickhouseBranchConfig - dbPod.image
CockroachDB
docker.io/cockroachdb/cockroach:{version}
operator.cockroachdbBranchConfig - dbPod.image
Spanner
gcr.io/cloud-spanner-emulator/emulator:{version}
operator.spannerBranchConfig - dbPod.image
Generic branches have no default image - the user supplies the full image reference per branch. Admins can restrict which images are allowed with the allowedImages glob list under operator.genericBranchConfig - dbPod.allowedImages (when absent, all images are allowed), and imagePullSecrets in the same config covers private registries.
DB branching migration Job environment
Container-flavor migration Jobs inherit the target container's env and envFrom by default, with the declared connection variables redirected to the branch. dbPod.migrationEnv on every <db>BranchConfig controls this: inherit: false opts out, and env/envFrom add admin-supplied values in plain Kubernetes shapes (so valueFrom/secretRef keep secret values in-cluster). See Schema Migrations for the full behavior and precedence.
Copying images
We recommend regctl for copying multi-arch images:
Then set in your values.yaml:
OpenShift
Apply the following SecurityContextConstraints:
GKE Autopilot
In GKE Autopilot the mirrord Operator can be run as a customer-owned privileged workload.
mirrord is an approved GKE Autopilot partner. Because of this, you should not manually apply a WorkloadAllowlist for the mirrord-agent workload: GKE Autopilot clusters reject direct manual installation of it with an admission error. Manual installation only worked previously in specially-configured test projects, not in standard customer clusters.
Instead, apply the following AllowlistSynchronizer, which automatically syncs the current and future approved versions of the mirrord-agent allowlist:
Note: some Operator configurations might produce mirrord-agent pods that don't match this specification. When that happens, you'll see agent spawn errors in the Operator logs. To get the correct WorkloadAllowlist embedded in those error messages, merge this snippet into your mirrord Operator values.yaml:
Verifying the Installation
All mirrord clients will now use the Operator automatically when running against the cluster.
Last updated
Was this helpful?

