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

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