From f80477ab5ef575b4a9844c02f496e1b2595ea38c Mon Sep 17 00:00:00 2001 From: kloud-bot Date: Fri, 10 Jul 2026 08:27:25 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=84=20Sync=20shared=20files=20from=20`?= =?UTF-8?q?ws-meta`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- charts/workspace/scripts/env.reference.yaml | 437 ++++++++++++++++++-- 1 file changed, 412 insertions(+), 25 deletions(-) diff --git a/charts/workspace/scripts/env.reference.yaml b/charts/workspace/scripts/env.reference.yaml index 186997c..292033e 100644 --- a/charts/workspace/scripts/env.reference.yaml +++ b/charts/workspace/scripts/env.reference.yaml @@ -70,6 +70,7 @@ envs: type: string default: null delimiter: ; + pattern: "[a-zA-Z0-9 ./:_=~+[\\]-]+" reference: /tools/apt example: >- deb http://one.test trixie main; deb http://two.test trixie main @@ -107,12 +108,30 @@ envs: The workspace ships with a set of preference files that block GUI/desktop and other packages that have no use inside a headless container *(`x11`, `desktop`, `mail`, `printing`, `daemons`, - `language-pack`, `obsolete`)*. + `cni`, `language-pack`, `obsolete`)*. Accepts either: - A **space-delimited** list of restriction names. - A boolean `true` or `*` value to disable all restrictions. + override_restrictions: + type: boolean + default: false + since: 0.3.0 + reference: /tools/apt + example: "true" + description: Temporarily lifts all APT install restrictions for `additional_packages`. + longDescription: | + Distinct from `disable_restrictions`, which **permanently** lifts + restrictions at startup. This flag applies **only** to the + `additional_packages` install step: every active + `/etc/apt/preferences.d/99-deny-*` pin is renamed to `.disabled` + immediately before the install and restored when it completes + *(including on failure)*. + + Set to `true` when an entry in `additional_packages` is blocked by + a shipped restriction and a permanent lift is undesirable. + update_cache: type: boolean default: false @@ -125,7 +144,7 @@ envs: disable_sudo: type: boolean default: false - since: 0.3.0 + since: 0.0.2 description: Disables password-less `sudo`. github_token: @@ -150,6 +169,158 @@ envs: `/run/secrets/workspace/auth/github_token`. 4. Schema default *(unset)*. + mode: + type: string + default: password + since: 0.4.0 + example: oidc + description: Web authentication mode, either `password` or `oidc`. + reference: /editor/authentication + longDescription: | + - `password` *(default)*: the editor's built-in password login via + `WS_AUTH_PASSWORD` / `WS_AUTH_PASSWORD_HASHED`. Unchanged behaviour. + - `oidc`: an in-workspace oauth2-proxy listens on + `WS_SERVER_AUTH_PROXY_PORT` and authenticates every request against + `WS_AUTH_OIDC_ISSUER` before forwarding to the editor, which binds + loopback-only on `WS_SERVER_PORT`. Requires `WS_AUTH_OIDC_ISSUER`, + `WS_AUTH_OIDC_CLIENT_ID` and `WS_AUTH_OIDC_CLIENT_SECRET`. Publish + the proxy port. + + Any other value is treated as `password`. + + oidc_allowed_emails: + type: string + default: null + delimiter: " " + since: 0.4.0 + example: alice@corp.com bob@corp.com + description: Restrict OIDC login to an explicit email allowlist. + reference: /editor/authentication + longDescription: | + A **space-delimited** list. When unset, any email the IdP + authenticates is allowed. `oidc` assumes a single-user workspace + whose authorization is enforced upstream. Only used when + `WS_AUTH_MODE=oidc`. + + oidc_allowed_groups: + type: string + default: null + delimiter: " " + since: 0.4.0 + example: engineering platform + description: Restrict OIDC login to members of these IdP groups. + reference: /editor/authentication + longDescription: | + A **space-delimited** list mapped to oauth2-proxy `--allowed-group`. + Only used when `WS_AUTH_MODE=oidc`. + + oidc_client_id: + type: string + default: null + since: 0.4.0 + example: workspace + description: OIDC client ID. Required when `WS_AUTH_MODE=oidc`. + reference: /editor/authentication + + oidc_client_secret: + type: string + default: null + secret: true + since: 0.4.0 + description: OIDC client secret. Required when `WS_AUTH_MODE=oidc`. + reference: /editor/authentication + longDescription: | + Required for oidc mode. oauth2-proxy authenticates to the IdP as a + confidential client and refuses to start without it. PKCE + (`--code-challenge-method=S256`) is layered on top as defence in + depth. Register the workspace as a confidential client and supply its + secret here. Never baked or shared, provide it per deployment via the + resolution chain below. + + **Resolution chain:** + + 1. Env literal: `WS_AUTH_OIDC_CLIENT_SECRET=...`. + 2. `file:` env value: `WS_AUTH_OIDC_CLIENT_SECRET=file:/path/to/secret`. + 3. Convention default: file mounted at + `/run/secrets/workspace/auth/oidc_client_secret`. + 4. Schema default *(unset)*. + + oidc_cookie_secret: + type: string + default: null + secret: true + since: 0.4.0 + description: Secret that signs and encrypts the oauth2-proxy session cookie. + reference: /editor/authentication + longDescription: | + A 16, 24, or 32-byte secret (raw or base64). When unset it is + generated once and persisted under the workspace home so sessions + survive restarts and redeploys that reattach the volume. For + multi-replica or volume-less deployments, set this to a shared value + so every instance signs cookies identically. Only used when + `WS_AUTH_MODE=oidc`. + + **Resolution chain:** + + 1. Env literal: `WS_AUTH_OIDC_COOKIE_SECRET=...`. + 2. `file:` env value: `WS_AUTH_OIDC_COOKIE_SECRET=file:/path/to/secret`. + 3. Convention default: file mounted at + `/run/secrets/workspace/auth/oidc_cookie_secret`. + 4. Generated and persisted *(unset)*. + + oidc_forbidden_message: + type: string + default: Contact your administrator to request access; retrying will not help. + since: 0.4.0 + example: Contact the platform team to request access. + description: Custom guidance shown on the OIDC not-authorized (403) page. + reference: /editor/authentication + longDescription: | + Replaces the default guidance on the 403 error page shown when an + authenticated user is denied (failed group/email allowlist). When + unset, a default "contact your administrator" message is shown. Only + used when `WS_AUTH_MODE=oidc`. + + oidc_issuer: + type: string + default: null + since: 0.4.0 + example: https://idp.example.com + description: OIDC issuer URL. Required when `WS_AUTH_MODE=oidc`. + reference: /editor/authentication + longDescription: | + The OpenID Connect issuer (discovery base URL). For Active Directory, + point at an OIDC-fronting issuer (Entra ID, Keycloak, dex) rather than + raw LDAP. + + oidc_redirect_url: + type: string + default: null + since: 0.4.0 + example: https://ws.example.com/oauth2/callback + description: Explicit OAuth redirect URL override. + reference: /editor/authentication + longDescription: | + When unset, oauth2-proxy derives the callback from the incoming + request host as `https:///oauth2/callback`. Set this when the + externally-visible host differs from what oauth2-proxy can infer + (e.g. behind a terminator that rewrites the Host header). The in-IDE + logout action also uses this value to build the sign-out URL. Only + used when `WS_AUTH_MODE=oidc`. + + oidc_scopes: + type: string + default: openid email profile + delimiter: " " + since: 0.4.0 + example: openid email profile groups + description: OAuth scopes requested at login. + reference: /editor/authentication + longDescription: | + A **space-delimited** scope list requested from the IdP. Add `groups` + when you use `WS_AUTH_OIDC_ALLOWED_GROUPS` and your IdP exposes a + `groups` scope. Only used when `WS_AUTH_MODE=oidc`. + password: type: string default: null @@ -193,6 +364,18 @@ envs: `/run/secrets/workspace/auth/password_hashed`. 4. Schema default *(unset)*. + session_ttl: + type: integer + default: 86400 + since: next + description: Lifetime *(seconds)* of an authenticated web session. + reference: /editor/authentication + longDescription: | + The session cookie carries a rolling expiry, renewed on each + authenticated request and keep-alive ping, so an actively-used + session never drops. A missing or malformed value falls back to the + default. Only used when `WS_AUTH_MODE=password`. + ca: name: Enterprise CA properties: @@ -276,6 +459,31 @@ envs: reference: /tools/claude description: Shell used to execute the statusline script. + cloudflared: + properties: + tunnel_token: + type: string + default: null + secret: true + since: 0.4.0 + description: Cloudflare tunnel connector token. + reference: /tools/cloudflared + longDescription: | + Connector credential for a remotely-managed *(dashboard or API + created)* Cloudflare named tunnel. When set, and the opt-in + `cloudflared` feature is installed — the tunnel starts automatically + under s6 supervision *(`cloudflared tunnel --no-autoupdate run`)* and + restarts on death. When unset, the tunnel stays dormant. Never baked + or shared, provide it per deployment via the resolution chain below. + + **Resolution chain:** + + 1. Env literal: `WS_CLOUDFLARED_TUNNEL_TOKEN=...`. + 2. `file:` env value: `WS_CLOUDFLARED_TUNNEL_TOKEN=file:/path/to/token`. + 3. Convention default: file mounted at + `/run/secrets/workspace/cloudflared/tunnel_token`. + 4. Schema default *(unset)*. + docker: properties: enable_client: @@ -298,16 +506,6 @@ envs: Accepts a **space-delimited** list of extensions. reference: /editor/extensions - additional_vs_extensions_dir: - type: string - default: null - deprecated: 0.2.0 - reference: /editor/extensions - example: /additional-extensions - description: Installs `.vsix` file found in this directory. - longDescription: | - Use this when you package proprietary or pre-downloaded extensions. - comments_disable_font: type: boolean default: false @@ -374,6 +572,7 @@ envs: type: string default: null delimiter: "," + pattern: "[a-zA-Z0-9.:/_~?#=&%+-]+" since: 0.2.0 example: >- https://github.com,https://stackoverflow.com @@ -405,14 +604,28 @@ envs: dir: type: path - default: /usr/share/workspace/features + default: /usr/share/workspace/features.d reference: /editor/features - since: 0.20.0 + since: 0.0.20 description: Directory path where additional features are located. longDescription: | Specify the full path to the directory containing the features to be loaded or referenced at startup. + store_allow_fallback: + type: boolean + default: false + since: 0.3.0 + reference: /editor/features#feature-store + description: Allow upstream Debian fallback on older-drift detection. + longDescription: | + When the ws-feature-store serves a package strictly older than what + the workspace already has installed, opt into temporarily re-enabling + `debian.sources` for this install. Only effective when + `WS_APT_DISABLE_REPOS` does NOT cover `debian`. In air-gapped + deployments (no path to `deb.debian.org`) this knob has no effect — + the install proceeds via the per-install Pin fragment regardless. + store_url: type: string default: null @@ -470,6 +683,18 @@ envs: logging: properties: + auth_proxy_file: + type: string + default: auth-proxy.log + description: Log file for the OIDC authentication proxy. + since: 0.4.0 + + cloudflared_file: + type: string + default: cloudflared.log + description: Log file for the Cloudflared tunnel. + since: 0.4.0 + dir: type: path default: /var/log/workspace @@ -486,12 +711,84 @@ envs: `"${WS_LOGGING_DIR}/${WS_LOGGING_MAIN_FILE}"`. since: 0.0.22 + docker_file: + type: string + default: dockerd.log + description: Log file for the in-container Docker daemon. + since: 0.3.0 + main_file: type: string default: workspace.log description: Combined log file for `stdout` and `stderr`. since: 0.0.21 + metrics_file: + type: string + default: metrics.log + description: Log file for the metrics exporter. + since: 0.3.0 + + marketplace: + properties: + control_url: + type: string + default: null + since: next + reference: /editor/extensions + example: https://open-vsx.org/vscode/control + description: Overrides the gallery `controlUrl`. + + extension_url_template: + type: string + default: null + since: next + reference: /editor/extensions + example: https://open-vsx.org/vscode/gallery/{publisher}/{name}/latest + description: Overrides the gallery `extensionUrlTemplate`. + + gallery: + type: string + default: null + since: next + reference: /editor/extensions + example: | + { + "serviceUrl": "https://open-vsx.org/vscode/gallery", + "itemUrl": "https://open-vsx.org/vscode/item" + } + description: Complete JSON override for the extension gallery. + longDescription: | + A complete gallery JSON object that replaces the baked Open VSX + default. The per-key variables *(`WS_MARKETPLACE_SERVICE_URL`, ...)* + are layered on top. Malformed JSON is ignored and the baked default + is kept. + + item_url: + type: string + default: null + since: next + reference: /editor/extensions + example: https://open-vsx.org/vscode/item + description: Overrides the gallery `itemUrl`. + + resource_url_template: + type: string + default: null + since: next + reference: /editor/extensions + example: >- + https://open-vsx.org/vscode/asset/{publisher}/{name}/{version}/Microsoft.VisualStudio.Code.WebResources/{path} + description: Overrides the gallery `resourceUrlTemplate`. + + service_url: + type: string + default: null + since: next + reference: /editor/extensions + example: https://open-vsx.org/vscode/gallery + description: Overrides the gallery `serviceUrl`. + metrics: properties: collectors: @@ -551,6 +848,38 @@ envs: The metrics server exposes a `/` endpoint on this port. Default port `9100` follows the `node_exporter` convention. + npm: + name: npm + properties: + additional_packages: + type: string + default: null + delimiter: " " + since: 0.4.0 + example: prettier@3.2.5 @angular/cli + description: Additional global npm packages installed during startup. + longDescription: | + Accepts a **space-delimited** package list. Each entry is a full npm + spec, so `@version` pins *(`prettier@3.2.5`)* and scoped packages + *(`@angular/cli`)* are supported. + + pip: + name: pip + properties: + additional_packages: + type: string + default: null + delimiter: " " + since: 0.4.0 + reference: /tools/python + example: httpx==0.27.0 rich + description: Additional global Python packages installed during startup. + longDescription: | + Accepts a **space-delimited** package list. Each entry is a full pip + spec, so `==` pins *(`httpx==0.27.0`)* and extras *(`rich[jupyter]`)* + are supported. For installable CLI tools prefer + `WS_UV_ADDITIONAL_TOOLS`. + secrets: properties: master_key: @@ -559,9 +888,9 @@ envs: secret: true example: dGhpcyBpcyBhIHNlY3JldCBrZXkgZXhhbXBsZQ== since: 0.1.1 - description: Master encryption key for secrets vault. + description: Master encryption key for seed secrets. longDescription: | - Used to encrypt and decrypt secrets in the vault. + Used to encrypt and decrypt secrets projected by the seed engine. Can be provided as: - A base64-encoded string. @@ -576,18 +905,45 @@ envs: `/run/secrets/workspace/secrets/master_key`. 5. Schema default *(unset)*. - vault: + seed: + properties: + source: type: path - default: ~/.ws/vault/secrets.yaml - example: /custom/path/vault/secrets.yaml - since: 0.1.1 - description: Path to the secrets vault manifest file. + default: ~/.ws/seed.d + since: next + example: /mnt/seed + reference: /settings/seed + description: Directory projected onto the filesystem at startup. longDescription: | - A YAML file containing encrypted secrets that can be decrypted and - deployed to various destinations during startup. + Bare files mirror the filesystem tree; a hidden `.seed.yaml` manifest + overlays declarative behaviors (merge/append/prepend/block, + templating, whole-file secrets). Re-projected on every boot; empty or + absent is a no-op. server: properties: + auth_proxy_port: + type: integer + default: 38080 + since: 0.4.0 + description: Port the OIDC auth proxy listens on when WS_AUTH_MODE is oidc. + reference: /editor/authentication + longDescription: | + When WS_AUTH_MODE=oidc the auth proxy listens on this port and + forwards authenticated traffic to the editor on WS_SERVER_PORT. + Publish this port instead of WS_SERVER_PORT so every request is + authenticated before it reaches the editor. + + host: + type: string + default: 0.0.0.0 + since: next + description: Address on which the web server listens. + longDescription: | + Binds all interfaces by default so Docker-published traffic reaches + the editor. Set to `127.0.0.1` to restrict the listener to loopback + when a front proxy on the same host terminates external traffic. + port: type: integer default: 8080 @@ -598,17 +954,21 @@ envs: type: string default: null delimiter: " " + pattern: "[a-zA-Z0-9.{}_-]+" since: 0.0.20 example: ws.dev local.ws.dev description: >- Domain suffix used to expose server's forwarded ports. longDescription: >- Accepts either a single domain suffix or multiple - **space-delimited** suffixes. + **space-delimited** suffixes. Each suffix is exposed as + `{{port}}.`; the `{{port}}.` prefix is added automatically + unless the suffix already contains a `{{port}}` placeholder + (e.g. `{{port}}-project.ws.dev`). Wildcards are not accepted. > Multiple domain support was added in `v0.0.22`. reference: /editor/port-forwarding - root_dir: + root: type: path default: /workspace since: 0.0.20 @@ -741,12 +1101,30 @@ envs: reference: /editor/terminal description: Hides the current user in the prompt. + uv: + name: uv + properties: + additional_tools: + type: string + default: null + delimiter: " " + since: 0.4.0 + reference: /tools/python + example: ruff poetry==1.8.0 + description: Additional global Python CLI tools installed during startup. + longDescription: | + Accepts a **space-delimited** package list. Each entry is a full uv + spec, so `==` pins *(`poetry==1.8.0`)* are supported. Installs global + CLI tools only — for importable libraries use + `WS_PIP_ADDITIONAL_PACKAGES`. + zsh: properties: additional_plugins: type: string default: null delimiter: " " + pattern: "[a-zA-Z0-9_-]+" since: 0.0.20 example: php description: Loads additional `oh-my-zsh` plugins. @@ -817,6 +1195,7 @@ envs: golang helm kubectl npm python pip ssh-agent yarn zsh-autosuggestions delimiter: " " + pattern: "[a-zA-Z0-9_-]+" example: kubectl npm python pip description: Enables built-in `oh-my-zsh` plugins. longDescription: | @@ -978,6 +1357,14 @@ deprecated: Set WS_SECRETS_MASTER_KEY=file:/path or mount the secret at /run/secrets/workspace/secrets/master_key. + WS_SECRETS_VAULT: + since: 0.3.0 + removed: 0.3.0 + message: | + The secrets vault has been removed. Declare secrets in the seed + manifest at `/.seed.yaml` (the `secrets:` map and + `secret: true` entries); see /tools/seed. + WS_ZSH_EXTRA_PLUGINS: use: WS_ZSH_ADDITIONAL_PLUGINS since: 0.0.20