mirrord

https://metalbear.co/mirrord/docs/
Admin
A tool for faster and simpler Kubernetes development, enabling local debugging and interaction with...
Tokens:33,044
Snippets:181
Trust Score:8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Comprehensive mirrord Configuration Example

Source: https://metalbear.co/mirrord/docs/reference/configuration

Provides a complete example of a mirrord configuration file, showcasing all available options and their default or example values. This is intended as a reference for advanced customization rather than a starting point.

```JSON
{
  "accept_invalid_certificates": false,
  "skip_processes": "ide-debugger",
  "target": {
    "path": "pod/bear-pod",
    "namespace": "default"
  },
  "connect_tcp": null,
  "agent": {
    "log_level": "info",
    "json_log": false,
    "labels": { "user": "meow" },
    "annotations": { "cats.io/inject": "enabled" },
    "namespace": "default",
    "image": "ghcr.io/metalbear-co/mirrord:latest",
    "image_pull_policy": "IfNotPresent",
    "image_pull_secrets": [ { "secret-key": "secret" } ],
    "ttl": 30,
    "ephemeral": false,
    "communication_timeout": 30,
    "startup_timeout": 360,
    "network_interface": "eth0",
    "flush_connections": true,
    "metrics": "0.0.0.0:9000"
  },
  "feature": {
    "env": {
      "include": "DATABASE_USER;PUBLIC_ENV",
      "exclude": "DATABASE_PASSWORD;SECRET_ENV",
      "override": {
        "DATABASE_CONNECTION": "db://localhost:7777/my-db",
        "LOCAL_BEAR": "panda"
      },
      "mapping": {
        ".+_TIMEOUT": "1000"
      }
    },
    "fs": {
      "mode": "write",
      "read_write": ".+\\.json" ,
      "read_only": [ ".+\\.yaml", ".+important-file\\.txt" ],
      "local": [ ".+\\.js", ".+\\.mjs" ]
    },
    "network": {
      "incoming": {
        "mode": "steal",
        "http_filter": {
          "header_filter": "host: api\\..+"
        },
        "port_mapping": [[ 7777, 8888 ]],
        "ignore_localhost": false,
        "ignore_ports": [9999, 10000]
      },
      "outgoing": {
        "tcp": true,
        "udp": true,
        "filter": {
          "local": ["tcp://1.1.1.0/24:1337", "1.1.5.0/24", "google.com", ":53"]
        },
        "ignore_localhost": false,
        "unix_streams": "bear.+"
      },
      "dns": {
        "enabled": true,
        "filter": {
          "local": ["1.1.1.0/24:1337", "1.1.5.0/24", "google.com"]
        }
      }
    },
    "copy_target": {
      "scale_down": false
    }
  },
  "operator": true,
  "kubeconfig": "~/.kube/config",
  "sip_binaries": "bash",
  "telemetry": true,
  "kube_context": "my-cluster"
}
```

--------------------------------

### Install Node.js via APT

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

Installs the Node.js runtime environment using the APT package manager on a Linux system. This command requires superuser privileges and is a standard way to get Node.js set up for development.

```Shell
sudo apt install nodejs
```

--------------------------------

### mirrord CLI Operator Setup Command

Source: https://metalbear.co/mirrord/docs/overview/quick-start

Documents the `mirrord operator setup` command for installing the mirrord operator via CLI. It details the command signature, available options, their descriptions, and a practical usage example for piping output to `kubectl apply`.

```APIDOC
mirrord operator setup [OPTIONS] | kubectl apply -f -
  - Description: Installs the mirrord operator via the command line, outputting Kubernetes definitions to stdout for piping to kubectl.
  - Parameters:
    - --accept-tos: Flag to accept terms of service for mirrord-operator.
    - --license-key <key>: The license key required for the operator.
    - -f, --file <path>: (Optional) Output Kubernetes definitions to a specified file instead of stdout (instead of piping to `kubectl apply -f -`).
    - --namespace <name>: (Optional) Set the Kubernetes namespace for the mirrord operator (default: mirrord).
  - Usage Example:
    mirrord operator setup --accept-tos --license-key <license-key> | kubectl apply -f -
```

--------------------------------

### Example mirrord Configuration for Profile Selection

Source: https://metalbear.co/mirrord/docs/reference/configuration

Demonstrates how to specify a mirrord profile, supporting both cluster-wide and namespaced profiles. Profiles allow for predefined configurations to be easily applied.

```JSON
{
  "profile": "my-profile-name"
}
```

```JSON
{
  "profile": "my-namespace/my-profile-name"
}
```

--------------------------------

### Basic mirrord Configuration JSON

Source: https://metalbear.co/mirrord/docs/reference/configuration

Illustrates a minimal mirrord configuration file, enabling environment variable, file system (read-only), and network features. This serves as a quick start for basic mirrord functionality.

```JSON
{
  "target": "pod/bear-pod",
  "feature": {
    "env": true,
    "fs": "read",
    "network": true
  }
}
```

--------------------------------

### Example mirrord Internal Proxy Configuration

Source: https://metalbear.co/mirrord/docs/reference/configuration

Illustrates common configuration settings for the mirrord internal proxy, including `start_idle_timeout` and `idle_timeout` to manage connection behavior.

```JSON
{
  "internal_proxy": {
    "start_idle_timeout": 30,
    "idle_timeout": 5
  }
}
```

```JSON
{
  "internal_proxy": {
    "idle_timeout": 30
  }
}
```

```JSON
{
  "internal_proxy": {
    "start_idle_timeout": 60
  }
}
```

--------------------------------

### Example mirrord File System Path Mapping Configuration

