README.md.gotmpl

{{ template "rstudio.header" . }}

{{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }}{{ template "chart.appVersionBadge" . }}

{{ template "rstudio.description" . }}

{{ template "rstudio.disclaimer" . }}

{{ template "rstudio.install" . }}

## Required configuration

To function, this chart requires the following:

* A license file. See the [Licensing](#licensing) section below for more details.
* A Kubernetes [PersistentVolume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) that contains the
  home directory for users.
  * If `homeStorage.create` is set, it creates a Persistent Volume Claim (PVC) that relies on the default storage class to generate the
    PersistentVolume. Most Kubernetes environments do not have a default storage class that you can use
    with `ReadWriteMany` access mode out-of-the-box. In this case, we recommend that you:
      * Disable `homeStorage.create` and
    create your own `PersistentVolume` and `PersistentVolumeClaim`, then
      * Mount them into the container by specifying
    the `pod.volumes` and `pod.volumeMounts` parameters, or by specifying your `PersistentVolumeClaim`
    using `homeStorage.name` and `homeStorage.mount`.
  * If you cannot use a `PersistentVolume` to properly mount your users' home directories, mount your
    data in the container by using a
    regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes/#nfs), specified in `pod.volumes`
    and `pod.volumeMounts`.
  * If you cannot use a `Volume` to mount the directories, manually mount them during container startup
    with a mechanism similar to what is described below for joining to auth domains.
  * If not using `homeStorage.create`, configure `config.serverDcf.launcher-mounts` to ensure that the correct mounts are used when users create new sessions.
* If using load balancing (by setting `replicas > 1`), you need similar storage defined for `sharedStorage` to
  store shared project configuration. However, you can also configure the product to store its shared data underneath `/home` by
  setting `config.server.rserver\.conf.server-shared-storage-path=/home/some-shared-dir`.
* A method to join the deployed `rstudio-workbench` container to your auth domain. The default `rstudio/rstudio-workbench` image has `sssd` installed and started by default.
  You can include `sssd` configuration in `config.userProvisioning` like so:

    ```yaml
    config:
      userProvisioning:
        mysssd.conf:
          sssd:
            config_file_version: 2
            services: nss, pam
            domains: rstudio.com
          domain/rstudio.com:
            id_provider: ldap
            auth_provider: ldap
    ```
{{ template "rstudio.licensing" . }}

## Database

Workbench requires a PostgreSQL database when running in Kubernetes. You must configure a [valid connection URI and a password](https://docs.posit.co/ide/server-pro/database/configuration.html#postgresql) for the product to function correctly. The `database.conf` values may be defined in either `config.database.conf` or `config.secret.database.conf`. The former permits using a `database.conf` file as an existing Kubernetes `Secret`. The latter will automatically create a Kubernetes `Secret` for `database.conf` based on the defined values. In either method of defining database configuration details in the `values.yaml` file, it is possible to include the database password in the configuration section, however, we recommend only adding the connection URI and putting the database password in a Kubernetes `Secret`, which can be [automatically set as an environment variable](#database-password).


### Database configuration via `config.database.conf`

You can specify your database connection details in `config.database.conf` as follows:

```yaml
config:
  database:
    conf:
      value: |
        provider=postgresql
        connection-uri=postgres://<USERNAME>@<HOST>:<PORT>/<DATABASE>?sslmode=allow
```

or you can use an existing `Secret` that contains the database configuration file:

```yaml
config:
  database:
    conf:
      existingSecret: <name-of-secret-containing-database.conf`>
```

### Database configuration via `config.secret.database.conf`

Add the following to your `values.yaml`, replacing the `connection-uri` with your database details.

```yaml
config:
  secret:
    database.conf:
      provider: "postgresql"
      connection-uri: "postgres://<USERNAME>@<HOST>:<PORT>/<DATABASE>?sslmode=allow"
```
### Database password

First, create a `Secret` declaratively with YAML or imperatively using the following command (replacing with your actual password):

```bash
kubectl create secret generic {{ .Name }}-database --from-literal=password=YOURPASSWORDHERE
```

To avoid storing the password in your shell history, use:
```bash
kubectl create secret generic {{ .Name }}-database --from-file=password=/path/to/password-file
```
the file at `/path/to/password-file` should contain only the password.

Second, specify the following in your `values.yaml`:

```yaml
pod:
  env:
    - name: WORKBENCH_POSTGRES_PASSWORD
      valueFrom:
        secretKeyRef:
          name: {{ .Name }}-database
          key: password
```

Alternatively, database passwords may be set during `helm install` with the following argument:

`--set config.secret.'database\.conf'.password="<YOUR_PASSWORD_HERE>"`

## Session images

By default, session pods use the `rstudio/workbench-session` image with an init container
(`rstudio/workbench-session-init`) that delivers Workbench session components at pod startup.

To use the classic all-in-one `r-session-complete` image instead (which bundles all components
into a single image), disable session components and change the session image:

```yaml
session:
  image:
    repository: "rstudio/r-session-complete"
components:
  enabled: false
```

### Positron

To enable Positron IDE support, set a Positron version under `components.positron`:

```yaml
components:
  positron:
    version: "2026.03.0"
```

This configures an init container that delivers Positron binaries and documentation to
session pods. The version determines both the image tag and the server-side mount path.

## General principles

- In most places, we opt to pass Helm values directly into ConfigMaps. We automatically translate these into the
  valid `.ini` or `.dcf` file formats required by Workbench.
  - Those configuration files and their mount locations are covered in the [Configuration files](#configuration-files) section below.
- If you need to modify the jobs (sessions) launched by Workbench, use `launcher.templateValues` as described in the [Launcher Templates](#launcher-templates) section below.
- The prestart scripts for Workbench and Posit Job Launcher are highly customized to get the service account information off of the Workbench pod for use in launching jobs.

## Configuration files

These configuration values all take the form of usual Helm values
so you can set the database password with something like:

```{.bash}
... --set config.secret.database\.conf.password=mypassword ...
```

The files are converted into configuration files in the necessary format via go-templating. If you want to "in-line" a config file or mount it verbatim, you can use a pattern like:

```yaml
config:
  server:
    rserver.conf: |
      verbatim-file=format
```

The names of files are dynamically used, so you can add new files as needed. Beware that some files have default values,
so moving them can have adverse effects. Also, if you use a different mounting paradigm, you need to change
the `XDG_CONFIG_DIRS` environment variable.

- Session Configuration
  - These configuration files are mounted into the server and
    are mounted into the session pods.
  - `repos.conf`, `rsession.conf`, `notifications.conf`
  - Located in: <br>`config.session.<< name of file >>` Helm values
  - Mounted at:<br> `/mnt/session-configmap/rstudio/`
- Session Secret Configuration:
  - These configuration files are mounted into the server and session pods.
  - `odbc.ini` and other similar shared secrets.
  - Located in: <br>`config.sessionSecret.<< name of file>>` Helm values
  - Mounted at:<br> `/mnt/session-secret/`
- Secret Configuration:
  - These configuration files are mounted into the server with more restrictive permissions (0600).
  - `database.conf`, `openid-client-secret`, `databricks.conf`
  - Located in: <br>`config.secret.<< name of file >>` Helm values
  - Mounted at:<br> `/mnt/secret-configmap/rstudio/`
- Server Configuration:
  - These configuration files are mounted into the server (.ini file format).
  - `rserver.conf`, `launcher.conf`, `jupyter.conf`, `logging.conf`
  - Located at:<br> `config.server.<< name of file >>` Helm values
  - Mounted at:<br> `/mnt/configmap/rstudio/`
- Server DCF Configuration:
  - These configuration files are mounted into the server (.dcf file format).
  - `launcher-mounts`, `launcher-env`
  - Located at:<br> `config.serverDcf.<< name of file >>` Helm values
  - Included at:<br> `/mnt/configmap/rstudio/`
- Profiles Configuration:
  - These configuration files are mounted into the server (.ini file format).
  - `launcher.kubernetes.profiles.conf`
  - They are located at `config.profiles.<< name of file >>` Helm values
  - Included at:<br> `/mnt/configmap/rstudio/`
  - See the [Profiles](#rstudio-profiles) section below for more information.
- Prestart:
  - This is provided by the Helm chart in a configmap.
  - It is mounted into the pod at `/scripts/`.
  - `prestart-workbench.bash` is used to start workbench.
  - `prestart-launcher.bash` is used to start launcher.
- User Provisioning Configuration:
  - These configuration files are used for configuring user provisioning (i.e., `sssd`).
  - Located at:<br> `config.userProvisioning.<< name of file >>` Helm values
  - Mounted onto:<br> `/etc/sssd/conf.d/` with `0600` permissions by default.
- Custom Startup Configuration:
  - `supervisord` service / unit definition `.conf` files.
  - Use the `.ini` file format by default.
  - Mounted at:<br> `/startup/custom`
  - As with all configuration files above, you can override with a verbatim string if desired:
  - Located at:<br> `config.startupCustom.<< name of file >>` Helm values:
    ```yaml
    config:
      startupCustom:
        myfile.conf: |
          file-used-verbatim
    ```
- PAM configuration:
  - `pam` configuration files.
  - Located at:<br> `config.pam.<< name of file >>` Helm values
  - Mounted verbatim as individual files (using `subPath` mounts) at:<br> `/etc/pam.d/<< name of file >>`

#### Python repositories

pip can be configured with `config.session.pip.conf`:

  ```yaml
  config:
    session:
      pip.conf:
        "global":
          index-url: https://packagemanager.posit.co/pypi/latest/simple
          trusted-host: packagemanager.posit.co
  ```

#### R repositories

R package repositories can be configured with `config.session.repos.conf`:

```yaml
config:
  session:
    repos.conf:
      CRAN: https://packagemanager.posit.co/cran/__linux__/jammy/latest
```

For more information about configuring CRAN repositories in Workbench, see the [Posit Workbench Administrator Guide's - Package Installation > CRAN repositories](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/package_installation.html#cran-repositories) section.

## User provisioning

Provisioning users in Workbench containers is challenging. Session images create users automatically (with
consistent UIDs / GIDs). However, creating users in the Workbench containers is a responsibility that falls to the
administrator.

The most common way to provision users is via `sssd`.
The [latest Workbench container](https://github.com/rstudio/rstudio-docker-products/tree/main/workbench#user-provisioning)
has `sssd` included and running by default (see `userProvisioning` configuration files above).

The other way that this can be managed is via a lightweight startup service (runs once at startup and then sleeps forever)
or a polling service (checks at regular intervals). Either can be written easily in `bash` or another programming language.

However, it is important to use caution for the following:

- UID / GID consistency:
  - Linux usernames and their matching to UID/GID must be consistent across all nodes and across time.
  - Failing can cause security issues and access by some users to access view they should not be allowed to see.
- Usernames cannot have `@`.
  - The `@` sign (often used in emails with SSO) is a problem for Workbench because some operating systems disallow `@` signs in linux usernames.
- `supervisord` is configured by default to exit if any of its child processes exit.
  - If you use `config.startupCustom` to configure a user management service, be careful that it does not exit unnecessarily.

We do not provide such a service out-of-the box because we intend for Workbench to solve this problem in a
future release. Please contact your account representative if you have feedback or questions about this
workflow.

### PAM

When starting sessions on Workbench, PAM configuration is often very important, even if PAM is not being used as
an authentication mechanism. The Workbench Helm chart allows creating custom PAM files via the `config.pam`
values section.

Each key under `config.pam` becomes a PAM configuration file, and is mounted into `/etc/pam.d/` in the container. For
example:

```yaml
config:
  pam:
    rstudio: |
      # the rstudio PAM config file
      # will be used verbatim
    rstudio-session: |
      # the rstudio-session PAM config file
      # will be used verbatim
```

## RStudio profiles

Profiles are used to define product behavior (in `.ini` file format) based on user and group membership.

Sections define whether a set of configurations is applied to a user's jobs based on the following criteria:

- If section header is `[*]`, it applies to all users.
- If a user's username is `myusername`, the section `[myusername]` applies to them.
- If a user is in the `allusers` group, then the section `[@allusers]` applies to them

The product reads configuration from top to bottom and "last-in-wins" for a given configuration value.

### `/etc/rstudio/profiles`

The `/etc/rstudio/profiles` file enables you to tailor the behavior of sessions on a per-user or per-group basis. See the [Posit Workbench Administrator Guide - User and Group Profiles](https://docs.posit.co/ide/server-pro/rstudio_pro_sessions/user_and_group_profiles.html) page for more information.

In the `values.yaml`, define the content of `/etc/rstudio/profiles` in `config.server.profiles`. For example:

```yaml
config:
  server:
    profiles:
      "*":
        session-limit: 5
        session-timeout-minutes: 60
```

Becomes:

_/etc/rstudio/profiles_

```ini
[*]
session-limit=5
session-timeout-minutes=60
```

### `/etc/rstudio/launcher.kubernetes.profiles.conf`

The `/etc/rstudio/launcher.kubernetes.profiles.conf` contains the configuration of resource limits by user and group when using the Kubernetes Launcher Plugin. In the `values.yaml`, define the content of `/etc/rstudio/launcher.kubernetes.profiles.conf	` in the `config.profiles.launcher.kubernetes.profiles.conf` file. The `config.profiles` section has a couple of niceties that are added in by default.

- YAML arrays like the following becomes "comma-joined." For instance, the following becomes: `some-key=value1,value2`

  ```yaml
  some-key:
    - value1
    - value2
  ```

- The `[*]` section has arrays "appended" to user and group sections, along with "defaults" defined by the chart.

For example:

```yaml
config:
  profiles:
    launcher.kubernetes.profiles.conf:
      "*":
        some-key:
          - value1
          - value2
      myuser:
        some-key:
          - value4
          - value5
```

Becomes:

_/etc/rstudio/launcher.kubernetes.profiles.conf_

```ini
[*]
some-key: value1,value2
[myuser]
some-key: value1,value2,value3,value4
```

:::{.callout-note}
This appending/concatenation/array translation behavior only works with the helm chart.
:::

## Launcher Templates

If you want to customize the launcher job templates, use the `launcher.templateValues` section of the `values.yaml` file. These values are then used within session templates.

For example, if you want to add a container image registry credentials secret to allow session images to authenticate to a container registry, you can do so with the following:

```yaml
launcher:
  templateValues:
    pod:
      imagePullSecrets:
      - name: private-registry-creds
```

For example, if you want to add a toleration to each session, you can do so with the following:

```yaml
launcher:
  templateValues:
    pod:
      tolerations:
        - key: "posit-sessions"
          operator: "Exists"
          effect: "NoSchedule"
```

## Chronicle Agent

This chart supports use of a sidecar [Chronicle agent](https://docs.posit.co/chronicle/) to report data to a Chronicle server. The agent can be enabled
by setting `chronicleAgent.enabled=true`.

By default, the chart will attempt to lookup an existing Chronicle server deployed in the release namespace. The
searched namespace can be changed setting by `chronicleAgent.serverNamespace`. If a server exists, it will set the
Chronicle agent's server value to the server's service name and will use an agent version to match the server version.
This auto-discovery behavior can be disabled by setting `chronicleAgent.autoDiscovery=false`.

To set the server address and/or version manually, set the following values:
```yaml
chronicleAgent:
  enabled: true
  serverAddress: <server-address>
  image:
    tag: <agent-version>
```

If preferred, the Chronicle agent can be directly defined as a sidecar container using either `initContainers`
(recommended) or `sidecar` values. Below is an example of directly defining the Chronicle agent as a native sidecar
container using `initContainers`:
```yaml
initContainers:
  - name: chronicle-agent
    restartPolicy: Always
    image: ghcr.io/rstudio/chronicle-agent:<agent-version>
    env:
      - name: CHRONICLE_SERVER_ADDRESS
        value: "http://<address>"
```

For more information on Posit Chronicle, see the [Chronicle documentation](https://docs.posit.co/chronicle/).

### Chronicle Workbench API Key

> [!WARNING]
> The Workbench API is currently in preview. See
> [the Workbench documentation](https://docs.posit.co/ide/server-pro/admin/workbench_api/workbench_api.html) for more
> information.

The Chronicle agent can be configured to scrape the Workbench API for additional data. To do this, you must
provide the Chronicle agent with a Workbench API key. This can be done by setting `chronicleAgent.workbenchApiKey`:
```yaml
chronicleAgent:
  enabled: true
  workbenchApiKey:
    valueFrom:
      secretKeyRef:
        name: <secret-name>
        key: <key-name>
```

For additional information on enabling the API and generating API keys, see
[the Workbench documentation](https://docs.posit.co/ide/server-pro/admin/workbench_api/workbench_api.html).

## Using existing secrets

This chart supports referencing existing Kubernetes Secrets for sensitive configuration values.

**Note**: For database configuration, see the [Database](#database) section above for usage of `config.database.conf.existingSecret`.

### Using existing secrets for `launcher.pem` and `secureCookieKey`

Instead of having the chart generate and manage `launcher.pem` and `secureCookieKey`, you can reference existing Kubernetes Secrets:

```yaml
launcherPem:
  existingSecret: my-launcher-pem-secret  # Secret must have key: launcher.pem

secureCookieKey:
  existingSecret: my-cookie-key-secret    # Secret must have key: secure-cookie-key
```

When using `existingSecret`, the chart will **not** template these values into the chart-managed secret, avoiding duplication and ensuring the external secret is the single source of truth.

### Using existing secrets for arbitrary configurations

For other secret configuration files (like `openid-client-secret`), use `config.existingSecrets`:

```yaml
config:
  existingSecrets:
    - name: my-secret-name
      items:
        - key: openid-client-secret
          path: openid-client-secret
```

All files specified in `config.existingSecrets` are mounted to `/mnt/secret-configmap/rstudio/` with `0600` permissions, alongside any files defined in `config.secret`.

**Note**: `config.existingSecrets` and `config.secret` work together - you can use both simultaneously. Use `config.secret` for inline values and `config.existingSecrets` for externally managed secrets.

## Sealed secrets

This chart supports the use of [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) to allow for storing secrets in SCM and to ensure secrets are never leaked via Helm. The target cluster must include a `SealedSecret` controller as the controller is responsible for converting a `SealedSecret` to a `Secret`.

To activate the use of `SealedSecret` templates instead of `Secret` templates in the chart, set `sealedSecret.enabled=true` and ensure the following values are all encrypted (the chart does not support mixing encrypted values with unencrypted values):

- `config.secret`
- `config.sessionSecret`
- `config.userProvisioning`
- `launcherPem`
- `secureCookieKey` (or `global.secureCookieKey`)

Use of [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets) disables the chart's auto-generation and reuse capabilities for `launcherPem` and `secureCookieKey`. `launcherPem` is an RSA private key, which can be generated via an RSA tool such as Helm's [`genPrivateKey`](https://helm.sh/docs/chart_template_guide/function_list/#genprivatekey) function. `secureCookieKey` is typically a UUID, which can be generated via a UUID generator such as Helm's [`uuidv4`](https://helm.sh/docs/chart_template_guide/function_list/#uuid-functions) function.

{{ template "chart.valuesSection" . }}

{{ template "helm-docs.versionFooter" . }}