Learn about mirrord and how it works
mirrord is a tool that lets developers run local processes in the context of their cloud environment. It makes it incredibly easy to test your code on a cloud environment (e.g. staging) without actually going through the hassle of Dockerization, CI, or deployment, and without disrupting the environment by deploying untested code. Instead of saving it for the last step, now you can shift-left on cloud testing and test your code in the cloud from the very beginning of your development process.
Want to see mirrord in action? Check out our demo.
Traditionally, software development happens in loops. Developers write and test their code locally, then deploy it to a staging/pre-production environment in the cloud, where they perform additional tests. These tests often fail, because the code is meeting a production-like environment for the first time, and encounters new conditions. The code must then be fixed/rewritten, tested locally again, deployed to staging again, and so on, until the tests on staging pass.
Deployment to staging can be costly for several reasons:
It often involves a CI process, which may be slow (because of e.g. a long automated test suite having to pass in order to progress) and sometimes broken.
Since staging environments are shared, the environment is occasionally broken when an engineer deploys unstable code.
mirrord removes the costs associated with deployment to staging, by taking 'deployment' out of the process completely. By plugging your local process directly into the staging environment, you can test your code in cloud conditions without having to go through a long CI process, and without the risk of breaking the environment for other developers.
However, the point of mirrord is not just to make that final step in the dev loop of testing in staging quicker. mirrord makes running your code in the cloud easy, fast and safe, so you can shift left on cloud testing, and test your code in the cloud from the very beginning of your development process. Instead of spending your time running local environments, writing mocks, test fixtures, and so on - why not just test your code on staging itself?
mirrord runs in two places - in the memory of your local process (mirrord-layer), and as a pod in your cloud environment (mirrord-agent).
When you start your local process with mirrord, it creates a pod in your cloud environment, which listens in on the pod you've passed as an argument. mirrord-layer then does the following:
Override the process' syscalls to:
Listen to incoming traffic from the agent, instead of local sockets.
Intercept outgoing traffic and send it out from the remote pod, instead of locally.
Read and write files to the remote file system.
Merge the process' environment variables with those of the remote pod.
The remote part of this logic is handled by the agent, which runs in the network namespace of the remote pod, and can access its file system and environment variables.
For further details, see the architecture section.
mirrord is not the first tool to allow you to run your code in the cloud. However, it does it in a way that's completely different from all the other solutions. While all other remocal solutions use some version of a VPN to connect your local machine (or local Docker container) to the cluster, mirrord works at the level of your local process, overriding its syscalls and proxying them to the cloud. Similarly, at the cluster level, it runs at the level of the target pod, running on the same node and executing the syscalls received from the client.
This gives mirrord some unique advantages over its alternatives:
You can configure exactly what functionality happens remotely, and what stays local. For example:
You can read some files or environment variables from your local machine and some from the remote pod
You can make requests to certain hosts or IPs happen locally, and others be sent out from the remote pod
At the local level, it doesn't require root access
At the local level, it takes 15 seconds at most to start up
At the local level, you can run multiple processes simultaneously, each in the context of a different remote pod
At the cluster level, it's agnostic to the cluster's network setup - whether it includes a service mesh, a VPN, or anything else
At the cluster level, it's agnostic to the cluster's size - mirrord has been tested on clusters running 10,000+ pods
Intro to mirrord for Teams
Ready to start using mirrord for Teams? Register to get started.
So you've tried out mirrord on your cloud development environment and you liked it. You've even shown it to your teammates, and they tried it out on their own personal environments. Great! Now all of you might want to use mirrord together on the same environment (your shared staging environment, for example). This is where things might get tricky:
Your DevOps team might not be too happy about giving everyone privileged permissions to the shared environment.
Two or more developers might want to run mirrord simultaneously on the same pod or deployment without clashing.
You might be sharing the staging environment with other teams, who wouldn't want you to mess with their components.
Your shared environment is more likely to have multi-pod deployments, which you might want to mirror entirely, rather than just the first pod.
As you might have guessed, this is where mirrord for Teams comes in.
In the basic version of mirrord, mirrord injects itself into the local process, and creates a pod in the Kubernetes cluster. It's completely standalone, and is unaware of other instances of mirrord running on the same cluster.
In mirrord for Teams, we introduce a new component - the mirrord Operator. The Operator is a Kubernetes operator that runs persistently in the cluster and manages the mirrord instances trying to access it. The Operator itself is the one creating mirrord agents, so individual users no longer need elevated Kubernetes permissions to use mirrord. Additionally, a centralized component makes possible things like concurrent use, or limiting access or specific actions to certain cluster components.
The following functionality is currently available in mirrord for Teams that isn't available in the open-source version:
Concurrent use - mirrord for Teams includes various features that allow your entire team to work on a shared environment without conflicts.
Better security and RBAC - with the mirrord Operator, users no longer need permissions to create privileged pods - only the Operator does. In addition, permissions can be managed within Kubernetes to allow or prevent users from impersonating specific targets.
Advanced features - support for new resource types like Jobs and StatefulSets, multi-pod deployments, and more.
For the full list of features, see the mirrord for Teams .
How to contribute to mirrord
There are a lot of ways you can contribute to mirrord, like:
Write code! See our guide here. Most of our code is in Rust, but we also have some TypeScript and Kotlin (in our VS Code and IntelliJ extensions, respectively), and even some Assembly if you're feeling particularly brave. To start writing code for mirrord, find an issue you'd like to fix or implement in our issue tracker. Please let us know that you're working on an issue beforehand, so we can assign it to you, provide help and reduce double-work.
Report a bug you found in our issue tracker.
Suggest a feature or improvement in a discussion on our GitHub discussions.
Write a blog post about your experience with mirrord. We'd be happy to share it, or even host it on the MetalBear blog - just open a PR with the new post the MetalBear website repo.
Contribute to our docs and website by sending in a PR to the mirrord website repo.
Community is at the core of the mirrord project, and we welcome anyone and everyone that wants to join. We mainly hang out on Discord - if you need help or want to chat, feel free to join us there!
How to (very) quickly start using mirrord
mirrord runs on your local machine and in your Kubernetes cluster.
MacOS (Intel, Apple Silicon) and Linux (x86_64) are supported for the local machine. Windows users can use mirrord using WSL (IDE plugins supported as well).
kubectl needs to be configured on the local machine.
Docker or containerd runtime (containerd is the most common). If you'd like support for other runtimes to be added, please let us know by opening an issue on GitHub.
Linux Kernel version 4.20+
mirrord can be used in three ways:
If you're planning to use mirrord for Teams, you'll also need to install the mirrord Operator.
To install the CLI, run:
brew install metalbear-co/mirrord/mirrordor
curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bashTo use mirrord to plug a local process into a pod/deployment in the cluster configured with kubectl, run:
mirrord exec --target <target-path> <command used to run the local process>For example:
mirrord exec --target pod/app-pod-01 python main.pyOr, if you'd rather run a local container than a native process, run:
mirrord container --target <target-path> -- <command used to run the local container>For example:
mirrord container -- docker run nginxUse mirrord exec --help or mirrord container --help to get all possible commands + arguments.
You can install the extension directly in the IDE (Extensions -> search for 'mirrord'), or download it from the marketplace here.
To use extension, click the 'Enable mirrord' button in the status bar at the bottom of the window. When you next run a debug session, you'll be prompted with a dropdown listing pods in the namespace you've configured (or the 'default' namespace, if you haven't). Select the pod you want to impersonate, and the debugged process will be plugged into that pod by mirrord.
The VS Code extension reads its configuration from the following file: <project-path>/.mirrord/mirrord.json. You can also prepend a prefix, e.g. my-config.mirrord.json, or use .toml or .yaml format. Configuration options are listed here. The configuration file also supports autocomplete when edited in VS Code when the extension is installed.
You can install the plugin directly in the IDE (Preferences -> Plugins, search for 'mirrord'), or download it from the marketplace here.
To use extension, click the mirrord icon in the Navigation Toolbar at the top right of the window. When you next run a debug session, you'll be prompted with a dropdown listing namespaces in your cluster, and then another with pods in the namespace you selected. Select the pod you want to impersonate, and the debugged process will be plugged into that pod by mirrord.
The IntelliJ plugin reads its configuration from the following file: <project-path>/.mirrord/mirrord.json. You can also prepend a prefix, e.g. my-config.mirrord.json, or use .toml or .yaml format. Configuration options are listed here.
To install and use the Operator, you'll need a mirrord for Teams license. You can get one here. The Operator can be installed using the mirrord CLI or Helm. This has to be performed by a user with elevated permissions to the cluster.
Install the mirrord CLI.
Run the mirrord operator setup command. The base of the command is: mirrord operator setup [OPTIONS] | kubectl apply -f - Options:
--accept-tos You accept terms of service for mirrord-operator
--license-key The license key for the operator
(Optional) -f, --file Output Kubernetes definitions to file and not to stdout (instead of piping to kubectl apply -f -)
(Optional) --namespace Set namespace of mirrord operator (default: mirrord) So the final command should look like mirrord operator setup --accept-tos --license-key <license-key> | kubectl apply -f -
You should now be able to see the mirrord-operator deployment when running kubectl get deployments -n mirrord. Also, when you run mirrord, you'll see the connected to operator step in its progress reports.
To install the mirrord Operator with Helm, first add the MetalBear Helm repository:
helm repo add metalbear https://metalbear-co.github.io/chartsThen download the accompanying values.yaml:
curl https://raw.githubusercontent.com/metalbear-co/charts/main/mirrord-operator/values.yaml --output values.yamlSet license.key to your key.
Finally, install the chart:
helm install -f values.yaml mirrord-operator metalbear/mirrord-operator In order to make the operator work with OpenShift, you need to apply the following scc:
kind: SecurityContextConstraints
apiVersion: security.openshift.io/v1
metadata:
name: scc-mirrord
allowHostPID: true
allowPrivilegedContainer: false
allowHostDirVolumePlugin: true
allowedCapabilities: ["SYS_ADMIN", "SYS_PTRACE", "NET_RAW", "NET_ADMIN"]
runAsUser:
type: RunAsAny
seLinuxContext:
type: MustRunAs
users:
- system:serviceaccount:mirrord:mirrord-operator
- system:serviceaccount:mirrord:defaultAfter installing the Operator, you can verify it works by running mirrord operator status. All mirrord clients will now use the Operator instead of doing actions on their own when running against the cluster.
Now that you've installed the CLI tool or one of the extensions, lets see mirrord at work. By default, mirrord will mirror incoming traffic to the remote target (this can be changed in the configuration), sending a duplicate to the same port on your local process. So if your remote target receives traffic on port 80, your local process will receive a copy of that traffic on that same port (this can also be configured).
To test this out, enable mirrord in your IDE plugin and start debugging your process (or execute your process with the mirrord CLI). Send a request to your remote target, and you should see that request arriving at your local process as well!
Note that, by default, the following features are also enabled:
Environment variables from the remote target will be imported into your local process
When reading files, your local process will read them from the remote target
DNS resolution for your local process will happen on the remote target
Outgoing traffic sent by your local process will be sent out from the remote target instead, and the response will be sent back to your local process
We find that this configuration works for a lot of use cases, but if you'd like to change it, please read about available options in the configuration.
Now that you've tried out mirrord, it's time to get acquainted with its different configuration options and tailor it to your needs:
If you'd like to intercept traffic rather than mirror it so that your local process is the one answering the remote requests, check out this guide. Note that you can even filter which traffic you intercept!
If your local process reads from a queue, you might want to test out the copy target feature, which temporarily creates a copy of the mirrord session target. With its scaledown flag it allows you to temporarily delete all replicas in your targeted rollout or deployment, so that none competes with your local process for queue messages.
If you don't want to impersonate a remote target - for example, if you want to run a tool in the context of your cluster - check out our guide on the targetless mode.
If you just want to learn more about mirrord, why not check out our architecture or configuration sections?
Accelerate your Kubernetes development workflow with mirrord. mirrord lets developers run and test their code in a real Kubernetes environment instantly, without needing to rebuild or redeploy.
mirrord helps developers improve their development experience by seamlessly mirroring Kubernetes traffic and configuration from staging or testing environments directly into their local environment. This allows developers to test their locally written code in a production-like environment without going through tedious CI pipelines or repeatedly having to build and deploy container images.