Install and configure mirrord Operator for team use on Kubernetes. The skill covers licensing, access permissions, feature settings, internal registries, and offline deployments, with guidance for upgrades and troubleshooting across supported cluster platforms.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.
Help users install and configure the mirrord Operator for team/enterprise environments. Use when users ask about operator setup, Helm installation, cloud API key or license configuration, air-gapped/offline licensing, enabling features (queue splitting, DB branching, preview environments, multi-cluster), internal registries, OpenShift/GKE Autopilot, RBAC, or multi-user mirrord deployments. Also use when an AI agent hits a Team or Enterprise feature on a cluster with no license and needs to offer the user a trial (agent-started trial; the trial is Enterprise tier).
설치하기 전에 에이전트에게 전달되는 지시 내용을 확인할 수 있습니다.
Help users install and operate the mirrord Operator — the persistent Kubernetes control plane that enables all mirrord Team / Enterprise features:
In open-source mirrord each session is standalone (the CLI creates a privileged agent pod directly). The Operator centralizes this:
Trigger on questions like:
Feature X requires using mirrord operator or Operator not found on a cluster that has no mirrord for Teams licenseInstalling the operator modifies a shared cluster. Treat every operation as high-impact.
values.yaml. No cloud API keys, license keys, tokens, or PEM contents via --set or inline in committed values. Create a Kubernetes Secret and reference it (cloud.apiKey.keyRef, license.keyRef, license.pemRef), or use Google Secret Manager refs (cloud.apiKey.gsmRef, license.keyGsmRef, license.pemGsmRef).helm install/upgrade, kubectl create/apply, and RBAC commands for review and get explicit approval before running any of them. Do not run them automatically.-f values.yaml) for all structured input.references/troubleshooting.md — common operator issues and solutionsreferences/helm-values.md — curated digest of the important chart values (auth, feature flags, agent, TLS, registry, platform)references/values.yaml — verbatim upstream chart values.yaml, kept in sync automatically. Read this for exact current defaults or any value the digest doesn't list.Authoritative upstream sources:
values.yaml: https://raw.githubusercontent.com/metalbear-co/charts/main/mirrord-operator/values.yamlkubectl cluster-info # cluster reachable
helm version # Helm 3.x
kubectl auth can-i create deployments -n mirrord # sufficient RBAC (usually cluster-admin to install)
You also need a mirrord for Teams license. Register at app.metalbear.com. If there's no license yet, an agent can start a trial for the user once they agree — see No License Yet? Agent-Started Trials.
Check these before installing — most install failures trace back to one of them:
Kubernetes version: the Operator needs Kubernetes 1.22+. Some features need newer:
| Feature | Minimum Kubernetes version |
|---|---|
Agent as an ephemeral container (agent.ephemeral) | 1.23 |
AppArmor profile for the agent (agent.security_context) | 1.30 |
| Queue splitting | 1.30 |
| Multi-cluster | 1.30 on the Primary cluster |
| Multi-cluster preview replicas with DB branching | 1.29 on the workload clusters |
Permissions: the Helm chart creates cluster-scoped objects (CRDs, ClusterRoles, an APIService, a PriorityClass for agent pods). Whoever runs helm install needs permission to create these — in most clusters, the cluster-admin role.
Nodes: Operator and agent images are built for linux/amd64 and linux/arm64. Nodes where agents run need Linux kernel 5.4+ and a containerd, CRI-O, or Docker runtime — most features work on older kernels, but traffic stealing can be unreliable before 5.4. An agent for a target runs on that target pod's node; a targetless agent can run on any node.
Network:
operator.port (443 by default) through the APIService. Private clusters often need a firewall rule for this (see mirrord operator status fails with 503 on GKE).app.metalbear.com (license) and analytics.metalbear.com (telemetry). Team and Free licenses require telemetry — if it's unreachable for more than an hour, new sessions are blocked; Enterprise telemetry is optional. A cluster with no outbound access needs an Enterprise license certificate or a self-hosted license server — see Air-gapped / offline.ghcr.io/metalbear-co, plus other public images for some features (e.g. DB branch engine images). See Using an Internal Registry if nodes can't reach these registries.Resources: the Operator runs as one pod by default; agent pods run only while a session uses them. See Footprint & Agent Resources.
helm repo add metalbear https://metalbear-co.github.io/charts
helm repo update
curl https://raw.githubusercontent.com/metalbear-co/charts/main/mirrord-operator/values.yaml --output values.yaml
The operator needs credentials to obtain its license. Pick one path:
A. Cloud API key (default, recommended). The operator authenticates to the mirrord cloud with a cloud API key and obtains its license over the API. Generate the key in the dashboard under Settings at app.metalbear.com — it's shown only once. When generating it, an org admin also chooses identity sharing (ticked by default): with it on, usage metrics sent to the mirrord cloud include developer usernames and session targets so the usage dashboard can show them by name; with it off, metrics stay anonymized. Set cloud.anonymizeData: true in Helm values to keep metrics anonymized regardless of the key's setting. Provide the key one of three ways:
values.yaml. Point the chart at the secret name now (this doesn't require the secret to exist yet):
cloud:
apiKey:
keyRef: mirrord-operator-cloud-api-key
mirrord namespace), then have the user create the Secret in it. Write the key to a file (its exact contents, no trailing newline) and create the Secret with --from-file, so the key isn't exposed in the shell's process arguments (ps) or history — then delete the file. (Avoid --from-literal=apiKey=..., which places the key in argv.)
# apikey.txt holds only the key, with no trailing newline
kubectl create secret generic mirrord-operator-cloud-api-key \
--namespace mirrord --from-file=apiKey=./apikey.txt
rm apikey.txt
apiKey (what cloud.apiKey.keyRef expects). A stray trailing newline in the file becomes part of the key and breaks authentication. The operator pod waits for the Secret to appear and starts automatically once it's created — no restart needed. (If the user wants to create the Secret before installing instead, the mirrord namespace must already exist and be Helm-managed, or helm install will fail to adopt it.)cloud.apiKey.gsmRef: projects/PROJECT_ID/secrets/SECRET_NAME/versions/latest (read via Application Default Credentials; see sa.gcpSa).cloud.apiKey.key: <YOUR_API_KEY> (lands in the pod spec as plaintext; avoid for real clusters).Rotate/revoke from the dashboard (revocation supports a grace window so you can roll the operator to a new key).
B. License key (deprecated for cloud auth). Still valid for existing installs and required when using your own license server. Set license.key or reference a Secret via license.keyRef (Secret data key OPERATOR_LICENSE_KEY). New cloud installs should prefer the cloud API key.
C. Air-gapped / offline. See Air-gapped / offline.
helm install -f values.yaml mirrord-operator metalbear/mirrord-operator
(For upgrades, use helm upgrade --install ... -f values.yaml with the same release name.)
mirrord operator status # preferred — confirms clients can reach the operator
kubectl get pods -n mirrord # operator pod should be Running
Once installed, all mirrord clients use the Operator automatically when running against the cluster.
Most features are off by default and gated behind a Helm value under operator.*. Enable only what you need, then helm upgrade. See references/helm-values.md for the full list. Highlights:
| Feature | Helm value(s) |
|---|---|
| SQS queue splitting | operator.sqsSplitting: true |
| Kafka queue splitting | operator.kafkaSplitting: true (+ operator.kafkaSplittingSidecar.enabled for Kafka Streams / JVM clients) |
| RabbitMQ / GCP Pub/Sub / Azure Service Bus / Redis Pub/Sub / Temporal / BullMQ splitting | operator.rmqSplitting / gcpPubsubSplitting / azureServiceBusSplitting / redisPubsubSplitting / temporalSplitting / bullmqSplitting |
| DB branching (per engine) | operator.mysqlBranching, pgBranching, mariadbBranching, mongodbBranching, mssqlBranching, redisBranching, dynamodbBranching, clickhouseBranching, cockroachdbBranching, spannerBranching |
| Generic DB branching (user-supplied images) | operator.genericBranching: true (⚠️ lets branch creators run arbitrary images; restrict with genericBranchConfig.dbPod.allowedImages) |
| Preview environments | operator.previewEnv: true — default on recent chart versions, so only needs setting explicitly on older ones (+ operator.shareIngress.shareDomain and the mirrord-share-ingress chart for link sharing) |
| Multi-cluster orchestration | operator.multiCluster.enabled: true on the primary cluster; operator.multiClusterMember: true on members (needs Kubernetes 1.30+ on the Primary, 1.22+ on downstream clusters — 1.30+ on downstream clusters too if they use queue splitting) |
| Preview environments as multi-cluster replicas | operator.multiCluster.preview.mode: replicas on every cluster (default default-cluster; needs operator/chart 3.193.0+ and mirrord 3.247.0+; workload clusters need Kubernetes 1.29+ if the previews use DB branching, since the operator adds a native sidecar to the preview replicas) |
| Prometheus metrics | operator.metrics: true |
For the specific minimum operator/CLI/chart versions each feature needs, see the corresponding feature skill (e.g.
mirrord-db-branching,mirrord-kafka,mirrord-prev-env).
If the cluster has no mirrord for Teams license, an agent can offer the user a seven-day Enterprise trial instead of stopping. Run mirrord operator status first: if it succeeds, the cluster already runs the Operator (possibly from a trial an earlier session started), so don't sign up again. Otherwise, once the user agrees:
mirrord operator install --no-browser
This runs against the cluster of the current kubecontext, or the one named with --context. No authentication, no credit card, and no API key for the agent to handle. In a terminal, the command first asks you to confirm the kubecontext and namespace before it starts the trial or changes the cluster — --yes skips the question; an agent usually runs without a terminal, and then it isn't asked either way.
The command starts the trial, installs the Operator from the default Helm chart (no Helm needed), and prints the trial's end date, a claim_url for the user to open to take ownership of the organization, and the trial's API key. --no-browser keeps it from opening the claim page itself (it's skipped automatically whenever the command isn't running in a terminal). It sends the cluster's ID (the UID of its default namespace) as a hint so the user can recognize the cluster on the claim page; --cluster-hint <name> sends a different name, --no-hint sends none. If an Operator is already installed, or an earlier install left objects behind, the command stops and tells you rather than touching anything.
If the install fails or is stopped half-way, don't start another trial — remove what was installed and retry with the trial's key (the command prints both commands, filled in, when it fails):
mirrord operator uninstall
mirrord operator install --api-key <key>
Give both commands the same --context if the first attempt used one.
Treat the returned API key like any other secret material (see Security Boundaries) — don't echo it; if you move the install to Helm later, pass it via a Secret reference, not --set.
Confirm with the user before running mirrord operator install — it creates an external organization and installs into the cluster; treat it with the same care as any other cluster-modifying action.
Because the trial is an Enterprise license, it also covers Preview Environments. The Helm chart enables operator.previewEnv by default, so an Operator installed this way supports them as-is — no extra flag needed.
To remove an Operator that mirrord operator install set up (also after a half-finished install), run mirrord operator uninstall. It first lets the Operator end its sessions so the workloads they changed are restored, then deletes everything the install created, including the mirrord CRDs (so it also deletes the cluster's mirrord policies and profiles). Like install, it takes --context and asks for confirmation in a terminal. If the install was later taken over by Helm (via the helm install command mirrord operator install prints for anything beyond the default setup), use helm uninstall instead — mirrord operator uninstall detects this and stops rather than acting.
An agent that can't run the CLI can post to the signup endpoint directly instead:
curl -fsS -X POST https://app.metalbear.com/api/v1/agent/signup \
-H 'content-type: application/json' \
-d '{"agent": "claude-code", "developer_email": "<user email, optional>", "cluster_hint": "<optional>"}'
This endpoint needs no authentication and no credit card. The response describes the provisional organization: an api_key to use as the cloud API key in Step 2 above, and a claim_url the user has to open to take ownership of the organization — until they do, nobody can administer billing or seats, and the org expires with the trial. Treat the returned api_key like any other secret material — put it in a Kubernetes Secret, don't echo it. Confirm with the user before making this request — it creates an external organization and, if developer_email is set, sends mail to that address.
Air-gapped clusters can't reach the cloud to exchange an API key for a license, so they use an offline license certificate or a self-hosted license server.
license.file.secret.data:
license:
file:
secret:
data:
license.pem: |
-----BEGIN CERTIFICATE-----
<contents of your license.pem>
-----END CERTIFICATE-----
license.pemRef (doesn't require the secret to exist yet). Install the chart first (creates the mirrord namespace), then create the Secret in it:
kubectl create secret generic mirrord-operator-license-pem \
--namespace mirrord --from-file=license.pem=/path/to/license.pem
mirrord namespace must already exist and be Helm-managed, or helm install will fail to adopt it.)license.licenseServer: http://mirrord-operator-license-server.mirrord.svc. Here the license key is the shared secret the operator uses to authenticate to your server (a value you choose), and remains required.Air-gapped is Enterprise-only. Don't suggest the free/self-serve trial for offline clusters — the trial license needs connectivity to mirrord's telemetry endpoints.
Reduces startup time and removes the dependency on GitHub's registry. Copy the operator + agent images to your registry (multi-arch copy with regctl):
IMAGE_VERSION=$(helm show chart metalbear/mirrord-operator | grep 'appVersion:' | awk '{print $2}')
regctl image copy ghcr.io/metalbear-co/operator:$IMAGE_VERSION your-registry/operator:$IMAGE_VERSION
AGENT_IMAGE_VERSION=$(regctl image config ghcr.io/metalbear-co/operator:$IMAGE_VERSION | jq -r '.config.Labels."metalbear.mirrord.version"')
regctl image copy ghcr.io/metalbear-co/mirrord:$AGENT_IMAGE_VERSION your-registry/mirrord:$AGENT_IMAGE_VERSION
operator:
image: your-registry/operator
agent:
image:
registry: your-registry/mirrord
Feature images are pulled only when the feature is enabled (Kafka sidecar, MSSQL tools, Flyway, Liquibase) and DB branch pods pull a per-engine database image — both have registry overrides under operator.<engine>BranchConfig.dbPod.image and imagePullSecrets. See references/helm-values.md.
mirrord adds a small, mostly idle footprint to the cluster. In a default install, the Operator pod (one replica by default) is the only thing that runs all the time; any optional component installed separately, such as a license server, also runs all the time. Agent pods run only while a session uses them, and the Operator deletes one once no session needs it. The chart's other installed objects — CRDs, RBAC, a Service, a ConfigMap, the agent PriorityClass — live in etcd and cost no node CPU/memory.
Unless overridden, each agent pod uses:
| Resource | Request | Limit |
|---|---|---|
| CPU | 1m | 1 |
| Memory | 1Mi | 100Mi |
The requests are tiny so agent pods barely affect scheduling; the limits just stop one from using too much of a node. Agent lifecycle depends on the session type:
ephemeral: true under agent.extraConfig. Kubernetes doesn't allow setting resources on ephemeral containers, so the table above doesn't apply, and the Operator ignores the agent settings in the user's mirrord config.To change agent resources cluster-wide, set agent.resources in Helm values (operator 3.197.0+). A field set to null is left out of the agent pod spec entirely — for example, this runs agents with no CPU limit:
agent:
resources:
limits:
cpu: null
Some features allocate more for a session: copy target makes a full copy of the target pod, DB branching makes a branch database (its own pod for most engines, see Branch Storage & Resources in the mirrord-db-branching skill), and queue splitting makes temporary queues. The default resource envelope supports roughly 200 concurrent sessions — raise operator.requests/operator.limits for more (see Operator deployment in the Helm values reference).
openshift: true in values (renders a SecurityContextConstraints), covering the mirrord-operator and default service accounts in the mirrord namespace.AllowlistSynchronizer (not a manually-written WorkloadAllowlist — Autopilot rejects a manual one with an admission error on standard clusters):
apiVersion: auto.gke.io/v1
kind: AllowlistSynchronizer
metadata:
name: mirrord-allowlist
spec:
allowlistPaths:
- "mirrord/mirrord-agent/*"
agent.annotations.cloud.google.com/generate-allowlist: "true" into values to get the exact WorkloadAllowlist embedded in the operator's error logs.operator.port (e.g. 3000 / 8443) and ensure nodes can reach it.The chart creates the roles users need — you don't hand-write mirrord CRD roles. For each namespace where developers run mirrord, add it to roleNamespaces so a namespaced role is created there; then bind users to it with your own RoleBinding:
roleNamespaces:
- staging
- development
The chart also ships cluster roles: mirrord-operator-user-basic, mirrord-operator-user, and mirrord-operator-ci (scoped for CI — creating/deleting preview sessions plus the operator APIs the CLI needs; used by preview-environment CI, see the mirrord-prev-env skill). Bind the appropriate role to your users, groups, or service accounts. roleNamespaces: [] (empty) creates no namespaced roles.
Clients use the operator automatically when it's present. To force operator mode explicitly:
{ "operator": true, "target": "pod/my-app" }
mirrord exec --target pod/my-app -- node app.js
To make operator the default across every project instead of setting it in each mirrord.json, a developer can store it in their user-wide config (~/.mirrord/mirrord.json, created empty on first use):
mirrord config set operator true # or false, to disable it by default
mirrord config unset operator # back to the usual auto-detect behavior
This is currently the only field the CLI actually applies from the global file as a session default — other fields can be stored there but don't yet affect sessions, so point users at their project config for anything else. An explicit project config value (including false) or MIRRORD_OPERATOR_ENABLE still wins over the global default. If a session starts successfully through the Operator, mirrord also remembers operator: true in the global file for next time.
# Upgrade (reuse the same release name + values file)
helm repo update
helm upgrade --install -f values.yaml mirrord-operator metalbear/mirrord-operator
# Uninstall
helm uninstall mirrord-operator --namespace mirrord
kubectl delete namespace mirrord
Coordinate upgrades: in-flight sessions can break. Check with kubectl get sessions.operator.metalbear.co -A (or mirrord operator status) and upgrade when quiet.
operator.* flag; call out the generic-branching and preview security implications.helm/kubectl commands and wait for approval before running.mirrord operator status after install.아직 리뷰가 없습니다. 사용해 본 소감을 남겨 주세요.
로그인 없이 쓸 수 있습니다. 사용 후기, 질문, 작동하지 않은 환경 등을 편하게 남겨 주세요.
아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.
Test how an app handles slow or failing dependencies by adding delays and connection errors to outgoing TCP connections in a mirrord session. Create reusable rules, manage them during development, and include them in CI tests.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.
Build CI workflows that use mirrord to test applications against services in a real Kubernetes cluster. Configure runner access, start and stop application sessions, validate configuration files, and troubleshoot connection, permission, and logging problems.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.
Create, edit, and check mirrord.json files that connect a local application to Kubernetes. The skill produces minimal configurations, validates their structure and allowed settings, and explains problems with environment variables, files, and network behavior.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.
Create and validate mirrord.json settings for isolated database copies used in development and testing. Configure connection sources, copying scope, migrations, and authentication so experiments can run without affecting shared databases.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.
Update application code so a developer’s mirrord session identifier travels across service calls, queues, and storage events. Reuse existing tracing tools where possible, then report which request flows carry the identifier and where it still disappears.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.
Configure mirrord to route selected Kafka messages to a local application. Generate Kubernetes resource files and matching message filters, check their consistency, and troubleshoot connection or splitting issues, including Kafka Streams and AWS MSK IAM setups.
한국어 요약은 준비 중입니다. 영어 요약을 표시하고 있습니다.