Source: https://metalbear.co/mirrord/docs/reference/configuration

Demonstrates how to configure path mapping within mirrord's file system feature, allowing for dynamic path replacements using regex capture groups. This example shows mapping `/home/<user>/dev/tomcat` to `/etc/tomcat` and `/home/<user>/dev/config/<app>` to `/mnt/configs/${user}-$app`.

```json
{
  "^/home/(?<user>\\S+)/dev/tomcat": "/etc/tomcat",
  "^/home/(?<user>\\S+)/dev/config/(?<app>\\S+)": "/mnt/configs/${user}-$app"
}
```

--------------------------------

### Install mirrord CLI in WSL

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

This command downloads and executes the official mirrord installation script from GitHub, installing the mirrord command-line interface tool within your Windows Subsystem for Linux (WSL) environment. It may require root privileges to install in system paths like `/usr/local/bin`.

```bash
curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bash
```

--------------------------------

### Example mirrord File System Configuration

Source: https://metalbear.co/mirrord/docs/reference/configuration

Illustrates a mirrord configuration for file system behavior, setting the default mode to `write` and defining specific regex patterns for `read_write`, `read_only`, `local`, and `not_found` operations.

```json
{
  "feature": {
    "fs": {
      "mode": "write",
      "read_write": ".+\\.json" ,
      "read_only": [ ".+\\.yaml", ".+important-file\\.txt" ],
      "local": [ ".+\\.js", ".+\\.mjs" ],
      "not_found": [ "\\.config/gcloud" ]
    }
  }
}
```

--------------------------------

### mirrord Network Feature Configuration with Example

Source: https://metalbear.co/mirrord/docs/reference/configuration

Manages mirrord's network operations, including detailed settings for incoming (mode, HTTP filter, port mapping, ignore localhost/ports) and outgoing (TCP/UDP, filter, ignore localhost, Unix streams) traffic, and DNS resolution. The provided JSON example illustrates a complete network configuration.

```JSON
{
  "feature": {
    "network": {
      "incoming": {
        "mode": "steal",
        "http_filter": {
          "header_filter": "host: api\\..+"
        },
        "port_mapping": [[ 7777, 8888 ]],
        "ignore_localhost": false,
        "ignore_ports": [9999, 10000]
      },
      "outgoing": {
        "tcp": true,
        "udp": true,
        "filter": {
          "local": ["tcp://1.1.1.0/24:1337", "1.1.5.0/24", "google.com", ":53"]
        },
        "ignore_localhost": false,
        "unix_streams": "bear.+"
      },
      "dns": {
        "enabled": true,
        "filter": {
          "local": ["1.1.1.0/24:1337", "1.1.5.0/24", "google.com"]
        }
      }
    }
  }
}
```

--------------------------------

### Start a WSL Session

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

Initiates a new session within the Windows Subsystem for Linux environment, allowing direct interaction with the installed default Linux distribution. This command opens a new terminal session inside WSL.

```Shell
wsl
```

--------------------------------

### Example: mirrord with Docker Nginx Container

Source: https://metalbear.co/mirrord/docs/using-mirrord/local-container

An example demonstrating how to use the `mirrord container` command to attach mirrord to an Nginx container started with Docker. This illustrates the basic syntax for integrating mirrord with a local Dockerized application, supporting Docker, Podman, and nerdctl.

```Shell
mirrord container -- docker run nginx
```

--------------------------------

### Install WSL Default Linux Distro

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

Installs the default Linux distribution (Ubuntu) for Windows Subsystem for Linux (WSL) from the terminal. This command requires administrator privileges to execute successfully.

```Shell
wsl --install
```

--------------------------------

### Install regctl for Image Management

Source: https://metalbear.co/mirrord/docs/overview/quick-start

Provides two methods to install `regctl`, a command-line tool recommended for copying multi-arch container images. Options include using `go install` or a direct `curl` download.

```go
go install github.com/regclient/regclient/cmd/regctl@latest
```

```bash
curl -L https://github.com/regclient/regclient/releases/latest/download/regctl-linux-amd64 >regctl
chmod 755 regctl
```

--------------------------------

### List Installed WSL Distributions

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

Displays a list of all installed Windows Subsystem for Linux distributions and their default status. This command is useful for verifying successful WSL installation and identifying available Linux environments.

```Shell
C:\> wsl --list
Windows Subsystem for Linux Distributions:
Ubuntu (Default)
```

--------------------------------

### Example mirrord Configuration for macOS SIP Binary Patching

Source: https://metalbear.co/mirrord/docs/reference/configuration

Shows how to list binaries that mirrord should patch on macOS to bypass System Integrity Protection (SIP). This is useful when mirrord isn't automatically loaded for protected binaries.

```JSON
{
  "sip_binaries": ["bash", "python"]
}
```

--------------------------------

### Example mirrord Configuration for Kubernetes Context

Source: https://metalbear.co/mirrord/docs/reference/configuration

Shows how to explicitly define the Kubernetes context to be used by mirrord from the kubeconfig file. If not specified, mirrord defaults to the current context.

```JSON
{
  "kube_context": "mycluster"
}
```

--------------------------------

### Basic MirrordKafkaClientConfig YAML Example

Source: https://metalbear.co/mirrord/docs/using-mirrord/queue-splitting

An example of a `MirrordKafkaClientConfig` resource defining basic Kafka client properties like `bootstrap.servers`.

```YAML
apiVersion: queues.mirrord.metalbear.co/v1alpha
kind: MirrordKafkaClientConfig
metadata:
  name: base-config
  namespace: mirrord
spec:
  properties:
  - name: bootstrap.servers
    value: kafka.default.svc.cluster.local:9092
```

