Module container_relay 

In-container ingest relay (ADR-100 section 4).

A cog always posts its vectors to 127.0.0.1:80/api/v1/store/ingest (the address is compiled into the released binaries). Inside a container, or an Apple container VM, that loopback is the container’s own, so nothing answers unless something listens there. When the host contract names an ingest upstream (the node’s ingest bridge as the container sees it, e.g. the VM gateway), the adapter builds the image with a small relay as the entrypoint:

1. the relay binds 127.0.0.1:80 while still root (the only reason the container starts as root, with every capability dropped except NET_BIND_SERVICE, SETUID and SETGID);
2. it forks the cog, which drops to nobody and sets no_new_privs before exec, so the cog runs with no capabilities and cannot regain any through a setuid binary (Apple container has no --security-opt no-new-privileges, so the relay sets it itself);
3. it drops to nobody (and no_new_privs) itself and forwards each connection, byte for byte, to the upstream (bounded connections, bytes and time);
4. it forwards SIGTERM / SIGINT to the cog and exits with the cog’s status.

The relay is a Python script, so a relay image needs python3 in the operator-pinned base; the build checks for it and fails loudly.

Constants

COG_INGEST_ADDR

The fixed address every cog posts its ingest to.

RELAY_CAPS

Capabilities a relay container keeps (all others are dropped).

RELAY_FILE

Build-context file name of the relay script.

RELAY_PATH

Where the relay script lives in the image.

RELAY_SCRIPT

The relay script (see the module docs).

Functions

dockerfile

Dockerfile for a cog image fronted by the ingest relay.

relay_upstream

The upstream the relay forwards to, if the image needs a relay.