Boundary vs. Internal Pods¶

Note

For an introduction to pod types, see Pod Types & Composability. This page covers the technical specifics of how boundary and internal pod classification affects PINHOLE configuration and access patterns.

Summary¶

Aspect	Boundary Pods	Internal Pods
Pod types	Gateway (`http-gateway`, `grpc-gateway`), Sink (`http-sink`, `grpc-sink`)	Relay, Distributor, Aggregator, Terminator
`PINHOLE_ENABLED` default	`true`	`false`
External endpoints	`POST /trigger` (Gateway), `GET /output` (Sink)	None
Port 8000	Exposed via NodePort / LoadBalancer	Internal only
Can be triggered externally	Yes (Gateway only)	No

What PINHOLE_ENABLED does¶

When PINHOLE_ENABLED=true, the WoSP sidecar opens a Pinhole — a small, authenticated gap in the Zero Trust perimeter that allows specific external HTTP calls:

Gateway pods: POST /trigger on port 8000 accepts external trigger calls (from clients, the auto-trigger, or curl)
Sink pods: GET /output on port 8000 returns the accumulated delivery results

When PINHOLE_ENABLED=false, the pod has no externally accessible endpoints. All communication is WoSP-to-WoSP and cannot be initiated from outside the network.

Pinhole TLS setup¶

For production deployments where the Gateway or Sink needs TLS termination, run pinhole-setup.sh included in the blueprint bundle:

bash pinhole-setup.sh

This script generates a self-signed certificate (or accepts your own cert) and configures TLS on the Pinhole endpoint. Required when clients sending POST /trigger expect HTTPS.

When to run pinhole-setup.sh

For local k3d development, TLS is not required — curl http://localhost:8000/output works without it. For cloud deployments where external clients call the gateway, run pinhole-setup.sh and update your service to use port 443.

Internal pods cannot be triggered externally¶

Even if you manually set PINHOLE_ENABLED=true on an internal pod (Relay, Distributor, Aggregator, Terminator), it will not expose a /trigger endpoint. Internal pod templates do not include the Pinhole trigger route in their app.py. The setting is ignored for internal pod types.

This is a security property, not a limitation. Internal pods exist only within the WoSP network and are unreachable from outside by design.