--------------------------------

### General mirrord Configuration Reference

Source: https://metalbear.co/mirrord/docs/reference/configuration

Documentation for general mirrord settings, including Kubernetes context and kubeconfig paths, operator usage, profile selection, and macOS SIP binary patching.

```APIDOC
kube_context: string
  Description: Kube context to use from the kubeconfig file. Uses current context if not specified.
kubeconfig: string (path)
  Description: Path to a kubeconfig file. If not specified, uses `KUBECONFIG`, `~/.kube/config`, or in-cluster config.
operator: boolean
  Description: Whether mirrord should use the operator. If not set, mirrord attempts to use the operator and continues without it on failure.
profile: string
  Description: Name of the mirrord profile to use. Can be cluster-wide or namespaced.
  Format: "my-profile-name" (cluster-wide) or "my-namespace/my-profile-name" (namespaced).
sip_binaries: array of strings (paths/regexes)
  Description: Binaries to patch on macOS for System Integrity Protection (SIP). Uses `endswith` on binary path.
  Purpose: Use when mirrord isn't loaded to protected binaries automatically.
```

--------------------------------

### Example mirrord Configuration for Message Queue Splitting

Source: https://metalbear.co/mirrord/docs/reference/configuration

Demonstrates how to define filters for splitting message queues (SQS, Kafka) based on message content using regular expressions. This allows the local application to consume only messages matching specified criteria.

```JSON
{
  "feature": {
    "split_queues": {
      "first-queue": {
        "queue_type": "SQS",
        "message_filter": {
          "wows": "so wows",
          "coolz": "^very"
        }
      },
      "second-queue": {
        "queue_type": "SQS",
        "message_filter": {
          "who": "you$"
        }
      },
      "third-queue": {
        "queue_type": "Kafka",
        "message_filter": {
          "who": "you$"
        }
      },
      "fourth-queue": {
        "queue_type": "Kafka",
        "message_filter": {
          "wows": "so wows",
          "coolz": "^very"
        }
      }
    }
  }
}
```

--------------------------------

### Example mirrord Configuration for Kubeconfig Path

Source: https://metalbear.co/mirrord/docs/reference/configuration

Illustrates how to specify a custom path to a kubeconfig file for mirrord. This overrides default locations like `KUBECONFIG` environment variable or `~/.kube/config`.

```JSON
{
  "kubeconfig": "~/bear/kube-config"
}
```

--------------------------------

### Example Mirrord Outgoing Network Configuration

Source: https://metalbear.co/mirrord/docs/reference/configuration

Illustrates a complete JSON configuration block for enabling and configuring mirrord's outgoing network tunneling feature, including TCP/UDP settings, localhost ignoring, and traffic filtering.

```JSON
{
  "feature": {
    "network": {
      "outgoing": {
        "tcp": true,
        "udp": true,
        "ignore_localhost": false,
        "filter": {
          "local": ["tcp://1.1.1.0/24:1337", "1.1.5.0/24", "google.com", ":53"]
        },
        "unix_streams": "bear.+"
      }
    }
  }
}
```

--------------------------------

### Install mirrord License Server with Helm

Source: https://metalbear.co/mirrord/docs/managing-mirrord/license-server

This shell command installs the mirrord operator license server onto a Kubernetes cluster using Helm. It references the `metalbear-co/mirrord-operator-license-server` chart and applies configurations from a local `values.yaml` file. The `--wait` flag ensures that the command waits until all deployed resources are in a ready state before completing.

```shell
helm install mirrord-operator-license-server metalbear-co/mirrord-operator-license-server -f ./values.yaml --wait
```

--------------------------------

### Install mirrord CLI on macOS and Linux

Source: https://metalbear.co/mirrord/docs/overview/quick-start

Instructions for installing the mirrord command-line interface using Homebrew for macOS or a curl script for Linux and other systems. These commands add the mirrord executable to your system's path, making it globally accessible.

```bash
brew install metalbear-co/mirrord/mirrord
```

```bash
curl -fsSL https://raw.githubusercontent.com/metalbear-co/mirrord/main/scripts/install.sh | bash
```

--------------------------------

### Install mirrord Operator Helm Chart

Source: https://metalbear.co/mirrord/docs/overview/quick-start

Installs the mirrord operator using Helm, applying configurations from a local `values.yaml` file. Ensure the `license.key` is set in the `values.yaml` before running this command.

```bash
helm install -f values.yaml mirrord-operator metalbear/mirrord-operator
```

--------------------------------

### Install mirrord Operator with Helm

Source: https://metalbear.co/mirrord/docs/managing-mirrord/license-server

This shell command installs the mirrord operator on a Kubernetes cluster using Helm, applying the updated `values.yaml` file that now includes the license server connection details. The `--wait` flag ensures that the installation process waits for all operator resources to become ready, confirming a successful deployment.

```shell
helm install mirrord-operator metalbear-co/mirrord-operator -f ./values.yaml --wait
```

--------------------------------

### Basic mirrord Configuration with Templating

Source: https://metalbear.co/mirrord/docs/reference/configuration

Demonstrates a mirrord configuration file utilizing Tera templating for dynamic values, specifically for the target field. It shows how to use environment variables within the configuration.

```JSON
{
  "target": "{{ get_env(name="TARGET", default="pod/fallback") }}",
  "feature": {
    "env": true,
    "fs": "read",
    "network": true
  }
}
```

--------------------------------

### mirrord Feature Configuration Reference

Source: https://metalbear.co/mirrord/docs/reference/configuration

Documentation for various mirrord features, including network outgoing traffic handling (UDP, Unix streams) and advanced message queue splitting.

