mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-18 05:39:50 +08:00
grs
8369bc11a5
* fix(podman): restore host gateway alias mediation Signed-off-by: Gordon Sim <gsim@redhat.com> * fix(podman-e2e-tests): enable broader test podman e2e coverage Signed-off-by: Gordon Sim <gsim@redhat.com> * fix(tests): make test more reliable Signed-off-by: Gordon Sim <gsim@redhat.com> * fix(podman): fix macos linting error Signed-off-by: Gordon Sim <gsim@redhat.com> --------- Signed-off-by: Gordon Sim <gsim@redhat.com>
67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
# Podman Networking
|
|
|
|
Only the external supervisor has external network connectivity. The workload
|
|
container uses `network=none`; its loopback DNS relay and TCP socket mediation
|
|
reach the supervisor through a protected Unix socket, not a veth or proxy
|
|
environment variable.
|
|
|
|
```text
|
|
workload container supervisor container
|
|
agent -> sandbox -- private UDS / gRPC -> policy proxy -> host network -> destination
|
|
|
|
|
+-- authenticated gateway session
|
|
```
|
|
|
|
## Outer network fence
|
|
|
|
The driver creates the workload without networks, host aliases, published
|
|
ports, or added capabilities. It checks the Podman inspect response before
|
|
launch and restart. The sandbox installs seccomp mediation and Landlock before
|
|
executing the agent. It does not create network namespaces, configure nftables,
|
|
or require `CAP_NET_ADMIN`.
|
|
|
|
TCP opens, TCP byte streams, DNS requests/replies, and lifecycle operations
|
|
share the authenticated gRPC channel. DNS is resolved and authorized by the
|
|
supervisor. General UDP is unsupported.
|
|
|
|
The driver mounts a read-only, driver-owned `/etc/resolv.conf` into the
|
|
workload with `nameserver 127.0.0.53`. This prevents the disconnected Podman
|
|
network namespace from replacing the policy-DNS relay with a runtime resolver.
|
|
The supervisor answers `host.openshell.internal` with a trusted concrete
|
|
destination: `127.0.0.1` on native Linux, the configured Podman Machine host
|
|
address on macOS. That destination is part of the supervisor bootstrap and is
|
|
reapplied when a sandbox restarts.
|
|
|
|
## Supervisor network
|
|
|
|
The supervisor companion uses Podman's host network. On Linux it connects to
|
|
the gateway's primary loopback endpoint. On macOS, Podman Machine provides the
|
|
host-loopback route. The upstream corporate proxy applies only to the
|
|
supervisor. The gateway's SSH tunnel uses the supervisor relay over its private
|
|
Unix socket, so the driver does not publish a supervisor port.
|
|
|
|
These runtime-managed network helpers are outside the workload trust boundary.
|
|
Sharing the workload's user namespace preserves volume UID/GID mapping; it
|
|
does not share the workload's PID, mount, or network namespaces.
|
|
|
|
## Troubleshooting
|
|
|
|
Inspect both containers with the same sandbox-ID label, distinguishing
|
|
`openshell.ai/isolation-role=sandbox` from
|
|
`openshell.ai/isolation-role=supervisor`.
|
|
|
|
- Sandbox fails its qualification probe: use its log to identify the denied
|
|
kernel/runtime primitive. Do not add capabilities or disable runtime seccomp.
|
|
- Sandbox cannot authenticate to supervisor: check the private channel volume,
|
|
matching user namespace mappings, and shared SELinux label.
|
|
- Supervisor cannot connect: inspect its configured gateway endpoint,
|
|
credentials, host network, and the gateway's primary listener.
|
|
- DNS or egress denied: inspect supervisor policy decisions. Do not add a
|
|
workload network, resolver bypass, or direct gateway route.
|
|
- Pair is not Ready: check the supervisor health socket and gateway session.
|
|
A running workload container alone does not establish readiness.
|
|
|
|
See the [driver overview](README.md) and
|
|
[Podman runtime documentation](https://docs.podman.io/en/latest/markdown/podman-run.1.html)
|
|
for runtime options.
|