diff --git a/charts/workspace/scripts/env.reference.yaml b/charts/workspace/scripts/env.reference.yaml index 186997c..0336512 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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.3.1 + 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 @@ -298,16 +469,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 +535,7 @@ envs: type: string default: null delimiter: "," + pattern: "[a-zA-Z0-9.:/_~?#=&%+-]+" since: 0.2.0 example: >- https://github.com,https://stackoverflow.com @@ -405,7 +567,7 @@ envs: dir: type: path - default: /usr/share/workspace/features + default: /usr/share/workspace/features.d reference: /editor/features since: 0.20.0 description: Directory path where additional features are located. @@ -413,6 +575,20 @@ envs: 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 +646,12 @@ envs: logging: properties: + auth_proxy_file: + type: string + default: auth-proxy.log + description: Log file for the OIDC authentication proxy. + since: 0.3.1 + dir: type: path default: /var/log/workspace @@ -486,12 +668,24 @@ 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 + metrics: properties: collectors: @@ -576,18 +770,20 @@ envs: `/run/secrets/workspace/secrets/master_key`. 5. Schema default *(unset)*. - vault: - 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. - longDescription: | - A YAML file containing encrypted secrets that can be decrypted and - deployed to various destinations during startup. - server: properties: + auth_proxy_port: + type: integer + default: 38080 + since: 0.3.1 + 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. + port: type: integer default: 8080 @@ -598,17 +794,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 @@ -747,6 +947,7 @@ envs: 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 +1018,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 +1180,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: | + Place your vault manifest at `~/.ws/vault/secrets.yaml`; + it is auto-discovered at boot. No environment variable + is required. + WS_ZSH_EXTRA_PLUGINS: use: WS_ZSH_ADDITIONAL_PLUGINS since: 0.0.20