```APIDOC
feature:
  network:
    outgoing:
      udp: boolean
        Description: Defaults to `true`. Controls whether mirrord intercepts outgoing UDP connections.
        Default: true
      unix_streams: string | array of strings (regex)
        Description: Defines Unix stream paths to connect remotely. Other paths connect locally. Values are regular expressions.
        Syntax: Supported regex syntax (https://docs.rs/regex/1.7.1/regex/index.html#syntax).
        Behavior: Target address matched against regexes; if match, mirrord connects to target pod. Otherwise, local connection.
  split_queues: object
    Description: Defines filters for splitting message queues, allowing local application to consume only matching messages.
    Structure:
      <queue_name>: object
        queue_type: string (e.g., "SQS", "Kafka")
        message_filter: object (key-value pairs for message content filtering)
          <field_name>: string (regex)
```

--------------------------------

### Advanced mirrord incoming traffic configuration with HTTP filter and port mapping

Source: https://metalbear.co/mirrord/docs/reference/configuration

This JSON configuration demonstrates a comprehensive setup for stealing incoming traffic. It specifies 'steal' mode, applies an HTTP header filter for 'host: api\\..+', defines port mappings, and sets ignore options for localhost and specific ports, allowing fine-grained control over traffic interception.

```JSON
{
  "feature": {
    "network": {
      "incoming": {
        "mode": "steal",
        "http_filter": {
          "header_filter": "host: api\\..+"
        },
        "port_mapping": [[ 7777, 8888 ]],
        "ignore_localhost": false,
        "ignore_ports": [9999, 10000],
        "listen_ports": [[80, 8111]]
      }
    }
  }
}
```

--------------------------------

### Verify mirrord Operator Installation Status

Source: https://metalbear.co/mirrord/docs/overview/quick-start

A simple command to check the operational status of the mirrord operator after installation. This helps confirm that the operator is running and accessible.

```bash
mirrord operator status
```

--------------------------------

### Mirrord Incoming Network Configuration Options

Source: https://metalbear.co/mirrord/docs/reference/configuration

Documents the various configuration options available for managing incoming network traffic with mirrord, including port remapping, traffic mirroring/stealing modes, and IPv6 support.

```APIDOC
feature.network.incoming.listen_ports:
  - Description: Mapping for local ports to actually used local ports. When an application listens on a port while steal/mirror is active, mirrord may fallback to random ports to avoid conflicts. This configuration allows specifying a fixed local port. For example, `[[80, 4480]]` maps remote port 80 to local port 4480.
  - Type: Array of arrays (e.g., `[[remote_port, local_port]]`)

feature.network.incoming.mode:
  - Description: Allows selecting between mirroring or stealing traffic.
  - Type: String
  - Valid Values:
    - "mirror": Sniffs on TCP port, sends a copy of the data to listeners.
    - "off": Disables the incoming network feature.
    - "steal": Supports two modes of operation:
      1. Port traffic stealing: Steals all TCP data from a port when the user listens on a TCP socket.
      2. HTTP traffic stealing: Steals only HTTP traffic, with best-effort detection.

feature.network.incoming.on_concurrent_steal:
  - Description: (Operator Only) Allows overriding port locks.
  - Type: String
  - Valid Values:
    - "continue": Continue with normal execution.
    - "override": If a port lock is detected, override it with a new lock and force close the original locking connection.

feature.network.incoming.port_mapping:
  - Description: Mapping for local ports to remote ports. Useful for mirroring/stealing a port to a different port on the remote machine. For example, `[[9333, 80]]` maps local port 9333 to remote port 80.
  - Type: Array of arrays (e.g., `[[local_port, remote_port]]`)

feature.network.incoming.ports:
  - Description: List of specific ports to mirror/steal traffic from. Other ports will remain local. Mutually exclusive with `feature.network.incoming.ignore_ports`.
  - Type: Array of integers

feature.network.ipv6:
  - Description: Enable IPv6 support. Turn on if your application listens to incoming traffic over IPv6 or connects to other services over IPv6.
  - Type: Boolean
```

--------------------------------

### Verify mirrord License Server Deployment

Source: https://metalbear.co/mirrord/docs/managing-mirrord/license-server

This shell command uses `kubectl` to check the status of the `mirrord-license-server` deployment within the `mirrord` namespace. It is used to confirm that the license server has been successfully installed and is running correctly on the Kubernetes cluster after the Helm installation.

```shell
kubectl get deployment -n mirrord mirrord-license-server
```

--------------------------------

### Configure mirrord Build Tool Skipping

Source: https://metalbear.co/mirrord/docs/reference/configuration

Defines whether mirrord should skip common build tools during operation. Useful for combined build and run commands. Defaults to `true`.

```APIDOC
skip_build_tools: boolean
  - Description: Allows mirrord to skip build tools. Useful when running command lines that build and run the application in a single command.
  - Default: true
  - Built-in Build-Tools: ["as", "cc", "ld", "go", "air", "asm", "cc1", "cgo", "dlv", "gcc", "git", "link", "math", "cargo", "hpack", "rustc", "compile", "collect2", "cargo-watch", "debugserver"]
```

--------------------------------

### Resolved Kafka Client Properties File (Basic)

Source: https://metalbear.co/mirrord/docs/using-mirrord/queue-splitting

The resulting `.properties` file generated by the mirrord Operator from the basic `MirrordKafkaClientConfig` example.

```properties
bootstrap.servers=kafka.default.svc.cluster.local:9092
```

--------------------------------

### Specify Additional Build Tools to Skip in mirrord

Source: https://metalbear.co/mirrord/docs/reference/configuration

