From d0d0e5e9fa85b751f2979ebd953f0743566e973b Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Wed, 11 Mar 2026 12:49:51 -0700 Subject: [PATCH] update docs per new dev prs --- architecture/build-containers.md | 2 +- architecture/gateway-security.md | 28 +++++++++++------------ architecture/sandbox-custom-containers.md | 4 ++-- docs/reference/cli.md | 6 +++-- docs/reference/support-matrix.md | 2 +- docs/sandboxes/create-and-manage.md | 6 +++++ 6 files changed, 28 insertions(+), 20 deletions(-) diff --git a/architecture/build-containers.md b/architecture/build-containers.md index f68e1ec57..bcd97c80c 100644 --- a/architecture/build-containers.md +++ b/architecture/build-containers.md @@ -268,7 +268,7 @@ The chart deploys a **StatefulSet** (not a Deployment) with a `volumeClaimTempla The StatefulSet always mounts TLS secrets as volumes and sets environment variables for the server to use `rustls` with mTLS: -- **Volumes**: `tls-cert` (from `navigator-server-tls` secret, mounted at `/etc/navigator-tls/server/`) and `tls-client-ca` (from `navigator-server-client-ca` secret, mounted at `/etc/navigator-tls/client-ca/`). +- **Volumes**: `tls-cert` (from `navigator-server-tls` secret, mounted at `/etc/openshell-tls/server/`) and `tls-client-ca` (from `navigator-server-client-ca` secret, mounted at `/etc/openshell-tls/client-ca/`). - **Environment**: `OPENSHELL_TLS_CERT`, `OPENSHELL_TLS_KEY`, `OPENSHELL_TLS_CLIENT_CA` pointing to the mounted files. - **Client TLS secret name**: `OPENSHELL_CLIENT_TLS_SECRET_NAME` set to the `clientTlsSecretName` value, used by the server to inject TLS volume mounts into sandbox pod specs. - **gRPC endpoint**: `https://navigator.navigator.svc.cluster.local:8080` so sandbox pods connect over mTLS. diff --git a/architecture/gateway-security.md b/architecture/gateway-security.md index b365579dc..3f6ec428a 100644 --- a/architecture/gateway-security.md +++ b/architecture/gateway-security.md @@ -85,19 +85,19 @@ Secret names are defined as constants in `crates/navigator-bootstrap/src/constan ### Gateway Mounts -The Helm StatefulSet (`deploy/helm/navigator/templates/statefulset.yaml`) mounts: +The Helm StatefulSet (`deploy/helm/openshell/templates/statefulset.yaml`) mounts: | Volume | Mount Path | Source Secret | |---|---|---| -| `tls-cert` | `/etc/navigator-tls/server/` (read-only) | `navigator-server-tls` | -| `tls-client-ca` | `/etc/navigator-tls/client-ca/` (read-only) | `navigator-server-client-ca` | +| `tls-cert` | `/etc/openshell-tls/server/` (read-only) | `navigator-server-tls` | +| `tls-client-ca` | `/etc/openshell-tls/client-ca/` (read-only) | `navigator-server-client-ca` | Environment variables point the gateway binary to these paths: ``` -OPENSHELL_TLS_CERT=/etc/navigator-tls/server/tls.crt -OPENSHELL_TLS_KEY=/etc/navigator-tls/server/tls.key -OPENSHELL_TLS_CLIENT_CA=/etc/navigator-tls/client-ca/ca.crt +OPENSHELL_TLS_CERT=/etc/openshell-tls/server/tls.crt +OPENSHELL_TLS_KEY=/etc/openshell-tls/server/tls.key +OPENSHELL_TLS_CLIENT_CA=/etc/openshell-tls/client-ca/ca.crt ``` ### Sandbox Pod Mounts @@ -105,13 +105,13 @@ OPENSHELL_TLS_CLIENT_CA=/etc/navigator-tls/client-ca/ca.crt When the gateway creates a sandbox pod (`crates/navigator-server/src/sandbox/mod.rs:681`), it injects: - A volume backed by the `navigator-client-tls` secret. -- A read-only mount at `/etc/navigator-tls/client/` on the agent container. +- A read-only mount at `/etc/openshell-tls/client/` on the agent container. - Environment variables for the sandbox gRPC client: ``` -OPENSHELL_TLS_CA=/etc/navigator-tls/client/ca.crt -OPENSHELL_TLS_CERT=/etc/navigator-tls/client/tls.crt -OPENSHELL_TLS_KEY=/etc/navigator-tls/client/tls.key +OPENSHELL_TLS_CA=/etc/openshell-tls/client/ca.crt +OPENSHELL_TLS_CERT=/etc/openshell-tls/client/tls.crt +OPENSHELL_TLS_KEY=/etc/openshell-tls/client/tls.key OPENSHELL_ENDPOINT=https://navigator.navigator.svc.cluster.local:8080 ``` @@ -120,7 +120,7 @@ OPENSHELL_ENDPOINT=https://navigator.navigator.svc.cluster.local:8080 The CLI's copy of the client certificate bundle is written to: ``` -$XDG_CONFIG_HOME/openshell/clusters//mtls/ +$XDG_CONFIG_HOME/openshell/gateways//mtls/ ├── ca.crt ├── tls.crt └── tls.key @@ -221,9 +221,9 @@ Sandbox pods connect back to the gateway at startup to fetch their policy and pr | Env Var | Value | |---|---| -| `OPENSHELL_TLS_CA` | `/etc/navigator-tls/client/ca.crt` | -| `OPENSHELL_TLS_CERT` | `/etc/navigator-tls/client/tls.crt` | -| `OPENSHELL_TLS_KEY` | `/etc/navigator-tls/client/tls.key` | +| `OPENSHELL_TLS_CA` | `/etc/openshell-tls/client/ca.crt` | +| `OPENSHELL_TLS_CERT` | `/etc/openshell-tls/client/tls.crt` | +| `OPENSHELL_TLS_KEY` | `/etc/openshell-tls/client/tls.key` | These are used to build a `tonic::transport::ClientTlsConfig` with: - `ca_certificate()` -- verifies the server's certificate against the cluster CA. diff --git a/architecture/sandbox-custom-containers.md b/architecture/sandbox-custom-containers.md index 24d0f43d2..c1de88367 100644 --- a/architecture/sandbox-custom-containers.md +++ b/architecture/sandbox-custom-containers.md @@ -8,7 +8,7 @@ The `--from` flag accepts four kinds of input: | Input | Example | Behavior | |-------|---------|----------| -| **Community sandbox name** | `--from openclaw` | Resolves to `d1i0nduu2f6qxk.cloudfront.net/openshell-community/sandboxes/openclaw:latest` | +| **Community sandbox name** | `--from openclaw` | Resolves to `ghcr.io/nvidia/openshell-community/sandboxes/openclaw:latest` | | **Dockerfile path** | `--from ./Dockerfile` | Builds the image, pushes it into the cluster, then creates the sandbox | | **Directory with Dockerfile** | `--from ./my-sandbox/` | Uses the directory as the build context | | **Full image reference** | `--from myregistry.com/img:tag` | Uses the image directly | @@ -22,7 +22,7 @@ The CLI classifies the value in this order: 3. **Contains `/`, `:`, or `.`** — treated as a full container image reference. 4. **Otherwise** — treated as a community sandbox name, expanded to `{OPENSHELL_COMMUNITY_REGISTRY}/{name}:latest`. -The community registry prefix defaults to `d1i0nduu2f6qxk.cloudfront.net/openshell-community/sandboxes` and can be overridden with the `OPENSHELL_COMMUNITY_REGISTRY` environment variable. +The community registry prefix defaults to `ghcr.io/nvidia/openshell-community/sandboxes` and can be overridden with the `OPENSHELL_COMMUNITY_REGISTRY` environment variable. ### Dockerfile build flow diff --git a/docs/reference/cli.md b/docs/reference/cli.md index a836d9f68..568a1fcad 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -53,7 +53,7 @@ openshell │ ├── create │ ├── get [name] │ ├── list -│ ├── delete +│ ├── delete [--all] │ ├── connect [name] │ ├── upload [name] │ ├── download [name] @@ -115,7 +115,7 @@ Create and manage isolated agent execution environments. | `openshell sandbox create` | Create a new sandbox. Refer to the flag reference below. | | `openshell sandbox get [name]` | Show detailed information about a sandbox. | | `openshell sandbox list` | List all sandboxes in the active cluster. | -| `openshell sandbox delete ` | Delete one or more sandboxes by name. | +| `openshell sandbox delete ` | Delete one or more sandboxes by name. Use `--all` to delete every sandbox in the active gateway. | | `openshell sandbox connect [name]` | Open an interactive SSH session into a running sandbox. | | `openshell sandbox upload [name]` | Upload files from the host into a sandbox. | | `openshell sandbox download [name]` | Download files from a sandbox to the host. | @@ -242,3 +242,5 @@ $ openshell sandbox --help $ openshell sandbox create --help $ openshell gateway --help ``` + +Help output groups flags under distinct headings: `FLAGS` for command-specific options, `GATEWAY FLAGS` for `--gateway` and `--gateway-endpoint`, and `GLOBAL FLAGS` for `--verbose`, `--help`, and `--version`. diff --git a/docs/reference/support-matrix.md b/docs/reference/support-matrix.md index cc39a370f..3633ff20a 100644 --- a/docs/reference/support-matrix.md +++ b/docs/reference/support-matrix.md @@ -54,7 +54,7 @@ OpenShell uses several container images that are pulled automatically during gat | Cluster | ghcr.io | `ghcr.io/nvidia/openshell/cluster:latest` | `openshell gateway start` | | Server | ghcr.io | `ghcr.io/nvidia/openshell/server:latest` | Cluster startup (via Helm chart) | | Sandbox | ghcr.io | `ghcr.io/nvidia/openshell/sandbox:latest` | First sandbox creation (via Helm chart) | -| Community sandboxes | CloudFront CDN | `d1i0nduu2f6qxk.cloudfront.net/openshell-community/sandboxes/{name}:latest` | `openshell sandbox create --from ` | +| Community sandboxes | GHCR | `ghcr.io/nvidia/openshell-community/sandboxes/{name}:latest` | `openshell sandbox create --from ` | The cluster image is based on `rancher/k3s:v1.35.2-k3s1` and bundles the Helm charts and Kubernetes manifests required to bootstrap the control plane. The server and sandbox images are pulled separately at runtime. diff --git a/docs/sandboxes/create-and-manage.md b/docs/sandboxes/create-and-manage.md index c97919b53..cb734e267 100644 --- a/docs/sandboxes/create-and-manage.md +++ b/docs/sandboxes/create-and-manage.md @@ -174,6 +174,12 @@ Delete a sandbox by name: $ openshell sandbox delete my-sandbox ``` +Delete all sandboxes in the active gateway: + +```console +$ openshell sandbox delete --all +``` + ## Next Steps Explore related topics: