mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-31 07:44:57 +08:00
Evan Lezar
5c98604f0f
* feat(gpu): honor device IDs in Docker and Podman Signed-off-by: Evan Lezar <elezar@nvidia.com> * test(gpu): add Docker and Podman device selection e2e Signed-off-by: Evan Lezar <elezar@nvidia.com> * ci(gpu): run Docker GPU e2e workflow Signed-off-by: Evan Lezar <elezar@nvidia.com> --------- Signed-off-by: Evan Lezar <elezar@nvidia.com>
81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# openshell-driver-docker
|
|
|
|
Docker-backed compute driver for local OpenShell gateways.
|
|
|
|
The driver manages sandbox containers through the local Docker daemon with the
|
|
`bollard` client. It is intended for developer environments where Docker is
|
|
already available and running Kubernetes would be unnecessary.
|
|
|
|
## Runtime Model
|
|
|
|
The gateway runs as a host process. The Docker driver creates one container per
|
|
sandbox and starts the `openshell-sandbox` supervisor inside that container. The
|
|
supervisor then creates the nested sandbox namespace for the agent process.
|
|
|
|
Docker containers currently use host networking. This lets a supervisor reach a
|
|
gateway bound to `127.0.0.1` without requiring a separate bridge listener, NAT
|
|
rule, or userland proxy. The container also receives
|
|
`host.openshell.internal -> 127.0.0.1` so local host services have a stable
|
|
OpenShell-owned name.
|
|
|
|
## Container Contract
|
|
|
|
The driver-controlled container settings are part of the sandbox security
|
|
contract:
|
|
|
|
| Setting | Purpose |
|
|
|---|---|
|
|
| `user = "0"` | The supervisor needs root inside the container to prepare namespaces, mounts, Landlock, and seccomp. |
|
|
| `network_mode = "host"` | Lets the supervisor call back to loopback gateway endpoints. |
|
|
| `cap_add` | Grants supervisor-only capabilities required for namespace setup and process inspection. |
|
|
| `apparmor=unconfined` | Avoids Docker's default profile blocking required mount operations. |
|
|
| `restart_policy = unless-stopped` | Keeps managed sandboxes resumable across daemon or gateway restarts. |
|
|
| CDI GPU request | Uses the sandbox `gpu_device` value when set; otherwise requests all NVIDIA GPUs when the sandbox spec asks for GPU support and daemon CDI support is detected. |
|
|
|
|
The agent child process does not retain these supervisor privileges.
|
|
|
|
## Supervisor Binary Resolution
|
|
|
|
The Docker driver bind-mounts a host-side Linux `openshell-sandbox` binary into
|
|
each sandbox container. Resolution order is:
|
|
|
|
1. `--docker-supervisor-bin` / `OPENSHELL_DOCKER_SUPERVISOR_BIN`.
|
|
2. A sibling `openshell-sandbox` next to the running `openshell-gateway` binary.
|
|
3. A local Linux cargo target build for the Docker daemon architecture.
|
|
4. `--docker-supervisor-image` / `OPENSHELL_DOCKER_SUPERVISOR_IMAGE`, or the
|
|
release-matched default supervisor image, extracting `/openshell-sandbox`.
|
|
|
|
Release and Docker-image gateway builds bake the matching supervisor image tag
|
|
into the binary at compile time. The default Docker supervisor image is not
|
|
`:latest` unless a custom build explicitly sets that tag.
|
|
|
|
## Callback and TLS
|
|
|
|
`OPENSHELL_ENDPOINT` is injected from the gateway's configured gRPC endpoint
|
|
without rewriting. Because the container uses host networking, loopback
|
|
endpoints such as `http://127.0.0.1:8080` resolve to the host gateway.
|
|
|
|
For HTTPS endpoints, the server certificate must include the endpoint host as a
|
|
subject alternative name. Docker sandboxes also need the client TLS bundle
|
|
mounted into the container and exposed with:
|
|
|
|
- `OPENSHELL_TLS_CA`
|
|
- `OPENSHELL_TLS_CERT`
|
|
- `OPENSHELL_TLS_KEY`
|
|
|
|
HTTP endpoints reject TLS material because the supervisor would not use it.
|
|
|
|
## Environment Ownership
|
|
|
|
The driver merges template environment and sandbox spec environment first, then
|
|
overwrites security-critical keys:
|
|
|
|
- `OPENSHELL_ENDPOINT`
|
|
- `OPENSHELL_SANDBOX_ID`
|
|
- `OPENSHELL_SANDBOX`
|
|
- `OPENSHELL_SSH_SOCKET_PATH`
|
|
- `OPENSHELL_SANDBOX_COMMAND`
|
|
- TLS path variables when HTTPS is enabled
|
|
|
|
Do not allow sandbox images or templates to override these values.
|