> For the complete documentation index, see [llms.txt](https://metalbear.com/mirrord/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://metalbear.com/mirrord/docs/using-mirrord/targeting-pods-by-label.md).

# Targeting Pods by Label

Target every pod that shares a Kubernetes label from a single mirrord session

Applications sometimes span more than one Kubernetes workload. A monolith might run as several separate Deployments or Rollouts in the same namespace — one per role, each with its own scaling policy but the same codebase. Pods can also be created and managed directly by a team's own controller, with no Deployment or ReplicaSet above them at all.

Label targeting lets a single mirrord session target every pod that carries a given Kubernetes label — instead of one workload name — so traffic from all of them is intercepted together, however many separate workloads (or none) actually own them.

### When to use this

* Your codebase is deployed multiple times under different roles in the same namespace, sharing a common label.
* Pods are managed directly by your own controller, with no Deployment or ReplicaSet above them to target.
* You want traffic from all of these pods mirrored or stolen into one local process, without merging or manually picking between them.

## Configuration

Object form:

```json
{
  "target": {
    "path": {
      "labels": { "argocd.argoproj.io/instance": "monolith-web" }
    }
  }
}
```

Shorthand Equivalent:

```json
{ "target": "label/argocd.argoproj.io/instance=monolith-web" }
```

Multiple labels are comma-separated in the string form (all must match):

```json
{ "target": "label/app=web,tier=frontend" }
```

An optional container:

```json
{ "target": "label/app=web,tier=frontend/container/app" }
```

### How it behaves

mirrord resolves the label selector against pods in the target namespace and:

* Mirrors or steals traffic from every matching pod.
* Resolves environment variables, file operations, and outgoing connections through a single pod that mirrord selects from the matches — not merged or repeated across every pod.

{% hint style="info" %}
This means label targeting fits best when every matching pod runs identical configuration and only differs in things like replica count or autoscaling policy. If your matching pods differ in environment variables or mounted files, pick a different targeting approach — or run one session per workload as before. Minimum versions required are mirrord operator v3.192.0 and mirrord CLI v3.246.0.
{% endhint %}

### Limitations

* An empty label selector is rejected, so it can't accidentally match every pod in the namespace.
* Not yet supported: copy\_target, queue splitting, DB branching, and multi-cluster targeting.
* [Preview environments](/mirrord/docs/use-cases/preview-environments.md) can target pods by label (requires operator v3.213.0 and CLI v3.266.0 or later). A single preview session takes traffic from every pod the selector matches. Queue splitting and DB branching are not supported in preview environments with a label target.
* Kubernetes' label selector syntax is not supported.

Combining label targeting with any of these currently returns an error rather than silently falling back to single-pod behavior.

### Not `mirrord up`

If what you need is to run several *different* applications together - not variations of the same one - that's [`mirrord up`](/mirrord/docs/using-mirrord/multiple-concurrent-sessions.md) instead. Label targeting intercepts traffic for pods that are all the *same* application from a single session; `mirrord up` orchestrates *separate* applications, each getting its own local process and its own target.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://metalbear.com/mirrord/docs/using-mirrord/targeting-pods-by-label.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.