Allows mirrord to skip user-specified build tools. Requires `skip_build_tools` to be enabled. Similar to `skip_processes` but also skips SIP patching.

```APIDOC
skip_extra_build_tools: string | string[]
  - Description: Allows mirrord to skip the specified build tools. Useful when running command lines that build and run the application in a single command.
  - Dependency: Must also enable `skip_build_tools` for this to take an effect.
  - Behavior: Similar to `skip_processes`, except that here it also skips SIP patching.
  - Accepts: A single value, or an array of values.
```

```JSON
{
 "skip_extra_build_tools": ["bash", "node"]
}
```

--------------------------------

### Experimental mirrord Configuration Flags

Source: https://metalbear.co/mirrord/docs/reference/configuration

Details on experimental configuration flags in mirrord, which may be subject to change or removal. These flags control specific behaviors like proxy handling, certificate trust, and file creation.

```APIDOC
ignore_system_proxy_config:
  - Disables any system wide proxy configuration for affecting the running application.
trust_any_certificate:
  - Enables trusting any certificate on macOS, useful for specific scenarios.
use_dev_null:
  - Uses /dev/null for creating local fake files (should be better than using /tmp).
```

--------------------------------

### Update APT Package List

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

Updates the package list for the Advanced Package Tool (APT) on Debian/Ubuntu-based Linux distributions. This command is crucial before installing new software to ensure the system has access to the latest package information and dependencies.

```Shell
sudo apt update
```

--------------------------------

### mirrord Internal Proxy Configuration Reference

Source: https://metalbear.co/mirrord/docs/reference/configuration

Comprehensive documentation for configuring mirrord's internal proxy, which facilitates local layer connections to the remote agent. Includes settings for idle timeouts, logging behavior, and log destinations.

```APIDOC
internal_proxy:
  start_idle_timeout: integer (seconds)
    Description: How much time to wait for the first connection to the proxy in seconds. Useful for debugging scenarios.
    Default: 30
  idle_timeout: integer (seconds)
    Description: How much time to wait while no active connections before exiting. Addresses scenarios where layers skip proxy usage.
    Default: 5
  json_log: boolean
    Description: Whether the proxy should output logs in JSON format. If false, logs are human-readable.
    Default: true
  log_destination: string (path)
    Description: Set the log file destination for the internal proxy.
    Default: Randomized path inside temporary directory.
  log_level: string
    Description: Set the log level for the internal proxy, following RUST_LOG convention (e.g., `mirrord=trace`).
    Default: `mirrord=info,warn`
```

--------------------------------

### mirrord Feature Configuration

Source: https://metalbear.co/mirrord/docs/reference/configuration

Comprehensive configuration for various mirrord features, including environment variables, file system operations, and network settings. This allows fine-grained control over how mirrord intercepts and handles different aspects of the application's behavior.

```JSON
{
  "feature": {
    "env": {
      "include": "DATABASE_USER;PUBLIC_ENV",
      "exclude": "DATABASE_PASSWORD;SECRET_ENV",
      "override": {
        "DATABASE_CONNECTION": "db://localhost:7777/my-db",
        "LOCAL_BEAR": "panda"
      }
    },
    "fs": {
      "mode": "write",
      "read_write": ".+\\.json" ,
      "read_only": [ ".+\\.yaml", ".+important-file\\.txt" ],
      "local": [ ".+\\.js", ".+\\.mjs" ]
    },
    "network": {
      "incoming": {
        "mode": "steal",
        "http_filter": {
          "header_filter": "host: api\\..+"
        },
        "port_mapping": [[ 7777, 8888 ]],
        "ignore_localhost": false,
        "ignore_ports": [9999, 10000]
      },
      "outgoing": {
        "tcp": true,
        "udp": true,
        "filter": {
          "local": ["tcp://1.1.1.0/24:1337", "1.1.5.0/24", "google.com", ":53"]
        },
        "ignore_localhost": false,
        "unix_streams": "bear.+"
      },
      "dns": false
    },
    "copy_target": false,
    "hostname": true
  }
}
```

```APIDOC
feature (object):
  - Controls mirrord features.
  - See the technical reference for more details on what each feature does.
  - The `env`, `fs`, and `network` options have support for a shortened version.
  Properties:
    env (object, optional):
      - Configuration for environment variable handling.
      Properties:
        include (string, optional):
          - Semicolon-separated list of environment variables to include.
        exclude (string, optional):
          - Semicolon-separated list of environment variables to exclude.
        override (object, optional):
          - Key-value pairs to override specific environment variables.
    fs (object, optional):
      - Configuration for file system operations.
      Properties:
        mode (string, optional):
          - File system interception mode (e.g., "write").
        read_write (string, optional):
          - Regular expression for files to be intercepted for read/write operations.
        read_only (array of strings, optional):
          - List of regular expressions for files to be intercepted for read-only operations.
        local (array of strings, optional):
          - List of regular expressions for files to be handled locally (not intercepted).
    network (object, optional):
      - Configuration for network interception.
      Properties:
        incoming (object, optional):
          - Settings for incoming network traffic.
          Properties:
            mode (string, optional):
              - Incoming traffic interception mode (e.g., "steal").
            http_filter (object, optional):
              - HTTP filtering options.
              Properties:
                header_filter (string, optional):
                  - Regular expression to filter HTTP requests based on headers (e.g., "host: api\\..+").
            port_mapping (array of arrays of integers, optional):
              - List of port mappings (e.g., [[local_port, remote_port]]).
            ignore_localhost (boolean, optional):
              - Whether to ignore localhost connections.
            ignore_ports (array of integers, optional):
              - List of ports to ignore for incoming traffic.
        outgoing (object, optional):
          - Settings for outgoing network traffic.
          Properties:
            tcp (boolean, optional):
              - Whether to intercept outgoing TCP connections.
            udp (boolean, optional):
              - Whether to intercept outgoing UDP connections.
            filter (object, optional):
              - Outgoing traffic filtering options.
              Properties:
                local (array of strings, optional):
                  - List of network addresses/hostnames to handle locally (not intercepted).
            ignore_localhost (boolean, optional):
              - Whether to ignore localhost connections for outgoing traffic.
            unix_streams (string, optional):
              - Regular expression for Unix domain sockets to intercept.
        dns (boolean, optional):
          - Whether to intercept DNS requests.
    copy_target (boolean, optional):
      - Whether to copy the target application.
    hostname (boolean, optional):
      - Whether to intercept hostname resolution.
```

