Skip to content

Commit 92581d3

Browse files
committed
docs(egress): document config.yaml override paths (downstream image, ConfigMap mount)
The previous draft told operators to edit components/egress/mitmproxy/config.yaml and rebuild — true for the in-repo flow, but does not help operators consuming a published egress image who want different static defaults. Add a section spelling out the three supported override paths: 1. Build a downstream image that COPYs an alternate config.yaml over the baked-in path (recommended: version-controlled, reproducible). 2. Mount an override at /var/lib/mitmproxy/.mitmproxy/config.yaml at runtime (Kubernetes ConfigMap subPath mount example included). 3. Use the env-driven --set escape hatch for the small set of options exposed via environment variables. Also warn against in-container edits, which are lost on restart and blocked by the mitmproxy user's read-only access.
1 parent af8c28e commit 92581d3

1 file changed

Lines changed: 35 additions & 1 deletion

File tree

components/egress/docs/mitmproxy-transparent.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,41 @@ This is the single source of truth for:
7272

7373
Precedence: command-line `--set` (from env overrides) > `config.yaml` > mitmproxy built-in defaults.
7474

75-
To change a static option for the whole fleet: edit `config.yaml`, rebuild the egress image, redeploy. To bypass decryption for a specific host **temporarily** in one deployment, the option is to edit and remount `config.yaml` rather than pass an env override.
75+
#### Overriding the built-in config.yaml
76+
77+
There is no env var to point mitm at an alternate config file. Operators who need different static defaults (e.g. a different `ignore_hosts` list, `connection_strategy`, or `stream_large_bodies`) should pick one of the following:
78+
79+
1. **Build a downstream image** that derives from the official egress image and replaces the file:
80+
81+
```dockerfile
82+
FROM <opensandbox-egress-image>:<tag>
83+
COPY my-config.yaml /var/lib/mitmproxy/.mitmproxy/config.yaml
84+
RUN chown mitmproxy:mitmproxy /var/lib/mitmproxy/.mitmproxy/config.yaml \
85+
&& chmod 0644 /var/lib/mitmproxy/.mitmproxy/config.yaml
86+
```
87+
88+
This is the recommended path because the override is version-controlled, reviewable, and reproducible.
89+
90+
2. **Mount an override file at runtime** over the baked-in path. For Kubernetes, mount a `ConfigMap` as a file at `/var/lib/mitmproxy/.mitmproxy/config.yaml` (be aware that a `ConfigMap` file mount typically lands as read-only with the original UID, so verify the mitmproxy user can read it):
91+
92+
```yaml
93+
volumeMounts:
94+
- name: mitm-config
95+
mountPath: /var/lib/mitmproxy/.mitmproxy/config.yaml
96+
subPath: config.yaml
97+
readOnly: true
98+
volumes:
99+
- name: mitm-config
100+
configMap:
101+
name: egress-mitm-config
102+
defaultMode: 0644
103+
```
104+
105+
Useful for staged rollouts or per-environment overrides without rebuilding the image.
106+
107+
3. **Single-option escape hatch via env-driven `--set`** (already supported for the documented env variables above). This only works for options exposed via env and only for the single specific override; it cannot replace the whole file.
108+
109+
Do not edit `config.yaml` inside a running container — the file lives in the container layer, edits are lost on restart, and the mitmproxy user has read-only access by design.
76110

77111
## Common Configuration Templates
78112

0 commit comments

Comments
 (0)