General

What does mirrord actually do? #

First and most important, mirrord doesn’t just mirror traffic. It does that, but also a lot more.

mirrord lets you connect a process on your development machine to your Kubernetes cluster. It does this by injecting itself into the local process (no code changes needed!), intercepting all of the input and output points of the process - network traffic, file access, and environment variables - and proxying them to the cluster. This mechanism is discussed in more detail here.

When you run mirrord, you select a Target - this is the Kubernetes Pod or Deployment whose context you want your local code to run in. For example, if you have a staging cluster running the latest stable version of all of your microservices, and you’re now coding the next version of one of these microservices, you’d select as your Target the Pod or Deployment running the stable version of that microservice in staging. The following things will then happen:

• The Target’s environment variables will be made available to the local process.
• When the local process tries to read a file, it will be read from the Target’s filesystem instead.
• Traffic reaching the remote Target will reach your locally running process (this incoming traffic can either be mirrored, intercepted entirely, or intercepted based on a filter you define).
• Traffic sent out from your local process will be sent out from the Target instead, letting it reach any endpoint that’s accessible to the Target, and the response will be sent back to your local process.

By proxying all of your local process’ input and output points in this way, mirrord makes it “think” it’s running in the cloud, which lets you test it in cloud conditions:

1. Without having to run your entire architecture locally
2. Without going through lengthy CI and deployment processes
3. Without deploying untested code to the cloud environment - the stable version of the code is still running in the cluster and handling requests - letting multiple users test on the same cluster without queueing to use it or breaking the cluster for everyone else.

Is mirrord free? #

mirrord is free and open source (MIT License). Our paid offering, mirrord for Teams, includes a Kubernetes operator that acts as a control plane for mirrord. You can read more about it here.

Can I intercept traffic instead of duplicating it? #

Yes, you can use the --steal flag to intercept traffic instead of duplicating it.

Does mirrord install anything on the cluster? #

No, mirrord doesn’t install anything on the cluster, nor does it have any persistent state. It does spawn a short-living pod/container to run the proxy, which is automatically removed when mirrord exits. mirrord works using the Kubernetes API, and so the only prerequisite to start using mirrord is to have kubectl configured for your cluster.

If you have any restrictions for pulling external images inside your cluster, you have to allow pulling of ghcr.io/metalbear-co/mirrord image.

How does mirrord protect against disrupting my shared environment with my local code? #

• By letting you mirror traffic rather than intercept it, the stable version of the code can still run in the cluster and handle requests.
• By letting you control which functionality runs locally and which runs in the cloud, you can configure mirrord in the way that’s safest for your architecture. For example, you can configure mirrord to read files and receive incoming traffic from the cloud, but write files and send outgoing traffic locally. Our main goal in future versions of mirrord is to reduce the risk of disruption of the shared environment when using mirrord. This will be achieved by providing more granular configuration options (for example, filtering traffic by hostname or protocol), and advanced functionality like copy-on-write for databases.

Can I use mirrord to run a local container, rather than a local process, in the context of the remote Kubernetes cluster? #

The only way to do this at the moment is to install the mirrord CLI within the container and change its entrypoint to run the original process using mirrord. Support for running containers directly with mirrord will be added in the future - please follow this issue for updates.

What if I can’t create containers with the capabilities mirrord requires in my cluster? #

mirrord works by creating an agent on a privileged pod in the remote cluster that accesses another pod’s namespaces (read more about it here). If you can’t give your end users permissions to create pods with the capabilities mirrord needs, we suggest trying out mirrord for Teams. It adds a Kubernetes operator that acts as a control plane for mirrord clients, and lets them work with mirrord without creating pods themselves. If mirrord for Teams doesn’t work for you either, let us know and we’ll try to figure a solution that matches your security policies.