README.md.gotmpl

{{ template "rstudio.header" . }}

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

{{ template "rstudio.description" . }}

{{ template "rstudio.disclaimer" . }}

{{ template "rstudio.install" . }}

## Upgrade guidance

### 0.4.0

- When upgrading to version 0.4.0 or later, the Package Manager service moves from running as `root` to running as
  the `rstudio-pm` user (with `uid:gid` `999:999`).
- A `chown` of persistent storage may be required. The team is working to implement an automatic fix. To disable the automatic fix/hook, set `enableMigrations=false`.

## Required configuration

This chart requires the following in order to function:

* 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 data directory for Package Manager.
  * If `sharedStorage.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 you disable `sharedStorage.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 `sharedStorage.name` and `sharedStorage.mount`.
  * If you cannot use a `PersistentVolume` to properly mount your data directory, mount your data in the container
    by using a regular [Kubernetes Volume](https://kubernetes.io/docs/concepts/storage/volumes), specified in `pod.volumes` and `pod.volumeMounts`.
  * Alternatively, S3 storage can be used. See the [S3 Configuration](#s3-configuration) section for details.

{{ template "rstudio.licensing" . }}

## Database

Package Manager requires a PostgreSQL database when running in Kubernetes. You must configure a [valid connection URI and a password](https://docs.posit.co/rspm/admin/database/#database-postgres) 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 `URL` with your database details.

```yaml
config:
  Database:
    Provider: "postgres"
  Postgres:
    URL: "postgres://<USERNAME>@<HOST>:<PORT>/<DATABASE>"
```

### 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: PACKAGEMANAGER_POSTGRES_PASSWORD
      valueFrom:
        secretKeyRef:
          name: {{ .Name }}-database
          key: password

    # Temporarily work around bug in Package Manager 2024.08.2 where Postgres.UsageDataPassword
    # does not default to Postgres.Password. This will be fixed in the next release of Package Manager.
    - name: PACKAGEMANAGER_POSTGRES_USAGEDATAPASSWORD
      valueFrom:
        secretKeyRef:
          name: {{ .Name }}-database
          key: password
```

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

`--set config.Postgres.Password="<YOUR_PASSWORD_HERE>"`

## S3 configuration

Package Manager [can be configured to store its data in S3
buckets](https://docs.posit.co/rspm/admin/file-storage/file-storage/#data-destinations),
which eliminates the need to provision shared storage for multiple replicas. A
`values.yaml` file using S3 might contain something like the following:

``` yaml
config:
  Storage:
    Default: s3
  S3Storage:
    Bucket: your-s3-bucket
```

If you are running on EKS, we strongly suggest using [IAM Roles for Service
Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
to manage the credentials needed to access S3. In this scenario, once you have
[created an IAM
role](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html),
you can use this role as an annotation on the existing Service Account:

``` yaml
serviceAccount:
  create: true
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789000:role/iam-role-name-here
```

If you are unable to use IAM Roles for Service Accounts, there are any number of
alternatives for injecting AWS credentials into a container. As a fallback, the
chart supports setting static credentials:

``` yaml
awsAccessKeyId: your-access-key-id
awsSecretAccessKey: your-secret-access-key
```

Bear in mind that static, long-lived credentials are the least secure option and
should be avoided if at all possible.

## General principles

- In most places, we opt to pass Helm values over configmaps. We translate these into the valid `.gcfg` file format
required by {{ template "chart.name" . }}.

## Configuration file

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

```{.bash}
... --set config.Postgres.Password=mypassword ...
```

The Helm `config` values are converted into the `rstudio-pm.gcfg` service configuration file via go-templating.

{{ template "chart.valuesSection" . }}

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