Kubernetes
Ricochet runs on amd64, arm64, and mixed Kubernetes clusters.
The Helm chart installs one ricochet-server replica and the service account and RBAC it uses to launch workloads.
It can also add persistent storage and ingress.
Prerequisites
Section titled “Prerequisites”Before you install Ricochet, set up:
- Kubernetes 1.27 or newer
- Helm 3.8 or newer with OCI registry support
- An OIDC client for the public Ricochet URL
- A default
ReadWriteOncestorage class for the server home volume - A
ReadWriteManystorage class for shared content and dependency caches - An ingress controller and TLS certificate issuer if the chart exposes Ricochet
Install
Section titled “Install”-
Create a namespace:
Terminal window kubectl create namespace ricochet -
Store the OIDC credentials in a Secret:
Terminal window kubectl --namespace ricochet create secret generic ricochet-oidc \--from-literal=RICOCHET_AUTH__OIDC__CLIENT_ID='your-client-id' \--from-literal=RICOCHET_AUTH__OIDC__CLIENT_SECRET='your-client-secret' -
Save the following configuration as
values.yaml:values.yaml replicaCount: 1envFrom:- secretRef:name: ricochet-oidcconfig:"auth.oidc":issuer_url: "https://your-idp.example.com/"redirect_url: "https://ricochet.example.com/oauth/callback"persistence:home:enabled: truesize: 25Giapps:deployment:persistence:content:enabled: truestorageClass: "rwx-storage"accessMode: ReadWriteManysize: 20Gicache:enabled: truestorageClass: "rwx-storage"accessMode: ReadWriteManysize: 20Giingress:enabled: trueclassName: nginxannotations:cert-manager.io/cluster-issuer: letsencrypt-prodhosts:- host: ricochet.example.compaths:- path: /pathType: Prefixtls:- secretName: ricochet-tlshosts:- ricochet.example.comresources:requests:cpu: 250mmemory: 512Milimits:memory: 2GiReplace the example host names, ingress class, certificate issuer, and
rwx-storagestorage class with your own. If TLS ends outside Kubernetes, disableingressand expose the chart’sClusterIPservice through your gateway. -
Install the latest chart:
Terminal window helm install ricochet oci://ghcr.io/ricochet-rs/ricochet-helm \--namespace ricochet \--values values.yamlThe chart version is separate from the
ricochet-serverversion. Check the chart’sappVersionbefore you upgrade:Terminal window helm show chart oci://ghcr.io/ricochet-rs/ricochet-helm -
Wait for Ricochet to become ready:
Terminal window kubectl --namespace ricochet rollout status deployment/ricochetkubectl --namespace ricochet get pods,pvc,ingress
Persistence
Section titled “Persistence”The example creates three volumes:
| Volume | Default mount path | Access mode | Purpose |
|---|---|---|---|
| Home | /var/lib/ricochet/data |
ReadWriteOnce |
Database, keys, config, logs, and server state |
| Content | /var/lib/ricochet/data/content |
ReadWriteMany |
Deployment bundles shared with app and task workloads |
| Cache | /var/lib/ricochet/data/.cache |
ReadWriteMany |
R, Python, and Julia package caches shared by all workloads |
Back up the home and content volumes together. You can recreate the cache volume, but then later deployments restore their dependencies again.
The chart disables persistence by default.
Running helm install without values creates a throwaway install, so use it only for testing.
Multi-architecture clusters
Section titled “Multi-architecture clusters”Ricochet can restore dependencies for both amd64 and arm64 nodes. Add this value so the server can find each node’s architecture:
rbac: clusterRole: enabled: trueThis grants a cluster-wide permission to list nodes. On clusters with one architecture, you can leave it off to avoid granting that permission.
Architecture
Section titled “Architecture”The ricochet-server creates Kubernetes resources for deployed content:
- Each app runs as a Kubernetes Deployment.
- Each task invocation runs as a Kubernetes Job.
- Dependency restore runs in a separate Job before the deployment goes live.
When an app starts, an init container checks that its dependencies exist for the node’s architecture. If they are missing, the init container restores them before the app starts.
App scaling
Section titled “App scaling”Ricochet scales each app with the settings in its _ricochet.toml:
min_instancessets the minimum replicas.max_instancessets the maximum replicas.spawn_thresholdsets the percent of used connections that adds a replica.max_connectionssets the connection capacity of each replica.max_connection_agesets the longest a connection can last.inactive_timeoutsets how long an idle replica stays up.
Custom deployment configuration
Section titled “Custom deployment configuration”Admins can let content owners extend the Kubernetes deployment spec for a single app. This is off by default, because custom pod settings can weaken cluster security.
Turn it on only if you trust your content owners:
config: launcher: allow_custom_k8s_config: trueDo not override imagePullPolicy, imagePullSecrets, or strategy per app, because the chart sets those fields for the whole instance.
Upgrade
Section titled “Upgrade”Review the new chart’s values and appVersion, then reuse your install values:
helm upgrade ricochet oci://ghcr.io/ricochet-rs/ricochet-helm \ --namespace ricochet \ --values values.yamlBack up persistent data before upgrading.