Configuration

.outprobe.yaml is the default source for deployment settings and the only source for request identity, mode, feed, ingress, and egress configuration.

Run outprobe init to create a documented starter file with a hosted JSON Schema reference.

Resolution and precedence

Deployment settings resolve in this order:

flag or environment variable  →  .outprobe.yaml  →  built-in default

For example:

outprobe up --target temporary-service
NS=temporary-namespace outprobe up

These override target or namespace without changing the file.

Identity and routing policy are config-only: rules, mode, feed, ingress, and egress do not have flag or environment equivalents.

Complete example

# yaml-language-server: $schema=https://outprobe.dev/schemas/outprobe.schema.json
version: "0.0.1"

# Deployment
namespace: my-namespace
target: my-service
targetPort: 8080
image: ghcr.io/flaticols/outprobe-relay:v0.0.16
localTarget: http://localhost:8080
context: my-kube-context

# Traffic mode
mode: divert

# Optional caller-side divert pre-filter. Entries are OR'd.
feed:
  - path: /api/v2/
  - header: x-debug-user
  - header: x-environment
    value: dev

# Optional browser/gateway routes.
ingress:
  gateway: istio-ingressgateway-api
  gatewayNamespace: gateway-system
  header: x-outprobe
  headerValue: "1"
  routes:
    - name: my-service
      hostnames: [api.internal.example.com]
      path: /my-service
    - cloneFrom: my-service-admin-route

# Optional TCP access from the local app to cluster dependencies.
egress:
  allow:
    - .svc.cluster.local
  services:
    - name: pricing
      to: pricing.my-namespace.svc.cluster.local:8080
    - name: postgres
      to: pg.my-namespace.svc.cluster.local:5432
      listen: 127.0.0.1:15432

# Which requests belong to this laptop.
rules:
  - type: jwt
    property: https://your-org.example.com/
    matchers:
      - key: email
        value: you@example.com

Only target and a non-empty active matcher value are operationally required by up; namespace, ports, image, local target, mode, and context have fallback behavior.

Deployment fields

Field	Flag	Environment	Default	Meaning
`namespace`	`-n`, `--namespace`	`NS`	`default`	Target Service and relay namespace.
`context`	`-c`, `--context`	`KCONTEXT`	Current kubectl context	Cluster context.
`target`	`--target`	`TARGET`	none	Kubernetes Service to intercept.
`targetPort`	`--target-port`	`TARGET_PORT`	`8080`	Real target Service port.
`image`	`--image`	`RELAY_IMAGE`	Published relay image	Image used by the relay Deployment.
`localTarget`	`--local-target`	`LOCAL_TARGET`	`http://localhost:8080`	Local HTTP origin receiving matches.

The config file path itself is --config / OUTPROBE_CONFIG and defaults to .outprobe.yaml.

`mode`

Accepted values:

divert — caller-side serving mode; the default;
mirror — caller-side observe-only mirror;
inbound-divert — target-side serving mode for JWT/header rules;
inbound-mirror — target-side observe-only mirror for all callers.

See Traffic modes for routing diagrams and trade-offs.

`rules`

rules:
  - type: jwt
    property: ""
    matchers:
      - key: email
        value: you@example.com

Field	Meaning
`type`	`jwt` or `header`. Empty defaults to JWT internally.
`property`	JWT claim namespace; empty means a top-level claim. Unused for headers.
`matchers[].key`	JWT claim name or HTTP header name.
`matchers[].value`	Exact identity value assigned to this client. Must be non-empty.

Current v1 activates the first rule with a matcher and uses that rule’s first matcher. See Request matching.

`feed`

feed:
  - path: /api/v2/
  - header: x-debug-user
  - header: x-environment
    value: dev

Field	Meaning
`path`	URI prefix sent to the relay.
`header`	Header presence match, unless `value` is also set.
`value`	Exact header value.

Entries are OR’d and used only in divert. Empty or omitted means all caller-side traffic reaches the relay. See Request matching.

`ingress`

ingress:
  gateway: my-gateway
  gatewayNamespace: gateway-system
  header: x-outprobe
  headerValue: "1"
  routes:
    - name: my-route
      hostnames: [api.example.com]
      path: /my-service
    - cloneFrom: existing-route

Field	Meaning
`gateway`	Parent Gateway name for a from-scratch route.
`gatewayNamespace`	Parent Gateway namespace.
`header`	Candidate traffic gate. Defaults to `x-outprobe`.
`headerValue`	Exact value. With default header, defaults to `"1"`; with a custom header, empty means presence.
`routes[].name`	Managed object suffix. Defaults to `cloneFrom` or an index.
`routes[].hostnames`	Hostnames for a from-scratch route.
`routes[].path`	From-scratch `PathPrefix`, rewritten to `/`.
`routes[].cloneFrom`	Existing same-namespace HTTPRoute to clone.

A route must set either path or cloneFrom. Mirror-mode ingress requires cloneFrom. Read the ingress guide before enabling a broad presence gate.

`egress`

egress:
  allow: [.svc.cluster.local]
  services:
    - name: pricing
      to: pricing.my-namespace.svc.cluster.local:8080
      listen: 127.0.0.1:18080

Field	Meaning
`allow`	Relay dial-target host suffixes. Empty means any host.
`services[].name`	Log label; defaults to the host in `to`.
`services[].to`	Required cluster-side `host:port`.
`services[].listen`	Local bind address; defaults to `127.0.0.1:<to port>`.

Egress is raw TCP. See Reach cluster dependencies for identity and mTLS implications.

JSON Schema

The generated file points to:

https://outprobe.dev/schemas/outprobe.schema.json

Editors using the YAML language server can validate and autocomplete without a local schema. The hosted schema mirrors internal/deploy/outprobe.schema.json in the source repository.

Editable manifests

By default, manifests are embedded in the CLI binary. Scaffold editable copies with:

outprobe init --manifests

Directory.outprobe/
- relay.yaml
- virtualservice.yaml
- virtualservice-mirror.yaml
- virtualservice-filtered.yaml
- httproute.yaml
- envoyfilter.yaml
- envoyfilter-divert.yaml

outprobe up prefers a matching file in .outprobe/ over the embedded version. Use this to change resource requests, annotations, relay replicas, or low-level routing templates without rebuilding the CLI.

Templates contain placeholders such as ${NS}, ${RELAY_IMAGE}, ${TARGET}, and ${TARGET_PORT} that are substituted at runtime.