From f2bf357c2bcebd80ef9b8fd7d7912a592073427c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:44:05 +0000 Subject: [PATCH] docs(website): sync dev docs from dbe36eaf85c2980a35b5da4c3ab1461e0afafa50 --- fern/.docs-snapshots.yml | 6 +++--- fern/pages-dev/reference/gateway-config.mdx | 10 +++++++--- fern/pages-dev/sandboxes/manage-sandboxes.mdx | 11 +++++++++++ 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/fern/.docs-snapshots.yml b/fern/.docs-snapshots.yml index a0b761b44..5216887ca 100644 --- a/fern/.docs-snapshots.yml +++ b/fern/.docs-snapshots.yml @@ -1,5 +1,5 @@ snapshots: dev: - source-ref: 481ce566e1e3cc845f37a73e0f52ce9dba64a9f1 - source-sha: 481ce566e1e3cc845f37a73e0f52ce9dba64a9f1 - version: 0.0.117.dev147 + source-ref: dbe36eaf85c2980a35b5da4c3ab1461e0afafa50 + source-sha: dbe36eaf85c2980a35b5da4c3ab1461e0afafa50 + version: 0.0.117.dev150 diff --git a/fern/pages-dev/reference/gateway-config.mdx b/fern/pages-dev/reference/gateway-config.mdx index 528ef9d88..ab24fd26b 100644 --- a/fern/pages-dev/reference/gateway-config.mdx +++ b/fern/pages-dev/reference/gateway-config.mdx @@ -443,7 +443,8 @@ For Vault instead: credential_drivers = ["vault"] [openshell.credential_drivers.vault] -address = "http://vault.vault.svc.cluster.local:8200" +address = "https://vault.vault.svc.cluster.local:8200" +ca_bundle = "/etc/openshell/vault/ca.pem" mount = "secret" kv_version = "2" auth_method = "kubernetes" @@ -463,7 +464,9 @@ server: For `kubernetes-secrets`, `namespace` sets where OpenShell-managed provider Secret objects are stored. When omitted, the driver uses the in-cluster ServiceAccount namespace when available, otherwise `default`. The Helm chart creates a Role granting the gateway access to all Secrets in the credential namespace because OpenShell-managed Secret names are dynamic SHA-256 hashes that cannot be restricted with `resourceNames`. Deploy credential Secrets in a dedicated namespace (`server.credentialDrivers.kubernetesSecrets.namespace`) to limit the RBAC blast radius. -For `vault`, `address` points at the Vault service, `mount` and `kv_version` describe the KV engine where OpenShell-managed provider secrets are stored, and `auth_method = "kubernetes"` logs in with the gateway Pod's ServiceAccount token. For local or development validation, use `auth_method = "token_file"` with `token_path = "/path/to/token"`. Do not put literal Vault tokens in TOML. +For `vault`, `address` points at the Vault service. Non-loopback endpoints must use HTTPS; plaintext HTTP is accepted only for `localhost` or an IP loopback address during local development. Vault requests do not follow redirects, preventing credentials from being replayed to a downgraded or substituted endpoint. HTTPS uses platform trust roots by default. Set `ca_bundle` to a certificate-only PEM bundle for a private Vault CA; the bundle augments platform roots and normal hostname verification remains enabled. `mount` and `kv_version` describe the KV engine where OpenShell-managed provider secrets are stored, and `auth_method = "kubernetes"` logs in with the gateway Pod's ServiceAccount token. For local or development validation, use `auth_method = "token_file"` with `token_path = "/path/to/token"`. Do not put literal Vault tokens in TOML. + +For Helm deployments, set `server.credentialDrivers.vault.caConfigMapName` to a ConfigMap containing the private CA bundle under the `ca.crt` key. The chart mounts that key and renders `ca_bundle` automatically. Provider records that already contain inline database credentials remain readable for upgrade compatibility. New provider create/update requests still submit credential values through the normal API, but the gateway stores those values through the active credential storage path and persists only handles. Before OpenShell 0.1.0, OpenShell does not automatically migrate inline refresh material or credential handles between drivers. Reconfigure refresh grants after an upgrade. Before changing credential drivers, remove affected credentials while the original driver is still available, then select the new driver and create them again. Do not run mixed gateway versions against the same refresh records. @@ -494,7 +497,8 @@ transport = "uds" socket_path = "/run/openshell/credential-drivers/vault.sock" command = "/usr/libexec/openshell/openshell-driver-vault" args = [ - "--address", "http://vault.vault.svc.cluster.local:8200", + "--address", "https://vault.vault.svc.cluster.local:8200", + "--ca-bundle", "/etc/openshell/vault/ca.pem", "--auth-method", "kubernetes", "--role", "openshell-gateway", ] diff --git a/fern/pages-dev/sandboxes/manage-sandboxes.mdx b/fern/pages-dev/sandboxes/manage-sandboxes.mdx index 5a1e32869..730b7da79 100644 --- a/fern/pages-dev/sandboxes/manage-sandboxes.mdx +++ b/fern/pages-dev/sandboxes/manage-sandboxes.mdx @@ -46,6 +46,17 @@ captures the command result, and deletes the sandbox after the command exits: openshell sandbox create --no-keep -- sh -c 'echo done; exit 0' ``` +Combine `--detach` and `--no-keep` for a background workload whose lifecycle +belongs entirely to the gateway: + +```shell +openshell sandbox create --detach --no-keep -- ./worker +``` + +The create command returns after the workload is ready. The gateway keeps the +canonical process running without a host-side attachment and deletes the +sandbox after that process exits. + `--upload` cannot yet be combined with a trailing main command because uploads finish after the canonical process starts. Create a scratch sandbox, upload the files, then launch the workload with `sandbox exec`, or build the files into the