Specify file path patterns that if matched will be opened locally.

Specify map of patterns that if matched will replace the path according to specification.

Capture groups are allowed.

Example:

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

Will do the next replacements for any io operation

/home/johndoe/dev/tomcat/context.xml => /etc/tomcat/context.xml /home/johndoe/dev/config/api/app.conf => /mnt/configs/johndoe-api/app.conf

• Relative paths: this feature (currently) does not apply mappings to relative paths, e.g. ../dev.

Specify file path patterns that if matched will be treated as non-existent.

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.

Specify file path patterns that if matched will be read and written to the remote.

Sets buffer size for read-only remote files in bytes. By default, the value is 128000 bytes, or 128 kB.

Setting the value to 0 disables file buffering. Otherwise, read-only remote files will be read in chunks and buffered locally. This improves performance when the user application reads data in small portions.

Allows setting up custom annotations for the agent Job and Pod.

{
  "agent": {
    "annotations": {
      "cats.io/inject": "enabled"
      "prometheus.io/scrape": "true",
      "prometheus.io/port": "9000"
    }
  }
}

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

Clean leftover iptables rules and start the new agent instead of erroring out when there are existing mirrord rules in the target's iptables.

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.

Add relevant labels and annotations to agent pods/jobs to prevent service mesh sidecar injections. Defaults to true.

Only affects istio, linkerd, kuma.

If nothing is disabled here, agent uses:

1. NET_ADMIN,
2. SYS_PTRACE,
3. SYS_ADMIN.

Has no effect when using the targetless mode, as targetless agent containers have no capabilities.

Runs the agent as an ephemeral container.

Not compatible with targetless runs.

Defaults to false.

When running the agent as an ephemeral container, use this option to exclude the agent's port from the service mesh sidecar proxy.

Flushes existing connections when starting to steal, might fix issues where connections aren't stolen (due to being already established)

Defaults to true.

Name of the agent's docker image.

Useful when a custom build of mirrord-agent is required, or when using an internal registry.

Defaults to the latest stable image "ghcr.io/metalbear-co/mirrord:latest".

{
  "agent": {
    "image": "internal.repo/images/mirrord:latest"
  }
}

Complete setup:

{
  "agent": {
    "image": {
      "registry": "internal.repo/images/mirrord",
      "tag": "latest"
    }
  }
}

Can also be controlled via MIRRORD_AGENT_IMAGE, MIRRORD_AGENT_IMAGE_REGISTRY, and MIRRORD_AGENT_IMAGE_TAG. MIRRORD_AGENT_IMAGE takes precedence, followed by config values for registry/tag, then environment variables for registry/tag.

Controls when a new agent image is downloaded.

Supports "IfNotPresent", "Always", "Never", or any valid kubernetes image pull policy

Defaults to "IfNotPresent"

List of secrets the agent pod has access to.

Takes an array of entries with the format { name: <secret-name> }.

Read more here.

{
  "agent": {
    "image_pull_secrets": [
      { "name": "secret-key-1" },
      { "name": "secret-key-2" }
    ]
  }
}

Sets whether Mirrord-Agent headers are injected into HTTP responses that went through the agent.

Possible values for the header:

