README.md.gotmpl

{{ template "rstudio.header" . }}

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

{{ template "rstudio.description" . }}

{{ template "rstudio.disclaimer" . }}

{{ template "rstudio.install" . }}

## Usage

This chart deploys the Chronicle server and is intended to be used in tandem
with the Workbench and Connect charts. For the server to receive data,
the Chronicle agent must be deployed as a sidecar container alongside
Workbench or Connect server pods.

Both [Workbench](https://docs.posit.co/helm/charts/rstudio-workbench/README.html#chronicle-agent)
(`>=0.9.2`) and [Connect](https://docs.posit.co/helm/charts/rstudio-connect/README.html#chronicle-agent)
(`>=0.7.26`) charts include out of the box support for Chronicle agent sidecars.
The sidecar can be enabled by setting the `chronicleAgent.enabled` value to `true`
in either product's chart.

For additional information on deploying and configuring Chronicle agents,
see the [Workbench](https://docs.posit.co/helm/charts/rstudio-workbench/README.html#chronicle-agent)
or [Connect](https://docs.posit.co/helm/charts/rstudio-connect/README.html#chronicle-agent)
chart documentation.

## HTTPS Configuration

Chronicle can be configured to use HTTPS for secure communication. The
`config.HTTPS` section of the configuration allows you to specify the certificate
and key files to use for HTTPS. Both `config.HTTPS.Certificate` and
`config.HTTPS.Key` are expected to be paths to files accessible by Chronicle.
The `extraSecretMounts` value can be used to mount the certificate and key files
into the Chronicle pod. Here is an example of how to do this, assuming that
the certificate and key files are stored together in a Kubernetes TLS secret:

```yaml
extraSecretMounts:
  - name: chronicle-https
    mountPath: /etc/chronicle/ssl
    secretName: chronicle-https
    items:
      - key: tls.crt
      - key: tls.key
config:
  HTTPS:
    Enabled: true
    Certificate: "/etc/chronicle/ssl/tls.crt"
    Key: "/etc/chronicle/ssl/tls.key"
```

## Storage Configuration

Chronicle can be configured to persist data to local storage, AWS S3, or both.

### Local Storage

The default configuration will save data to a persistent volume, which
is suitable if you'd like to access and analyze the data within your cluster.
The below values show the default configuration for storage:

```yaml
persistence:
  enabled: true
  accessModes:
    - ReadWriteOnce
  size: 10Gi
config:
  LocalStorage:
    Enabled: true
    Location: "/opt/chronicle-data"
```

The `persistence` section configures the persistent volume claim in the
cluster while the `config.LocalStorage` section directly applies to Chronicle's
configuration file. The persistent volume will always mount to the path specified
by `config.LocalStorage.Path` to avoid potential misconfiguration and data loss.

By default, Chronicle requests 10Gi of storage. In most cases, this amount of
storage should be sufficient for thirty days of monitoring data.

::: {.callout-important}
Users are responsible for managing the size of the persistent volume, retention
of stored data, and controlling access to the data from other pods. Consider
utilizing a dynamic volume provisioner to avoid storage-related service
interruptions.
:::

While attaching the volume to Workbench is a valid method of accessing the data,
keep in mind that some data captured by Chronicle may be considered sensitive and
should be handled with care.

#### Alternate Storage Class

Depending on the environment or cloud hosting Chronicle, many CSI drivers may
be available to use as the persistent volume's storage class. While Chronicle
only natively supports local storage or S3, CSI drivers may be used to provide
support for other storage backends such as Azure Blob Storage, Azure Files, Google
Cloud Storage, or other object storage solutions. The storage class for persistent
volumes can be set with the following value:

```yaml
persistence:
  storageClass: "alternate-storage-class"
```

Please report and performance or stability issues with alternate storage configurations
to the [issue tracker](https://github.com/rstudio/helm/issues/new?template=chronicle.md).

### S3 Storage

Chronicle can also be configured to store data in an S3 bucket. This can be
useful for controlling access to data or taking advantage of S3 features
such as lifecycle management.

```yaml
config:
  S3Storage:
    Enabled: true
    Bucket: "posit-chronicle"
    Region: "us-east-2"
```

#### Using IAM roles for S3 access

If Chronicle is running on EKS, [IAM Roles for Service
Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
can be utilized to manage the credentials needed to access S3. Once [an IAM role has been
created](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html),
the role can be attached as an annotation on Chronicle's Service Account:

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

There are alternatives for injecting AWS credentials into a container. As a fallback,
the S3 storage config allows specifying a profile:

```yaml
config:
  S3Storage:
    Enabled: true
    Bucket: "posit-chronicle"
    Profile: "my-aws-account"
    Region: "us-east-2"
```

#### Needed S3 Policy Permissions

The credentials Chronicle uses for S3 storage must have the following permissions enabled:

- `s3:GetObject`
- `s3:ListBucket`
- `s3:PutObject`
- `s3:DeleteObject`

## Additional Configuration

Chronicle has additional configuration options not specifically mentioned in this
README. For additional information on administrating or using Posit Chronicle, see
the [Chronicle documentation](https://docs.posit.co/chronicle/).

For details on server configuration options, see the [advanced server configuration
reference page](https://docs.posit.co/chronicle/appendix/library/advanced-server.html).

{{ template "chart.valuesSection" . }}

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