Skip to content
ricochet

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.

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 ReadWriteOnce storage class for the server home volume
  • A ReadWriteMany storage class for shared content and dependency caches
  • An ingress controller and TLS certificate issuer if the chart exposes Ricochet
  1. Create a namespace:

    Terminal window
    kubectl create namespace ricochet
  2. 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'
  3. Save the following configuration as values.yaml:

    values.yaml
    replicaCount: 1
    envFrom:
    - secretRef:
    name: ricochet-oidc
    config:
    "auth.oidc":
    issuer_url: "https://your-idp.example.com/"
    redirect_url: "https://ricochet.example.com/oauth/callback"
    persistence:
    home:
    enabled: true
    size: 25Gi
    apps:
    deployment:
    persistence:
    content:
    enabled: true
    storageClass: "rwx-storage"
    accessMode: ReadWriteMany
    size: 20Gi
    cache:
    enabled: true
    storageClass: "rwx-storage"
    accessMode: ReadWriteMany
    size: 20Gi
    ingress:
    enabled: true
    className: nginx
    annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
    - host: ricochet.example.com
    paths:
    - path: /
    pathType: Prefix
    tls:
    - secretName: ricochet-tls
    hosts:
    - ricochet.example.com
    resources:
    requests:
    cpu: 250m
    memory: 512Mi
    limits:
    memory: 2Gi

    Replace the example host names, ingress class, certificate issuer, and rwx-storage storage class with your own. If TLS ends outside Kubernetes, disable ingress and expose the chart’s ClusterIP service through your gateway.

  4. Install the latest chart:

    Terminal window
    helm install ricochet oci://ghcr.io/ricochet-rs/ricochet-helm \
    --namespace ricochet \
    --values values.yaml

    The chart version is separate from the ricochet-server version. Check the chart’s appVersion before you upgrade:

    Terminal window
    helm show chart oci://ghcr.io/ricochet-rs/ricochet-helm
  5. Wait for Ricochet to become ready:

    Terminal window
    kubectl --namespace ricochet rollout status deployment/ricochet
    kubectl --namespace ricochet get pods,pvc,ingress

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.

Ricochet can restore dependencies for both amd64 and arm64 nodes. Add this value so the server can find each node’s architecture:

values.yaml
rbac:
clusterRole:
enabled: true

This grants a cluster-wide permission to list nodes. On clusters with one architecture, you can leave it off to avoid granting that permission.

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.

Ricochet scales each app with the settings in its _ricochet.toml:

  • min_instances sets the minimum replicas.
  • max_instances sets the maximum replicas.
  • spawn_threshold sets the percent of used connections that adds a replica.
  • max_connections sets the connection capacity of each replica.
  • max_connection_age sets the longest a connection can last.
  • inactive_timeout sets how long an idle replica stays up.

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:

values.yaml
config:
launcher:
allow_custom_k8s_config: true

Do not override imagePullPolicy, imagePullSecrets, or strategy per app, because the chart sets those fields for the whole instance.

Review the new chart’s values and appVersion, then reuse your install values:

Terminal window
helm upgrade ricochet oci://ghcr.io/ricochet-rs/ricochet-helm \
--namespace ricochet \
--values values.yaml

Back up persistent data before upgrading.