mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-30 07:33:59 +08:00
Derek Carr
9c019a93f5
* feat(auth): implement RFC 0011 Phase 2 workspace authorization Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address PR review feedback on workspace authorization - Docker e2e: add --health-port and switch readiness probe from `openshell status` to `curl /healthz`, fixing a false-positive readiness check in OIDC mode where the CLI exited 0 without actually contacting the gateway - ListWorkspaces: move membership filtering from post-query N+1 lookups into a SQL EXISTS subquery so pagination applies to the visible set, not the global ordering. Add generic list_with_membership to the persistence layer. - Descriptor validator: reject role/scope fields on unauthenticated and sandbox auth modes, and allow-list workspace_role as user/admin and global_role as platform_admin to catch typos at startup Signed-off-by: Derek Carr <decarr@redhat.com> * fix(server): use authed request in delete telemetry test The workspace authorization added by the Phase 2 auth changes requires a Principal on every delete request. The delete-telemetry test was still using a bare Request::new, so extract_principal failed before the handler could acquire the delete gate, causing a 5-second timeout flake. Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address gator review findings for workspace authorization - Inject unauthenticated-local-dev principal in no-auth gateway mode so handlers that call extract_principal() always find one. - Cap label-selector membership query at MAX_PAGE_SIZE instead of u32::MAX to bound the in-memory read. - Authorize workspace membership before resolving workspace existence in all sandbox RPCs to prevent workspace-name enumeration by non-members. - Remove dead_code allow on AuthorizedWorkspace.workspace now that callers use the normalized name from the authz result. Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): close workspace-name oracle and label-selector truncation Swap authorize-before-resolve ordering in 27 handlers across provider.rs, service.rs, policy.rs, and workspace.rs to prevent CWE-203 workspace-name enumeration by non-members. Add combined membership+label SQL query (list_with_membership_and_selector) to both persistence backends so ListWorkspaces with label selectors no longer silently drops results beyond the first page of membership matches. Signed-off-by: Derek Carr <decarr@redhat.com> * test(auth): add non-member rejection and membership+label persistence tests Add comprehensive test coverage for workspace authorization changes: - Non-member rejection tests across all 44 workspace-scoped handlers (sandbox, provider, service, policy, workspace, inference) verifying PERMISSION_DENIED is returned instead of NOT_FOUND to prevent CWE-203 workspace-name oracle - Persistence test for list_with_membership_and_selector verifying SQL-level membership EXISTS + label filtering, multiple predicates, no-match cases, and pagination Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): format merged import line in sandbox tests Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address gator re-review findings on workspace authorization - Fix TUI unconditionally setting providers_v2_enabled after provider refresh; read the actual gateway setting via GetGatewayConfig at startup instead - Fix SQLite json_extract with dotted label keys (e.g. example.com/env) by quoting the key in the JSON path - Add authed_request wrappers to upstream OCI identity tests that were missing a principal after rebase - Add test proving GetGatewayConfig is accessible without Platform Admin - Add test for dotted/prefixed Kubernetes-style label key filtering Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address second gator re-review findings - Loosen GetGatewayConfig from platform_admin to scope-only so workspace users can discover providers_v2_enabled during sandbox creation with inferred-provider commands; update proto descriptor, descriptor validation, and RFC 0011 access table - Add validate_label_selector to handle_list_workspaces and escape single quotes in SQLite json_extract interpolation (CWE-89 defense-in-depth) - Re-fetch providers_v2_enabled after TUI gateway switch so the new gateway's capability is reflected - Add e2e test for workspace user with inferred-provider command - Add persistence test for adversarial label keys with SQL injection attempts - Add handler test for invalid label selector rejection in ListWorkspaces Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address third gator review findings - Cap label selector pairs at 64 (CWE-400) to bound SQLite dynamic SQL - Add SCOPE_ONLY_METHODS allowlist for scope-without-role RPCs (CWE-863) - Normalize ID-based data-plane handlers to return NOT_FOUND for unauthorized sandboxes, closing the cross-workspace oracle (CWE-203) - Fix TUI provider profile cache lookup key mismatch for legacy providers with empty profile_workspace - Add whoami to CLI skill reference command tree - Update TUI skill doc with workspace, provider, and settings coverage - Document scope/workspace orthogonality on GetGatewayConfig proto Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): extend CWE-203 normalization to policy.rs sandbox handlers GetSandboxConfig and GetSandboxLogs in policy.rs had the same fetch-before-authorize pattern that leaked cross-workspace sandbox existence. Promote fetch_and_authorize_sandbox to pub(super) and use it from both sandbox.rs and policy.rs handlers. Signed-off-by: Derek Carr <decarr@redhat.com> * test(auth): update assertions for CWE-203 sandbox ID normalization Cross-workspace sandbox access via ID-based handlers now returns NOT_FOUND instead of PERMISSION_DENIED to prevent existence inference. Update the unit test and OIDC e2e assertion to match. Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): narrow CWE-203 error mapping and correct whoami output formats Only remap PERMISSION_DENIED to NOT_FOUND in fetch_and_authorize_sandbox and RevokeSshSession, letting INTERNAL and UNAUTHENTICATED propagate as-is. Fix whoami --output format values in cli-reference.md to match the actual CLI (table/json/yaml, not text/json). Signed-off-by: Derek Carr <decarr@redhat.com> * fix(ci): share network namespace with Keycloak in containerized CI In GitHub Actions job containers, Docker port publishing lands on the host, not inside the job container. Detect this environment and attach Keycloak to the job container's network namespace instead, with hardened defaults (cap-drop ALL, no-new-privileges, loopback-only listener). Signed-off-by: Derek Carr <decarr@redhat.com> --------- Signed-off-by: Derek Carr <decarr@redhat.com>
200 lines
9.0 KiB
Plaintext
200 lines
9.0 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "Manage Gateways"
|
|
sidebar-title: "Gateways"
|
|
description: "Register OpenShell gateways, switch between environments, inspect gateway status, and troubleshoot gateway access."
|
|
keywords: "Generative AI, Cybersecurity, Gateway, Docker, Podman, Kubernetes, MicroVM, CLI"
|
|
position: 2
|
|
---
|
|
|
|
The gateway is the control plane for OpenShell. All control-plane traffic between the CLI and running sandboxes flows through the gateway.
|
|
|
|
The gateway is responsible for:
|
|
|
|
- Provisioning and managing sandboxes, including creation, deletion, and status monitoring.
|
|
- Storing provider credentials and delivering them to sandboxes at startup.
|
|
- Delivering network and filesystem policies to sandboxes. Policy enforcement itself happens inside each sandbox through the proxy, OPA, Landlock, and seccomp.
|
|
- Managing inference configuration and serving inference bundles so sandboxes can route requests to the correct backend.
|
|
- Providing the SSH tunnel endpoint so you can connect to sandboxes without exposing them directly.
|
|
|
|
OpenShell separates gateway access from the compute driver that runs sandboxes. Use [Installation](/about/installation) to install OpenShell, choose a compute driver, and start a gateway. This page covers working with gateway entries after a gateway exists.
|
|
|
|
## Gateway Compute Drivers
|
|
|
|
A gateway provisions sandboxes through the compute driver configured for that gateway.
|
|
|
|
| Compute Driver | Where sandboxes run | Best for |
|
|
|---|---|---|
|
|
| Docker | Containers on the gateway host. | Solo development, quick iteration, and single-machine gateways. |
|
|
| Podman | Rootless containers on the gateway host. | Workstations that avoid a rootful Docker daemon. |
|
|
| Kubernetes | Pods in an operator-managed cluster. | Shared clusters and cloud environments. |
|
|
| MicroVM | VM-backed sandboxes. | Workflows that need VM-backed isolation. |
|
|
|
|
All compute drivers expose the same gateway API surface. Sandboxes, policies, and providers work the same after the CLI registers the gateway endpoint. The difference is how the gateway creates sandbox workloads and how operators expose the gateway to users.
|
|
|
|
<Tip>
|
|
For driver setup, including Docker, Podman, MicroVM, and Kubernetes paths, refer to [Installation](/about/installation).
|
|
|
|
</Tip>
|
|
|
|
## Configure Service Forwarding
|
|
|
|
Sandbox service routing is enabled for gateways by default. Users expose long-running sandbox services with `openshell service expose`, and the gateway routes browser traffic from the printed service URL to the loopback port inside the sandbox.
|
|
|
|
Loopback gateways use `openshell.localhost` service URLs. OpenShell prints a URL in the form `http://<sandbox>.openshell.localhost:<port>/` or `http://<sandbox>--<service>.openshell.localhost:<port>/` when a service name is provided.
|
|
|
|
Browser traffic enters the same gateway listener as mTLS-protected gRPC, but plaintext HTTP is accepted only from loopback clients and only for sandbox service hostnames. Gateway APIs, auth routes, health endpoints, and non-service hostnames remain unavailable over plaintext HTTP. Cross-origin and sibling-subdomain browser requests are rejected before reaching the sandbox service.
|
|
|
|
Disable the local browser path with `--enable-loopback-service-http=false` or `OPENSHELL_ENABLE_LOOPBACK_SERVICE_HTTP=false`.
|
|
|
|
Custom HTTPS service domains use the gateway server SAN configuration. Add a wildcard DNS SAN such as `*.apps.example.com` to the gateway certificate and pass the same SAN to the gateway with `--server-san` or `OPENSHELL_SERVER_SAN`.
|
|
|
|
For remote or non-loopback gateways, browser service URLs remain HTTPS and require normal gateway authentication.
|
|
|
|
## Register an Existing Gateway
|
|
|
|
Use `openshell gateway add` to register any reachable gateway endpoint so the CLI can target it.
|
|
|
|
Register a plaintext local endpoint, such as a trusted port-forward:
|
|
|
|
```shell
|
|
openshell gateway add http://127.0.0.1:8080 --local --name local
|
|
```
|
|
|
|
Register a gateway behind an authenticated reverse proxy:
|
|
|
|
```shell
|
|
openshell gateway add https://gateway.example.com --name production
|
|
```
|
|
|
|
This opens your browser for the proxy's login flow when the gateway uses edge authentication. If the token expires later, re-authenticate with:
|
|
|
|
```shell
|
|
openshell gateway login production
|
|
```
|
|
|
|
For direct mTLS endpoints, place the CLI client certificate bundle in the gateway credential directory described in [Gateway Authentication](/reference/gateway-auth), then register or select that gateway name.
|
|
|
|
## Manage Multiple Gateways
|
|
|
|
One gateway is always the active gateway. All CLI commands target it by default. `gateway add` sets the new gateway as active.
|
|
|
|
The active gateway is the persisted default. The `-g` flag and the `OPENSHELL_GATEWAY` environment variable override it when commands resolve a gateway. If `OPENSHELL_GATEWAY` is set to a different gateway, `openshell gateway select <name>` still saves the new default and warns that the current shell continues to use the environment value until you unset or update it.
|
|
|
|
Installers can seed read-only gateway entries for package-managed local services. By default the CLI reads these from `/etc/openshell`, using the same `active_gateway` plus `gateways/<name>/metadata.json` layout as per-user config. Packages can override that system config root with a non-empty absolute `OPENSHELL_SYSTEM_GATEWAY_DIR` when needed; empty or relative values fall back to `/etc/openshell` and log a warning. These entries appear in `openshell gateway list` and can be selected like user registrations. `openshell gateway list` and `openshell term` label each gateway as `user` or `system` so you can see which config layer owns it. `openshell gateway remove` removes only per-user registrations. Register a per-user gateway with the same name when you need to shadow an installer-provided default.
|
|
|
|
List all registered gateways. The table shows each gateway's endpoint, type,
|
|
config source, authentication mode, and remote target when a remote registration
|
|
has one:
|
|
|
|
```shell
|
|
openshell gateway list
|
|
```
|
|
|
|
Use structured output when you need the complete local registration metadata,
|
|
including `remote_host` and `resolved_host` for remote registrations:
|
|
|
|
```shell
|
|
openshell gateway list -o json
|
|
```
|
|
|
|
Switch the active gateway:
|
|
|
|
```shell
|
|
openshell gateway select production
|
|
```
|
|
|
|
Override the active gateway for a single command with `-g`:
|
|
|
|
```shell
|
|
openshell status -g staging
|
|
```
|
|
|
|
## Inspect Gateway Status
|
|
|
|
Use `openshell status` for a live gateway check. It reports gateway
|
|
reachability, authentication, and the gateway version independently:
|
|
|
|
```shell
|
|
openshell status
|
|
```
|
|
|
|
`Status: Connected` means the public health endpoint responded.
|
|
`Authentication: Authenticated` confirms the configured credentials also
|
|
passed the gateway authentication layer. If authentication fails while status
|
|
remains connected, run `openshell gateway login <name>` to refresh the stored
|
|
credentials.
|
|
|
|
For automation or scripting, use `--output json` or `--output yaml` to get machine-readable output:
|
|
|
|
```shell
|
|
openshell status --output json
|
|
```
|
|
|
|
Use `openshell gateway info` when you need elevated runtime details such as
|
|
initialized compute drivers and driver-reported capability versions:
|
|
|
|
```shell
|
|
openshell gateway info
|
|
```
|
|
|
|
Use structured output when scripting against live runtime info:
|
|
|
|
```shell
|
|
openshell gateway info -o json
|
|
```
|
|
|
|
Remove a local CLI registration without stopping the gateway service:
|
|
|
|
```shell
|
|
openshell gateway remove production
|
|
```
|
|
|
|
## Troubleshoot
|
|
|
|
Check gateway health:
|
|
|
|
```shell
|
|
openshell status
|
|
openshell gateway info
|
|
```
|
|
|
|
For Docker-backed local gateways, inspect Docker and the gateway process or container started by your local workflow:
|
|
|
|
```shell
|
|
openshell doctor check
|
|
openshell gateway list
|
|
```
|
|
|
|
For Kubernetes gateways, inspect the gateway workload and cluster events:
|
|
|
|
```shell
|
|
kubectl -n openshell get deployment,statefulset,pods
|
|
kubectl -n openshell logs deployment/openshell -c openshell-gateway --tail=100
|
|
kubectl -n openshell logs statefulset/openshell -c openshell-gateway --tail=100
|
|
kubectl -n openshell get events --sort-by=.lastTimestamp
|
|
```
|
|
|
|
For Podman or MicroVM gateways managed by systemd, inspect the user service and logs:
|
|
|
|
```shell
|
|
systemctl --user status openshell-gateway
|
|
journalctl --user -u openshell-gateway --no-pager -n 50
|
|
```
|
|
|
|
For sandbox startup failures, inspect the selected compute driver:
|
|
|
|
| Compute Driver | What to check |
|
|
|---|---|
|
|
| Docker | Docker daemon health, image availability, gateway logs, and sandbox container state. |
|
|
| Podman | Podman socket availability, rootless networking, image availability, and sandbox container state. |
|
|
| Kubernetes | Events and sandbox pods in the namespace configured by `server.sandboxNamespace`. |
|
|
| MicroVM | VM driver logs, rootfs availability, and gateway logs. |
|
|
|
|
## Next Steps
|
|
|
|
- To install OpenShell and choose a compute driver, refer to [Installation](/about/installation).
|
|
- To configure workspace membership and roles, refer to [Manage Workspaces and Access](/sandboxes/manage-workspaces).
|
|
- To create a sandbox using the gateway, refer to [Manage Sandboxes](/sandboxes/manage-sandboxes).
|