--------------------------------

### Add MetalBear Helm Repository

Source: https://metalbear.co/mirrord/docs/managing-mirrord/license-server

This command adds the official MetalBear Helm chart repository to your Helm client. This step is necessary to enable the installation of mirrord components, including the License Server, using Helm charts.

```Shell
helm repo add metalbear-co https://metalbear-co.github.io/charts
```

--------------------------------

### mirrord Core Configuration Options

Source: https://metalbear.co/mirrord/docs/reference/configuration

This section documents key configuration parameters for mirrord, covering telemetry data submission and the handling of HTTP/HTTPS proxy environment variables. These settings allow users to control mirrord's behavior in different network environments and privacy preferences.

```APIDOC
mirrord Configuration Options:

telemetry: boolean
  - Controls whether or not mirrord sends telemetry data to MetalBear cloud.
  - Telemetry sent doesn’t contain personal identifiers or any data that should be considered sensitive. It is used to improve the product.
  - For more information: https://github.com/metalbear-co/mirrord/blob/main/TELEMETRY.md

use_proxy: boolean
  - When disabled, mirrord will remove HTTP[S]_PROXY env variables before doing any network requests.
  - This is useful when the system sets a proxy but you don’t want mirrord to use it.
  - This also applies to the mirrord process (as it just removes the env).
  - If the remote pod sets this env, the mirrord process will still use it.
```

--------------------------------

### Execute Node.js project with mirrord in targetless mode

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

This is a specific example of using `mirrord exec` in 'targetless' mode, which allows mirrord to run without connecting to a specific Kubernetes pod. This is useful for local development and testing of applications like a Node.js `app.mjs`.

```bash
mirrord exec --target “targetless” node app.mjs
```

--------------------------------

### Navigate to IntelliJ JBR security directory in WSL

Source: https://metalbear.co/mirrord/docs/using-mirrord/wsl

This command changes the current directory in your WSL terminal to the Java Runtime Environment's security directory, which is part of the IntelliJ IDE installation. This path is relevant for managing SSL certificates, especially when troubleshooting 'PKIX path building failed' errors.

```bash
cd ~/.local/share/JetBrains/Toolbox/apps/{NAME-OF-IDE}/jbr/lib/security
```

--------------------------------

### Mirrord Agent Configuration Parameters

Source: https://metalbear.co/mirrord/docs/reference/configuration

Defines various configuration options for the mirrord agent, including its privilege level, resource requirements, service account, startup timeout, and pod tolerations. These settings control the agent's deployment and behavior within the Kubernetes environment.

```APIDOC
agent.privileged
  - Description: Run the mirror agent as a privileged container. Has no effect in targetless mode.
  - Type: boolean
  - Default: false
  - Notes: Might be needed in strict environments like Bottlerocket.

agent.resources
  - Description: Set pod resource requirements for the agent (not applicable for ephemeral agents).
  - Type: object
  - Default:
    {
      "requests": {"cpu": "1m", "memory": "1Mi"},
      "limits": {"cpu": "100m", "memory": "100Mi"}
    }
  - Example:
    {
      "requests":
      {
        "cpu": "1m",
        "memory": "1Mi"
      },
      "limits":
      {
        "cpu": "100m",
          "memory": "100Mi"
      }
    }

agent.service_account
  - Description: Allows setting a custom Service Account for the agent Job and Pod.
  - Type: string
  - Example:
    {
      "service_account": "my-service-account"
    }

agent.startup_timeout
  - Description: Controls how long to wait for the agent to finish initialization. Mirrord exits if initialization exceeds this value.
  - Type: integer (seconds)
  - Default: 60

agent.tolerations
  - Description: Set pod tolerations for the agent (not applicable for ephemeral agents). Set to an empty array for no tolerations.
  - Type: array of objects
  - Default: operator: Exists
  - Example:
    [
      {
        "key": "meow", "operator": "Exists", "effect": "NoSchedule"
      }
    ]

agent.ttl
  - Description: Controls how long the agent pod persists after the agent exits (in seconds). Useful for collecting logs.
  - Type: integer (seconds)
  - Default: 1
```

--------------------------------

### Mirrord Outgoing Network Configuration and Filtering

Source: https://metalbear.co/mirrord/docs/reference/configuration

Documents the configuration options for tunneling outgoing network operations through mirrord, including general settings and detailed traffic filtering capabilities.

```APIDOC
feature.network.outgoing:
  - Description: Tunnels outgoing network operations through mirrord. The `remote` and `local` config for this feature are mutually exclusive.
  - Type: Object

feature.network.outgoing.filter:
  - Description: Filters used to send specific traffic from either the remote pod or the local app. This option specifies when outgoing traffic is sent from the remote pod (default when outgoing is enabled) or from the local app (default when outgoing is disabled).
  - Type: Object with `local` or `remote` properties, each containing an array of strings.
  - Valid Values Pattern: `[protocol]://[name|address|subnet/mask]:[port]`
  - Examples:
    - `{"remote": ["udp://1.1.1.0/24:1337"]}`: Only UDP traffic on subnet `1.1.1.0/24` on port 1337 will go through the remote pod.
    - `{"remote": ["google.com:1337", "google.com:7331"]}`: Only UDP and TCP traffic on resolved address of `google.com` on ports 1337 and 7331 will go through the remote pod.
    - `{"local": ["tcp://localhost:1337"]}`: Only TCP traffic on `localhost` on port 1337 will go through the local app, the rest will be emitted remotely in the cluster.
    - `{"local": [":1337", ":7331"]}`: Only outgoing traffic on port 1337 and 7331 will go through the local app.

feature.network.outgoing.ignore_localhost:
  - Description: Specifies whether to ignore localhost traffic for outgoing tunneling.
  - Type: Boolean
  - Default: `false`

feature.network.outgoing.tcp:
  - Description: Enables or disables TCP outgoing traffic tunneling.
  - Type: Boolean
  - Default: `true`
```

--------------------------------

### Enable JSON Logging for Mirrord Agent

Source: https://metalbear.co/mirrord/docs/reference/configuration

Determines the log output format for the mirrord agent. Setting this to `true` enables JSON-formatted logs, which are often preferred for structured logging and analysis.

```JSON
{
  "agent": {
    "json_log": true
  }
}
```

--------------------------------

### Mirrord Agent Configuration Parameters

Source: https://metalbear.co/mirrord/docs/reference/configuration

Comprehensive documentation for various configuration parameters available for the mirrord agent, covering its behavior, resource management, and integration within a Kubernetes environment. These parameters control aspects like agent lifecycle, security capabilities, image handling, and Kubernetes scheduling.

```APIDOC
agent.check_out_of_pods:
  - Description: Determine if to check whether there is room for agent job in target node. (Not applicable when using ephemeral containers feature). Can be disabled if the check takes too long and you are sure there is enough resources on each node.
  - Type: Boolean
agent.communication_timeout:
  - Description: Controls how long the agent lives when there are no connections. Each connection has its own heartbeat mechanism, so even if the local application has no messages, the agent stays alive until there are no more heartbeat messages.
  - Type: Duration (e.g., "1h", "30m", "10s")
agent.disabled_capabilities:
  - Description: Disables specified Linux capabilities for the agent container. If nothing is disabled here, agent uses NET_ADMIN, NET_RAW, SYS_PTRACE and SYS_ADMIN. Has no effect when using the targetless mode, as targetless agent containers have no capabilities.
  - Type: Array of Strings (e.g., ["NET_ADMIN"])
agent.dns:
  - Description: Configuration related to DNS resolution for the agent. (Further details would be provided if available).
  - Type: Object/Boolean
agent.ephemeral:
  - Description: Runs the agent as an ephemeral container. Not compatible with targetless runs.
  - Type: Boolean
  - Default: `false`
agent.exclude_from_mesh:
  - Description: When running the agent as an ephemeral container, use this option to exclude the agent’s port from the service mesh sidecar proxy.
  - Type: Boolean
agent.flush_connections:
  - Description: Flushes existing connections when starting to steal, might fix issues where connections aren’t stolen (due to being already established).
  - Type: Boolean
  - Default: `true`
agent.image_pull_policy:
  - Description: Controls when a new agent image is downloaded. Supports "IfNotPresent", "Always", "Never", or any valid Kubernetes image pull policy.
  - Type: String
  - Valid Values: "IfNotPresent", "Always", "Never"
  - Default: "IfNotPresent"
agent.namespace:
  - Description: Namespace where the agent shall live. Ignored in targetless runs or when the agent is run as an ephemeral container. Defaults to the current Kubernetes namespace.
  - Type: String
  - Default: Current Kubernetes namespace
agent.network_interface:
  - Description: Which network interface to use for mirroring. The default behavior is try to access the internet and use that interface. If that fails it uses `eth0`.
  - Type: String
  - Default: Determined dynamically, falls back to `eth0`
agent.nftables:
  - Description: Use iptables-nft instead of iptables-legacy. Needed if your mesh uses nftables instead of iptables-legacy.
  - Type: Boolean
  - Default: `false`
```

--------------------------------

### Select Mirrord Profiles in User Configuration

Source: https://metalbear.co/mirrord/docs/managing-mirrord/profiles

These JSON snippets demonstrate how to select a mirrord profile in the user's mirrord configuration. It shows examples for referencing both cluster-wide profiles by name and namespaced profiles using the `namespace/name` format.

```JSON
{
  "profile": "example-profile"
}
```

```JSON
{
  "profile": "examle-namespace/example-profile"
}
```

--------------------------------

### Mirrord Experimental Feature Toggles

Source: https://metalbear.co/mirrord/docs/reference/configuration

Configuration options for experimental features in mirrord. These settings are unstable and should only be used under guidance from the mirrord team. They include toggles for `SO_REUSEADDR` on macOS, exec hooks on Linux, IPv6 interface hiding, and idle local HTTP connection timeouts.

```APIDOC
experimental.disable_reuseaddr
  - Description: Disables the `SO_REUSEADDR` socket option on sockets that mirrord steals/mirrors. This option applies only on macOS and addresses issues with incorrect stealing.
  - Type: boolean
  - Reference: https://github.com/metalbear-co/mirrord/issues/2819

experimental.enable_exec_hooks_linux
  - Description: Enables exec hooks on Linux. This can fix issues where applications share sockets with child commands (e.g., Python web servers with reload), but the feature is not stable and may cause other issues.
  - Type: boolean

