Skip to content

refactor: make sandbox callback listeners gateway-owned #1952

@elezar

Description

@elezar

Problem Statement

Docker can currently add gateway listener addresses from inside the in-process driver via gateway_bind_addresses(). Other drivers do not have that mechanism; they rely on gateway, operator, or deployment configuration to make the sandbox callback endpoint reachable.

This creates inconsistent ownership of gateway network exposure and does not extend cleanly to arbitrary remote compute drivers. A remote driver can inject a callback endpoint into its workloads, but it should not be expected to mutate gateway listeners over the compute-driver protocol.

The current model also weakens the local Podman posture. RPM defaults to bind_address = "0.0.0.0:17670" so sandbox containers can reach the gateway, even though a narrower listener on a Podman or Docker host-gateway interface would often be preferable.

Proposed Design

Expose gateway-owned extra listeners in gateway TOML, using the existing runtime concept already represented by Config.extra_bind_addresses:

[openshell.gateway]
bind_address = "127.0.0.1:17670"
extra_bind_addresses = ["172.18.0.1:17670"]

These listeners should serve the same multiplexed gateway surface as bind_address.

Drivers should not decide what interfaces the gateway exposes. Drivers should only inject callback endpoint configuration into workloads. The operator or deployment owns making the callback endpoint route to one of the configured gateway listeners.

For example, a narrower Podman or Docker setup could use:

[openshell.gateway]
bind_address = "127.0.0.1:17670"
extra_bind_addresses = ["172.18.0.1:17670"]

[openshell.drivers.podman]
grpc_endpoint = "https://host.openshell.internal:17670"
host_gateway_ip = "172.18.0.1"

Compatibility Plan

Phase this change to avoid surprising existing Linux Docker users:

  1. Add and document [openshell.gateway].extra_bind_addresses.
  2. Update Docker and Podman docs with narrow callback-listener examples that avoid broad 0.0.0.0 binding when a host-gateway IP is known.
  3. Keep Docker-derived gateway_bind_addresses() temporarily for compatibility.
  4. In a follow-up, decide whether Docker-derived listener mutation should be retained, warned, deprecated, or removed once explicit gateway config is established.

Remote Driver Contract

Remote drivers should not request gateway listener addresses through compute_driver.proto. The expected ownership model should be:

  • Gateway owns listener addresses.
  • Driver owns workload callback endpoint injection.
  • Operator or deployment owns network reachability between the two.

If a future protocol capability is added, it should be explicit, startup-only, and allowlisted because binding unexpected gateway interfaces has security, certificate, and HA implications.

Definition of Done

  • Add TOML schema support for [openshell.gateway].extra_bind_addresses.
  • Preserve duplicate handling and listener merging with the primary bind_address.
  • Add config parsing tests for extra listener addresses.
  • Add server tests for listener address merging where appropriate.
  • Document Docker and Podman examples that avoid broad 0.0.0.0 binding.
  • Document that arbitrary remote drivers cannot request gateway listeners over the compute-driver protocol.
  • Decide the compatibility path for Docker auto-derived listener addresses.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions