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. Both the connection URI and password may be specified in the `config` section of `values.yaml`. 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

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
```

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>"`

## 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 launched by Workbench, use `job-json-overrides`.
  - Review the [Job Json overrides](#job-json-overrides) section on this below. For general information, see [a support article](https://support.rstudio.com/hc/en-us/articles/360051652094-Using-Job-Json-Overrides-with-RStudio-Server-Pro-and-Kubernetes).
- 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.
- Workbench does not export prometheus metrics on its own. Instead, we run a sidecar graphite exporter.
  - This is described in the
  [Monitoring Posit Team Using Prometheus and Graphite](https://support.rstudio.com/hc/en-us/articles/360044800273-Monitoring-RStudio-Team-Using-Prometheus-and-Graphite) support article.

## 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`. To ensure `pip.conf` is mounted into the session pods, it is important that:

- `launcher.useTemplates: true` is set
- `pip.conf` settings are listed under `config.session` as shown in the following example for adding Posit Public Package Manager's PyPI:

  ```yaml
  launcher:
    useTemplates: true

  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.
:::

### Job Json overrides

If you want to customize the job launch process (i.e., how sessions are defined), edit the following configuration:

- Modify:
  ```yaml
  config.profiles.launcher\.kubernetes\.profiles\.conf.<< some selector >>.job-json-overrides`
  ```
- Create an array of maps with the following keys:
  - `target`: The "target" part of the job spec to replace.
  - `name`: A unique identifier (ideally with no spaces) becomes a configuration filename on disk.
  - `json`: A YAML value that is translated directly to JSON and injected into the job spec at `target`.

Explore the docs in the [Helm repository](https://github.com/rstudio/helm/blob/main/docs/customize.md) for additional information.

```yaml
config:
  profiles:
    launcher.kubernetes.profiles.conf:
      "*":
        job-json-overrides:
          - target: "/spec/template/spec/containers/0/imagePullPolicy"
            json: "Always"
            name: imagePullPolicy
          - target: "/spec/template/spec/imagePullSecrets"
            json:
              - name: my-pull-secret
            name: imagePullSecrets
        container-images:
          - "one-image:tag"
          - "two-image:tag
```

## 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" . }}