experimental.hide_ipv6_interfaces
  - Description: Enables a `getifaddrs` hook that removes IPv6 interfaces from the list returned by libc.
  - Type: boolean

experimental.idle_local_http_connection_timeout
  - Description: Sets a timeout for idle local HTTP connections (in milliseconds). This determines how long cached connections are kept for reuse after a request is delivered. Set to 0 to disable caching.
  - Type: integer (milliseconds)
  - Default: 3000
```

--------------------------------

### Specify Kubernetes Target for mirrord Session

Source: https://metalbear.co/mirrord/docs/reference/configuration

Defines the Kubernetes pod, deployment, or other resource mirrord should target for a session. Supports simplified string formats and detailed object configurations for namespace and container specification.

```APIDOC
target: string | object
  - Description: Specifies the target and namespace to target.
  - Simplified Configuration Supports:
    - `targetless`
    - `pod/{pod-name}[/container/{container-name}]`
    - `deployment/{deployment-name}[/container/{container-name}]`
    - `rollout/{rollout-name}[/container/{container-name}]`
    - `job/{job-name}[/container/{container-name}]` (Requires mirrord Operator and `copy_target` feature)
    - `cronjob/{cronjob-name}[/container/{container-name}]` (Requires mirrord Operator and `copy_target` feature)
    - `statefulset/{statefulset-name}[/container/{container-name}]` (Requires mirrord Operator)
    - `service/{service-name}[/container/{container-name}]` (Requires mirrord Operator)
    - `replicaset/{replicaset-name}[/container/{container-name}]` (Requires mirrord Operator)

target.namespace: string
  - Description: Namespace where the target lives. For targetless runs, this is the namespace in which remote networking is done.
  - Default: The Kubernetes user’s default namespace (defined in Kubernetes context).

target.path: string
  - Description: Specifies the Kubernetes resource to target.
  - Default: `targetless` if not given.
  - Note: Targeting services and whole workloads is available only in mirrord for Teams. If you target a workload without the mirrord Operator, it will choose a random pod replica to work with.
  - Supports:
    - `targetless`
    - `pod/{pod-name}[/container/{container-name}]`
    - `deployment/{deployment-name}[/container/{container-name}]`
    - `rollout/{rollout-name}[/container/{container-name}]`
    - `job/{job-name}[/container/{container-name}]` (requires mirrord Operator and the `copy_target` feature)
    - `cronjob/{cronjob-name}[/container/{container-name}]` (requires mirrord Operator and the `copy_target` feature)
    - `statefulset/{statefulset-name}[/container/{container-name}]` (requires mirrord Operator)
    - `service/{service-name}[/container/{container-name}]` (requires mirrord Operator)
    - `replicaset/{replicaset-name}[/container/{container-name}]` (requires mirrord Operator)
```

```JSON
{
 "target": "pod/bear-pod"
}
```

```JSON
{
  "target": "pod/bear-pod/container/bear-pod-container"
}
```

```JSON
{
 "target": {
   "path": {
     "pod": "bear-pod",
     "container": "bear-pod-container"
   },
   "namespace": "bear-pod-namespace"
 }
}
```

```JSON
{
  "target": {
    "path": "targetless",
    "namespace": "bear-namespace"
  }
}
```

--------------------------------

### MirrordKafkaClientConfig Inheritance YAML Example

Source: https://metalbear.co/mirrord/docs/using-mirrord/queue-splitting

Demonstrates property inheritance between two `MirrordKafkaClientConfig` resources. The `with-client-id` configuration inherits from `base-config`, showing how properties can be added, overridden, or explicitly removed by setting `value: null`.

```YAML
apiVersion: queues.mirrord.metalbear.co/v1alpha
kind: MirrordKafkaClientConfig
metadata:
  name: base-config
  namespace: mirrord
spec:
  properties:
  - name: bootstrap.servers
    value: kafka.default.svc.cluster.local:9092
  - name: message.send.max.retries
    value: 4
```

```YAML
apiVersion: queues.mirrord.metalbear.co/v1alpha
kind: MirrordKafkaClientConfig
metadata:
  name: with-client-id
  namespace: mirrord
spec:
  parent: base-config
  properties:
  - name: client.id
    value: mirrord-operator
  - name: message.send.max.retries
    value: null
```

--------------------------------

### mirrord File System Feature Configuration

Source: https://metalbear.co/mirrord/docs/reference/configuration

Comprehensive configuration for mirrord's file system operations, including defining read/write modes, specifying patterns for non-existent files, read-only and read-write remote synchronization, and setting buffer sizes for read-only files.

```APIDOC
feature.fs.mode:
  Description: Configuration for enabling read-only or read-write file operations. These options are overridden by user specified overrides and mirrord default overrides. If "localwithoverrides" is set, some files can be read/write remotely based on default/user specified settings. Default option for general file configuration.
  Accepted Values: "local", "localwithoverrides", "read", "write"

feature.fs.not_found:
  Description: Specify file path patterns that if matched will be treated as non-existent.

feature.fs.read_only:
  Description: Specify file path patterns that if matched will be read from the remote. If file matching the pattern is opened for writing or read/write it will be opened locally.

feature.fs.read_write:
  Description: Specify file path patterns that if matched will be read and written to the remote.

feature.fs.readonly_file_buffer:
  Description: Sets buffer size for read-only remote files in bytes. By default, the value is 128000 bytes (128 kB). Setting the value to 0 disables file buffering. Otherwise, read-only remote files will be read in chunks and buffered locally, improving performance when the user application reads data in small portions.
```
Tokens:
Raw