• passed-through: set when the request was not sent to the local app (perhaps because it didn't match the filters)

• forwarded-to-client: set when the request was sent to the local app

Time limit for running jaq queries, in milliseconds. Defaults to 500ms.

Controls whether the agent produces logs in a human-friendly format, or json.

{
  "agent": {
    "json_log": true
  }
}

Allows setting up custom labels for the agent Job and Pod.

{
  "agent": {
    "labels": { "user": "meow", "state": "asleep" }
  }
}

Log level for the agent.

Supports "trace", "debug", "info", "warn", "error", or any string that would work with RUST_LOG.

{
  "agent": {
    "log_level": "mirrord=debug,warn"
  }
}

Maximum size, in bytes, of HTTP request body buffers. Used for temporarily storing bodies of incoming HTTP requests to run body filters. HTTP body filters will not match any requests with bodies larger than this.

Maximum timeout, in milliseconds, for receiving HTTP request bodies. HTTP body filters will not match any requests whose bodies do not arrive within this timeout.

Enables prometheus metrics for the agent pod.

You might need to add annotations to the agent pod depending on how prometheus is configured to scrape for metrics.

{
  "agent": {
    "metrics": "0.0.0.0:9000"
  }
}

Namespace where the agent shall live.

Note: ignored in targetless runs or when the agent is run as an ephemeral container.

Defaults to the current kubernetes namespace.

Determines which iptables backend will be used for traffic redirection.

If set to true, the agent will use iptables-nft. If set to false, the agent will use iptables-legacy. If not set, the agent will try to detect the correct backend at runtime.

Allows setting up custom node selector for the agent Pod. Applies only to targetless runs, as targeted agent always runs on the same node as its target container.

{
  "agent": {
    "node_selector": { "kubernetes.io/hostname": "node1" }
  }
}

Specifies the priority class to assign to the agent pod.

{
  "agent": {
    "priority_class": "my-priority-class-name"
  }
}

In some cases, the agent pod may fail to schedule due to node resource constraints. Setting a priority class allows you to explicitly assign an existing priority class from your cluster to the agent pod, increasing its priority relative to other workloads.

Run the mirror agent as privileged container. Defaults to false.

Might be needed in strict environments such as Bottlerocket.

Has no effect when using the targetless mode, as targetless agent containers are never privileged.

Set pod resource requirements. (not with ephemeral agents) Default is

{
  "agent": {
    "resources": {
      "requests":
      {
        "cpu": "1m",
        "memory": "1Mi"
      },
      "limits":
      {
        "cpu": "100m",
        "memory": "100Mi"
      }
    }
  }
}

Agent pod security context (not with ephemeral agents). Support seccomp profile and app armor profile.

Allows setting up custom Service Account for the agent Job and Pod.

{
  "agent": {
    "service_account": "my-service-account"
  }
}

Controls how long to wait for the agent to finish initialization.

If initialization takes longer than this value, mirrord exits.

Defaults to 60.

Set pod tolerations. (not with ephemeral agents).

Defaults to operator: Exists.

{
  "agent": {
    "tolerations": [
        {
          "key": "meow", "operator": "Exists", "effect": "NoSchedule"
        }
    ]
  }
}

Set to an empty array to have no tolerations at all

Controls how long the agent pod persists for after the agent exits (in seconds).

Can be useful for collecting logs.

Defaults to 1.

Name of the secret.

Path to a directory where mirrord ci will flush application's stdout and stderr.

Defaults to /tmp/mirrord/.

Individual database connection parameter sources. At least one parameter must be specified. Each parameter is either a plain string (env var name) or an object with secret and key.

Any extra args to use when creating the sidecar mirrord-cli container.

This is useful when you want to use portforwarding, passing -p local:container won't work for main command but adding them here will work

{
  "container": {
    "cli_extra_args": ["-p", "local:container"]
  }
}

Tag of the mirrord-cli image you want to use.

Defaults to "ghcr.io/metalbear-co/mirrord-cli:<cli version>".

Path of the mirrord-layer lib inside the specified mirrord-cli image.

Don't add --rm to sidecar command to prevent cleanup.

When usingmirrord container with external_proxy TLS enabled (is enabled by default), you can specify the path where the certificate .pem file will be created, in the cli container.

Defaults to "/opt/mirrord/tls/mirrord-tls.pem".

Allows to override the IP address for the internal proxy to use when connecting to the host machine from within the container.

{
  "container": {
    "override_host_ip": "172.17.0.1" // usual resolution of value from `host.docker.internal`
  }
}

This should be useful if your host machine is exposed with a different IP address than the one bound as host.

• If you're running inside WSL, and encountering problems, try setting external_proxy.host_ip to 0.0.0.0, and this to the internal container runtime address (for docker, this would be what host.docker.internal resolved to, which by default is 192.168.65.254). You can find this ip by resolving it from inside a running container, e.g. docker run --rm -it {image-with-nslookup} nslookup host.docker.internal

Platform specification for the target container (e.g., "linux/amd64", "linux/arm64").

When specified, the target container will run with this platform, while the internal proxy container will still run on the native platform and contain both architectures (x64/arm64). The LD_PRELOAD will automatically use the correct architecture.

{
  "container": {
    "platform": "linux/amd64"
  }
}

Deployment to mirror.

Unstable: the precise syntax of this config is subject to change.

Allows for passing environment variables from an env file.

These variables will override environment fetched from the remote target.

Include the remote environment variables in the local process that are NOT specified by this option. Variable names can be matched using * and ? where ? matches exactly one occurrence of any character and * matches arbitrary many (including zero) occurrences of any character.

Some of the variables that are excluded by default: PATH, HOME, HOMEPATH, CLASSPATH, JAVA_EXE, JAVA_HOME, PYTHONPATH.

Can be passed as a list or as a semicolon-delimited string (e.g. "VAR;OTHER_VAR").

Include only these remote environment variables in the local process. Variable names can be matched using * and ? where ? matches exactly one occurrence of any character and * matches arbitrary many (including zero) occurrences of any character.

Can be passed as a list or as a semicolon-delimited string (e.g. "VAR;OTHER_VAR").

Some environment variables are excluded by default (PATH for example), including these requires specifying them with include

Allows for changing the way mirrord loads remote environment variables. If set, the variables are fetched after the user application is started.

This setting is meant to resolve issues when using mirrord via the IntelliJ plugin on WSL and the remote environment contains a lot of variables.

Specify map of patterns that if matched will replace the value according to specification.

Capture groups are allowed.

Example:

{
  ".+_TIMEOUT": "10000"
  "LOG_.+_VERBOSITY": "debug"
  "(\w+)_(\d+)": "magic-value"
}

Will do the next replacements for environment variables that match:

• CONNECTION_TIMEOUT: 500 => CONNECTION_TIMEOUT: 10000

• LOG_FILE_VERBOSITY: info => LOG_FILE_VERBOSITY: debug

• DATA_1234: common-value => DATA_1234: magic-value

Allows setting or overriding environment variables (locally) with a custom value.

For example, if the remote pod has an environment variable REGION=1, but this is an undesirable value, it's possible to use override to set REGION=2 (locally) instead.

Environment specified here will also override variables passed via the env file.

Allows unsetting environment variables in the executed process.

This is useful for when some system/user-defined environment like AWS_PROFILE make the application behave as if it's running locally, instead of using the remote settings. The unsetting happens from extension (if possible)/CLI and when process initializes. In some cases, such as Go the env might not be able to be modified from the process itself. This is case insensitive, meaning if you'd put AWS_PROFILE it'd unset both AWS_PROFILE and Aws_Profile and other variations.

Configuration for inspecting and modifying apple variables. macOS only.

mirrord will open a URL for initiating mirrord browser extension to automatically inject HTTP header that matches the HTTP filter configured in feature.network.incoming.http_filter.header_filter.

Disables the SO_REUSEADDR socket option on sockets that mirrord steals/mirrors. On macOS the application can use the same address many times but then we don't steal it correctly. This probably should be on by default but we want to gradually roll it out. https://github.com/metalbear-co/mirrord/issues/2819 This option applies only on macOS.

Useful when the user's application loads a c-shared golang library dynamically.

Defaults to false.

Whether to terminate the session when a permission denied error occurs during DNS resolution. This error often means that the Kubernetes cluster is hardened, and the mirrord-agent is not fully functional without agent.privileged enabled.

Defaults to true

DEPRECATED, WILL BE REMOVED

Enables exec hooks on Linux. Enable Linux hooks can fix issues when the application shares sockets with child commands (e.g Python web servers with reload), but the feature is not stable and may cause other issues.

Forces hooking all instances of the connect function. In very niche cases the connect function has multiple exports and this flag makes us hook all of the instances. https://linear.app/metalbear/issue/MBE-1385/mirrord-container-curl-doesnt-work-for-php-curl

Defaults to true

DEPRECATED, WILL BE REMOVED

Enables getifaddrs hook that removes IPv6 interfaces from the list returned by libc.

Enables hooking the rename function.

Useful if you need file remapping and your application uses rename, i.e. php-fpm, twig, to create and rename temporary files.

DEPRECATED, WILL BE REMOVED

Sets a timeout for idle local HTTP connections (in milliseconds).

HTTP requests stolen with a filter are delivered to the local application from a HTTP connection made from the local machine. Once a request is delivered, the connection is cached for some time, so that it can be reused to deliver the next request.

This timeout determines for how long such connections are cached.

Set to 0 to disable caching local HTTP connections (connections will be dropped as soon as the request is delivered).

Defaults to 3000ms.

Disables any system wide proxy configuration for affecting the running application.

Configuration for adding artificial latency to outgoing network operations.

Enables better support for outgoing connections using non-blocking TCP sockets. For technical reasons, enabling this will cause getsockname to always return a localhost address.

Defaults to true in OSS. Defaults to false in mfT.

Writes basic fork-safe SIP patching logs to a destination file. Useful for seeing the state of SIP when stdout may be affected by another process.

Extract pre-built SIP utility binaries into ~/.mirrord/binaries on macOS and uses them in place of SIP-patching the originals. This shouldn't be used unless someone from MetalBear/mirrord tells you to.

Defaults to true in OSS. Defaults to false in mfT.

https://github.com/metalbear-co/mirrord/issues/2421#issuecomment-2093200904

Enables trusting any certificate on macOS, useful for https://github.com/golang/go/issues/51991#issuecomment-2059588252

Uses /dev/null for creating local fake files (should be better than using /tmp)

Specify a custom host ip addr to listen on.

This address must be accessible from within the container. If not specified, mirrord will try and resolve a local address to use.

• If you're running inside WSL, and encountering problems, try setting this to 0.0.0.0, and container.override_host_ip to the internal container runtime address (for docker, this would be what host.docker.internal resolved to, which by default is 192.168.65.254).

How much time to wait while we don't have any active connections before exiting.

Common cases would be running a chain of processes that skip using the layer and don't connect to the proxy.

{
  "external_proxy": {
    "idle_timeout": 30
  }
}

Whether the proxy should output logs in JSON format. If false, logs are output in human-readable format.

Defaults to true.

Set the log destination for the external proxy.

1. If the provided path ends with a separator (/ on UNIX, \ on Windows), it will be treated as a path to directory where the log file should be created.
2. Otherwise, if the path exists, mirrord will check if it's a directory or not.
3. Otherwise, it will be treated as a path to the log file.

mirrord will auto create all parent directories.

Defaults to a randomized path inside the temporary directory.

Set the log level for the external proxy.

The value should follow the RUST_LOG convention (i.e mirrord=trace).

Defaults to mirrord=info,warn.

How much time to wait for the first connection to the external proxy in seconds.

Common cases would be running with dlv or any other debugger, which sets a breakpoint on process execution, delaying the layer startup and connection to the external proxy.

{
  "external_proxy": {
    "start_idle_timeout": 60
  }
}

Whether to use TLS or a plain TCP when accepting a connection from the internal proxy sidecar.

Creates a new copy of the target. mirrord will use this copy instead of the original target (e.g. intercept network traffic). This feature requires a mirrord operator.

This feature is not compatible with rollout targets and running without a target (targetless mode).

Configuration for the database branching feature.

Should mirrord return the hostname of the target pod when calling gethostname

Sensible defaults that improve the experience for most users. Each flag can be disabled individually if it conflicts with your setup.

Configuration for preview environments.

Define filters to split queues by, and make your local application consume only messages that match those filters. If you don't specify any filter for a queue that is however declared in the MirrordWorkloadQueueRegistry of the target you're using, a match-nothing filter will be used, and your local application will not receive any messages from that queue.

Specifies the number of DNS resolution attempts the agent will make before failing. Setting this too high may cause the internal proxy to time out and exit.

Specifies how long (in seconds) the agent will wait for a DNS response before timing out. If not specified the agent uses a default value of 1 second. Setting this too high may cause the internal proxy to time out and exit.

An array of HTTP filters.

Each inner filter specifies a header, path, method, body, or jq filter. Requests must match all of the filters to be stolen.

Cannot be an empty list.

Example:

{
  "all_of": [
    { "header": "^baggage: .*mirrord-session={{ key }}.*$" },
    { "path": "^/api/v1/my-endpoint$" },
    { "method": "POST" }
  ]
}

An array of HTTP filters.

Each inner filter specifies a header, path, method, body, or jq filter. Requests must match at least one of the filters to be stolen.

Cannot be an empty list.

Example:

{
  "any_of": [
    { "header": "^baggage: .*mirrord-session={{ key }}.*$" },
    { "header": "^tracestate: .*mirrord-session={{ key }}.*$" },
    { "path": "^/api/v1/my-endpoint$" }
  ]
}

Matches the request based on the contents of its body.

Supports regexes validated by the fancy-regex crate.

The HTTP traffic feature converts the HTTP headers to HeaderKey: HeaderValue, case-insensitive.

The recommended pattern is to match a W3C baggage or tracestate entry such as mirrord-session={{ key }}.

Supports jq expressions, matches when the expression returns true. The expression is evaluated on each present header in the request, in HeaderKey: HeaderValue format.

Supports standard HTTP methods, and non-standard HTTP methods.

Case-insensitive. If the request method matches the filter, the request is stolen.

Supports regexes validated by the fancy-regex crate.

Case-insensitive. Tries to find match in the path (without query) and path+query. If any of the two matches, the request is stolen.

Activate the HTTP traffic filter only for these ports. When absent, filtering will be done for all ports.

Sets up the HTTP traffic filter (currently, only useful when incoming: steal).

See filter for details.

DEPRECATED: use tls_delivery instead.

Consider removing when adding https://github.com/metalbear-co/mirrord/issues/702

Ports to ignore when mirroring/stealing traffic. Useful if you want specific ports to be used locally only.

Mutually exclusive with ports.

Mapping for local ports to actually used local ports. When application listens on a port while steal/mirror is active we fallback to random ports to avoid port conflicts. Using this configuration will always use the specified port. If this configuration doesn't exist, mirrord will try to listen on the original port and if it fails it will assign a random port

This is useful when you want to access ports exposed by your service locally For example, if you have a service that listens on port 80 and you want to access it, you probably can't listen on 80 without sudo, so you can use [[80, 4480]] then access it on 4480 while getting traffic from remote 80. The value of port_mapping doesn't affect this.

Allows selecting between mirroring or stealing traffic.

See mode for details.

(Operator Only): if value of override will force close any other connections on requested target

Mapping for local ports to remote ports.

This is useful when you want to mirror/steal a port to a different port on the remote machine. For example, your local process listens on port 9333 and the container listens on port 80. You'd use [[9333, 80]]

List of ports to mirror/steal traffic from. Other ports will remain local.

Mutually exclusive with ignore_ports.

(Operator Only): configures how mirrord delivers stolen TLS traffic to the local application.

How much time to wait while we don't have any active connections before exiting.

Common cases would be running a chain of processes that skip using the layer and don't connect to the proxy.

{
  "internal_proxy": {
    "idle_timeout": 30
  }
}

Whether the proxy should output logs in JSON format. If false, logs are output in human-readable format.

Defaults to true.

Set the log destination for the internal proxy.

1. If the provided path ends with a separator (/ on UNIX, \ on Windows), it will be treated as a path to directory where the log file should be created.
2. Otherwise, if the path exists, mirrord will check if it's a directory or not.
3. Otherwise, it will be treated as a path to the log file.

mirrord will auto create all parent directories.

Defaults to a randomized path inside the temporary directory.

Set the log level for the internal proxy.

The value should follow the RUST_LOG convention (i.e mirrord=trace).

Defaults to mirrord=info,warn.

How often to log information about connected processes in seconds.

This feature logs details about processes that are currently connected to the internal proxy, including their PID, process name, command line, and connection status.

{
  "internal_proxy": {
    "process_logging_interval": 60
  }
}

Sometimes the cpu is too busy with other tasks and the internal proxy sockets end up timing out. It's set at a ridiculous high value to prevent this from happening when a user hits a breakpoint while debugging, and stays stopped for a while, which sometimes results in mirrord not working when they resume.

{
  "internal_proxy": {
    "socket_timeout": 31536000
  }
}

How much time to wait for the first connection to the proxy in seconds.

Common cases would be running with dlv or any other debugger, which sets a breakpoint on process execution, delaying the layer startup and connection to proxy.

{
  "internal_proxy": {
    "start_idle_timeout": 60
  }
}

Delay in milliseconds for outgoing receive operations (Agent → Layer).

Defaults to 0 (no delay).

Delay in milliseconds for outgoing send operations (Layer → Agent).

Defaults to 0 (no delay).

Path to a PEM file containing the certificate chain used by the local application's TLS server.

This file must contain at least one certificate. It can contain entries of other types, e.g private keys, which are ignored.

Server name to use when making a connection.

Must be a valid DNS name or an IP address.

Paths to PEM files and directories with PEM files containing allowed root certificates.

Directories are not traversed recursively.

Each certificate found in the files is treated as an allowed root. The files can contain entries of other types, e.g private keys, which are ignored.

The AWS CLI prefers local credentials (e.g. ~/.aws, AWS_PROFILE) over the remote pod's identity (IAM role, instance profile, IRSA). When those local credentials are present, the pod's own identity is never used, which is rarely what you want in a mirrord session.

When enabled, mirrord makes local AWS configuration unavailable to the process by:

• Unsetting AWS_PROFILE and related AWS environment variables.
• Mapping ~/.aws to a temporary directory, so the AWS CLI cannot read local credentials and also has a writable location for its credential cache (avoiding errors on cache writes).

This allows the remote pod's IAM role / instance profile to be used as intended.

Disable this only if you intentionally need local AWS credentials inside the local mirrord' process.

Defaults to true.

Different ways of connecting to the source database.

Accepts three formats:

Legacy URL (backward compatible):

{ "url": { "type": "env", "variable": "DB_CONNECTION_URL" } }

Flat URL:

{ "type": "env", "url": "DB_CONNECTION_URL" }

Individual connection params:

{ "type": "env", "params": { "host": "DB_HOST", "port": "DB_PORT", "user": "DB_USER", "password": "DB_PASSWORD", "database": "DB_NAME" } }

Individual connection params with password from a Kubernetes Secret:

{ "type": "env", "params": { "host": "DB_HOST", "password": { "secret": "my-secret", "key": "password" }, "database": "DB_NAME" } }

Users can choose from the following copy mode to bootstrap their MongoDB branch database:

• Empty

  Creates an empty database. If the source DB connection options are found from the chosen target, mirrord operator extracts the database name and create an empty DB. Otherwise, mirrord operator looks for the name field from the branch DB config object. This option is useful for users that run DB migrations themselves before starting the application.

• All

  Copies both schema and data of all collections. Supports optional collection filters to copy only specific collections or filter documents within collections.

The timeout in seconds to wait for a database branch to become ready after creation. Defaults to 60 seconds. Adjust this value based on your database size and cluster performance.

Users can choose to specify a unique id. This is useful for reusing or sharing the same database branch among Kubernetes users.

When source database connection detail is not accessible to mirrord operator, users can specify the database name so it is included in the connection options mirrord uses as the override.

Mirrord operator starts counting the TTL when a branch is no longer used by any session. The time-to-live (TTL) for the branch database is set to 300 seconds by default. Users can set ttl_secs to customize this value according to their need. Please note that longer TTL paired with frequent mirrord session turnover can result in increased resource usage. For this reason, branch database TTL caps out at 15 min.

Mirrord operator uses a default version of the database image unless version is given.

Different ways of connecting to the source database.

Accepts three formats:

Legacy URL (backward compatible):

{ "url": { "type": "env", "variable": "DB_CONNECTION_URL" } }

Flat URL:

{ "type": "env", "url": "DB_CONNECTION_URL" }

Individual connection params:

{ "type": "env", "params": { "host": "DB_HOST", "port": "DB_PORT", "user": "DB_USER", "password": "DB_PASSWORD", "database": "DB_NAME" } }

Individual connection params with password from a Kubernetes Secret:

{ "type": "env", "params": { "host": "DB_HOST", "password": { "secret": "my-secret", "key": "password" }, "database": "DB_NAME" } }

Users can choose from the following copy mode to bootstrap their MSSQL branch database:

• Empty

  Creates an empty database. If the source DB connection options are found from the chosen target, mirrord operator extracts the database name and create an empty DB. Otherwise, mirrord operator looks for the name field from the branch DB config object. This option is useful for users that run DB migrations themselves before starting the application.

• Schema

  Creates an empty database and copies schema of all tables.

• All

  Copies both schema and data of all tables. This option shall only be used when the data volume of the source database is minimal.

The timeout in seconds to wait for a database branch to become ready after creation. Defaults to 60 seconds. Adjust this value based on your database size and cluster performance.

Users can choose to specify a unique id. This is useful for reusing or sharing the same database branch among Kubernetes users.

When source database connection detail is not accessible to mirrord operator, users can specify the database name so it is included in the connection options mirrord uses as the override.

Mirrord operator starts counting the TTL when a branch is no longer used by any session. The time-to-live (TTL) for the branch database is set to 300 seconds by default. Users can set ttl_secs to customize this value according to their need. Please note that longer TTL paired with frequent mirrord session turnover can result in increased resource usage. For this reason, branch database TTL caps out at 15 min.

Mirrord operator uses a default version of the database image unless version is given.

Different ways of connecting to the source database.

Accepts three formats:

Legacy URL (backward compatible):

{ "url": { "type": "env", "variable": "DB_CONNECTION_URL" } }

Flat URL:

{ "type": "env", "url": "DB_CONNECTION_URL" }

Individual connection params:

{ "type": "env", "params": { "host": "DB_HOST", "port": "DB_PORT", "user": "DB_USER", "password": "DB_PASSWORD", "database": "DB_NAME" } }

Individual connection params with password from a Kubernetes Secret:

{ "type": "env", "params": { "host": "DB_HOST", "password": { "secret": "my-secret", "key": "password" }, "database": "DB_NAME" } }

Users can choose from the following copy mode to bootstrap their MySQL branch database:

• Empty

  Creates an empty database. If the source DB connection options are found from the chosen target, mirrord operator extracts the database name and create an empty DB. Otherwise, mirrord operator looks for the name field from the branch DB config object. This option is useful for users that run DB migrations themselves before starting the application.

• Schema

  Creates an empty database and copies schema of all tables.

• All

  Copies both schema and data of all tables. This option shall only be used when the data volume of the source database is minimal.

The timeout in seconds to wait for a database branch to become ready after creation. Defaults to 60 seconds. Adjust this value based on your database size and cluster performance.

Users can choose to specify a unique id. This is useful for reusing or sharing the same database branch among Kubernetes users.

When source database connection detail is not accessible to mirrord operator, users can specify the database name so it is included in the connection options mirrord uses as the override.

Mirrord operator starts counting the TTL when a branch is no longer used by any session. The time-to-live (TTL) for the branch database is set to 300 seconds by default. Users can set ttl_secs to customize this value according to their need. Please note that longer TTL paired with frequent mirrord session turnover can result in increased resource usage. For this reason, branch database TTL caps out at 15 min.

Mirrord operator uses a default version of the database image unless version is given.

Enable ipv6 support. Turn on if your application listens to incoming traffic over IPv6, or connects to other services over IPv6.

Filters that are used to send specific traffic from either the remote pod or the local app

Defaults to false.

Defaults to true.

Defaults to true.

Connect to these unix streams remotely (and to all other paths locally).

You can either specify a single value or an array of values. Each value is interpreted as a regular expression (Supported Syntax).

When your application connects to a unix socket, the target address will be converted to a string (non-utf8 bytes are replaced by a placeholder character) and matched against the set of regexes specified here. If there is a match, mirrord will connect your application with the target unix socket address on the target pod. Otherwise, it will leave the connection to happen locally on your machine.

Different ways of connecting to the source database.

Accepts three formats:

Legacy URL (backward compatible):

{ "url": { "type": "env", "variable": "DB_CONNECTION_URL" } }

Flat URL:

{ "type": "env", "url": "DB_CONNECTION_URL" }

Individual connection params:

{ "type": "env", "params": { "host": "DB_HOST", "port": "DB_PORT", "user": "DB_USER", "password": "DB_PASSWORD", "database": "DB_NAME" } }

Individual connection params with password from a Kubernetes Secret:

{ "type": "env", "params": { "host": "DB_HOST", "password": { "secret": "my-secret", "key": "password" }, "database": "DB_NAME" } }

Users can choose from the following copy mode to bootstrap their PostgreSQL branch database:

• Empty

  Creates an empty database. If the source DB connection options are found from the chosen target, mirrord operator extracts the database name and create an empty DB. Otherwise, mirrord operator looks for the name field from the branch DB config object. This option is useful for users that run DB migrations themselves before starting the application.

• Schema

  Creates an empty database and copies schema of all tables.

• All

  Copies both schema and data of all tables. This option shall only be used when the data volume of the source database is minimal.

The timeout in seconds to wait for a database branch to become ready after creation. Defaults to 60 seconds. Adjust this value based on your database size and cluster performance.

IAM authentication for the source database. Use this when your source database (AWS RDS, GCP Cloud SQL) requires IAM authentication instead of password-based authentication.

Users can choose to specify a unique id. This is useful for reusing or sharing the same database branch among Kubernetes users.

When source database connection detail is not accessible to mirrord operator, users can specify the database name so it is included in the connection options mirrord uses as the override.

Mirrord operator starts counting the TTL when a branch is no longer used by any session. The time-to-live (TTL) for the branch database is set to 300 seconds by default. Users can set ttl_secs to customize this value according to their need. Please note that longer TTL paired with frequent mirrord session turnover can result in increased resource usage. For this reason, branch database TTL caps out at 15 min.

Mirrord operator uses a default version of the database image unless version is given.

Pod to mirror.

How long (in seconds) the CLI waits for the preview session to become ready. If the session hasn't reached Ready within this time, the CLI deletes it.

Container image to run in the preview pod. The image must be pre-built and pushed to a registry accessible by the cluster.

How long (in minutes) the preview session is allowed to live after creation. The operator will terminate the session when this time elapses.

Set to "infinite" to disable TTL.

Supports either a complete URL or separated connection parameters. If both are provided, url takes precedence.

The following fields can be sourced via remote environment variable:

• url
• host
• password
• username

Example:

"connection": {
    "host": { "type": "env", "variable": "REDIS_HOST" },
    "port": 6379,
    "password": { "type": "env", "variable": "REDIS_PASSWORD" }
}

Optional unique identifier for reusing branches across sessions.

Configuration for local Redis runtime.

Redis database number (default: 0).

Redis host/hostname. Can be sourced from an environment variable.

Redis password for authentication. Can be sourced from an environment variable.

Redis port (default: 6379).

Enable TLS/SSL connection.

Complete Redis URL (e.g., redis://user:pass@host:6379/0). Can be sourced from an environment variable.

Redis username (Redis 6+ ACL). Can be sourced from an environment variable.

Type marker for environment variable sources.

Custom path to the container command. If not provided, uses the runtime name from PATH (e.g., "docker"). Example: /usr/local/bin/docker or /home/user/.local/bin/podman

Container runtimes supported by mirrord.

Example:

{
  "args": ["--maxmemory", "256mb", "--appendonly", "yes"]
}

Local port to bind Redis to (default: 6379).

For container-based runtimes, mirrord spawns the Redis image in a container. For redis_server, it runs the native binary directly.

Backends:

• container (default) - Uses a container runtime (Docker/Podman/nerdctl), configured via container_runtime.
• redis_server - Uses native redis-server binary
• auto - Tries container first, falls back to redis-server

Custom path to the redis-server binary. If not provided, uses "redis-server" from PATH. Example: /opt/redis/bin/redis-server

Redis version/tag to use (default: "7-alpine"). Used as the container image tag.

Raw arguments passed directly to redis-server or as Docker CMD args. Use standard Redis config syntax (e.g., "--maxmemory 256mb").

Rollout to mirror.

Sets the max interval (in milliseconds) of retries for Kubernetes API requests made by mirrord during startup (e.g. for resolving the target or connecting to the mirrord Operator).

Defaults to 5000 milliseconds.

Sets the max amount of retries for Kubernetes API requests made by mirrord during startup (e.g. for resolving the target or connecting to the mirrord Operator).

If you want to disable request retries, set this value to 0.

Defaults to 2.

Sets the min interval (in milliseconds) of retries for Kubernetes API requests made by mirrord during startup (e.g. for resolving the target or connecting to the mirrord Operator).

Defaults to 500 milliseconds.

Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container.

Request is the name chosen for a request in the referenced claim. If empty, everything from the claim is made available, otherwise only the result of this request.

Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container.

This is an alpha field and requires enabling the DynamicResourceAllocation feature gate.

This field is immutable. It can only be set for containers.

Limits describes the maximum amount of compute resources allowed. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.

Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys.

Operator represents a key's relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category.

TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system.

Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string.