RustFS Helm Mode

RustFS helm chart supports standalone and distributed mode.

• Standalone mode: one pod with one PVC (single node, single disk).
• Distributed mode (default): multiple pods with multiple PVCs (multiple nodes, multiple disks).

Distributed topology

The distributed topology is defined by two parameters:

• replicaCount — number of pods (nodes) in the StatefulSet.
• drivesPerNode — number of data PVCs mounted on each pod.

Total drives in the cluster = replicaCount * drivesPerNode.

When drivesPerNode is left unset, the chart automatically infers a backward-compatible value from each pool's replica count (with pools disabled there is a single pool driven by the top-level replicaCount):

You can override the inference by setting drivesPerNode explicitly, e.g. --set drivesPerNode=2 for an 8×2 cluster.

IMPORTANT: Kubernetes does not allow changes to volumeClaimTemplates in an existing StatefulSet. If you want to change drivesPerNode after installation you must delete the StatefulSet (with --cascade=orphan to keep pods and PVCs) and recreate it, or perform a full reinstall.

Upgrade notes

Upgrading from chart versions that did not have drivesPerNode is safe without manual intervention:

• Existing 4×4 deployments (default replicaCount=4) continue to receive 4 drives per node because the chart infers drivesPerNode=4.
• Existing 16×1 deployments (replicaCount=16) continue to receive 1 drive per node because the chart infers drivesPerNode=1.

If you previously set replicaCount=16 and now want a different topology, set both replicaCount and drivesPerNode explicitly.

For distributed deployments that use the chart-generated RUSTFS_VOLUMES, localEndpointHost.autoInject defaults to automatic selection. Without secret.existingSecret, the chart injects a private Downward API variable, RUSTFS_CHART_POD_NAME, and uses it to build the pod's fully qualified hostname in RUSTFS_LOCAL_ENDPOINT_HOST. RustFS can then identify local drives without waiting for every peer's DNS record or TCP listener. A user-defined POD_NAME is preserved and does not interfere with the private chart variable. Setting RUSTFS_STARTUP_TOPOLOGY_WAIT_MODE explicitly to bounded, fail-fast, failfast, or strict also keeps legacy DNS-based locality discovery. A dynamically sourced wait mode keeps the legacy path because its value cannot be validated while rendering. Otherwise, Kubernetes auto-detection selects orchestrated startup when RustFS consumes the generated anchor.

An existing Secret is opaque to the chart and may historically contain more than credentials, so the chart does not inject an anchor whenever secret.existingSecret is set. In Kubernetes auto/orchestrated mode, RustFS then derives a DNS-free identity from the kernel hostname when exactly one domain endpoint at the server port has the same full hostname or first label. All-IP topologies retain direct IP locality detection. A domain topology with zero matches retains legacy DNS locality discovery; implicit auto mode bounds that compatibility path by RUSTFS_STARTUP_TOPOLOGY_WAIT_TIMEOUT (180 seconds by default). Multiple matching candidates remain an error. Set RUSTFS_LOCAL_ENDPOINT_HOST explicitly to avoid DNS discovery. For a credentials-only Secret, set localEndpointHost.autoInject=true to add the chart anchor without changing the historical ConfigMap-then-Secret envFrom precedence. If injection is explicitly enabled with an incompatible hidden RUSTFS_VOLUMES, RUSTFS_ADDRESS, or RUSTFS_STARTUP_TOPOLOGY_WAIT_MODE, RustFS also fails during endpoint construction; it does not silently fall back to a different topology.

When config.rustfs.volumes is set explicitly, the chart does not infer a local endpoint identity. RustFS applies the same kernel-hostname inference to custom domain topologies in Kubernetes auto/orchestrated mode; aliases that do not match the Pod hostname retain legacy DNS locality, with the bounded auto fallback described above. They may provide RUSTFS_LOCAL_ENDPOINT_HOST through extraEnv for DNS-free startup. An explicit RUSTFS_VOLUMES, explicit RUSTFS_LOCAL_ENDPOINT_HOST, bounded/dynamic or unrecognized startup mode, or localEndpointHost.autoInject=false, also disables chart injection. A RUSTFS_ADDRESS override alone does not disable it; the effective address and generated topology must agree on the endpoint port. Custom anchor-based configurations must resolve to orchestrated startup mode and must not receive a conflicting mode from an envFrom source. startupWaitTimeoutSeconds is retained for values-file compatibility but is deprecated and ignored. Historical RUSTFS_STARTUP_TOPOLOGY_RETRY_MAX_DELAY values of 0 or 0ms are replaced with the safe default retry cap instead of causing a busy loop or blocking a direct upgrade.

Upgrade the chart and RustFS image together. An older image that does not recognize RUSTFS_LOCAL_ENDPOINT_HOST retains its previous DNS-based startup behavior.

Parameters Overview

Scanner values map directly to scanner environment variables. For tuning workflow and /v3/scanner/status interpretation, see Scanner Runtime Controls. For repeatable scanner-pressure validation, see Scanner Benchmark Runbook.

NOTE:

The chart pulls the rustfs image from Docker Hub by default. For private registries, provide either:

• Existing secrets: Set imagePullSecrets with an array of secret names

  yamlCopy

  imagePullSecrets:
    - name: my-existing-secret
  

• Auto-generated secret: Enable imageRegistryCredentials.enabled: true and specify credentials plus your image details

  yamlCopy

  imageRegistryCredentials:
    enabled: true
    registry: myregistry.com
    username: myuser
    password: mypass
    email: [email protected]
  

Both approaches support pulling from private registries seamlessly and you can also combine them.

• The chart default pull rustfs image from dockerhub, if your rustfs image stores in private registry, you can use either existing image Pull secrets with parameter imagePullSecrets or create one setting imageRegistryCredentials.enabled to true,and then specify the imageRegistryCredentials.registry/username/password/email as well as image.rustfs.repository,image.rustfs.tag to pull rustfs image from your private registry.

• The default storageclass is local-path,if you want to specify your own storageclass, try to set parameter storageclass.name.

• The default size for data and logs dir is 256Mi which must satisfy the production usage,you should specify storageclass.dataStorageSize and storageclass.logStorageSize to change the size, for example, 1Ti for data and 1Gi for logs.

Server pools (capacity expansion)

In distributed mode the chart can run multiple server pools — independent StatefulSets whose drives together form one cluster, the same expansion model the RustFS server already supports via space-separated RUSTFS_VOLUMES expressions (rc admin pool ls / expand / rebalance / decommission).

With pools.enabled=false (default) the chart behaves exactly as before: one StatefulSet driven by the top-level replicaCount/storageclass.

To expand an existing deployment, enable pools and describe the current layout as pool 0 plus your new capacity:

pools:
  enabled: true
  list:
    - {}                  # pool 0: inherits top-level values and keeps the
                          # existing StatefulSet/pod/PVC names and data
    - replicaCount: 4     # pool 1: new capacity
      storageclass:
        dataStorageSize: 10Gi

Each entry may set replicaCount (>= 2) and/or a storageclass block; omitted fields inherit the top-level values. Additional pools render as <fullname>-pool<N> StatefulSets; all pools share the headless service, the main service, the configuration and the credentials.

Notes:

• Pools are append-only. The list index determines the StatefulSet name — never remove or reorder entries. Retire a pool with rc admin decommission before removing it from the list.
• With chart-generated volumes, each pod receives an explicit local endpoint identity. An unavailable peer no longer blocks a pod from reaching RustFS's own startup and quorum checks.
• After the cluster converges, run rc admin rebalance start <alias> to spread existing objects across the new pool.
• Pod anti-affinity in pool mode is scoped per pool and preferred (soft), not required: two pools can share nodes, and each pool's own pods spread across distinct nodes when capacity allows. Preferred affinity keeps additional pools schedulable when the cluster has fewer nodes than total pods. Single-pool deployments (pools.enabled=false) keep the chart's existing required anti-affinity unchanged.
• The PodDisruptionBudget spans all pools: with the default pdb.maxUnavailable: 1, at most one pod of the whole cluster may be evicted at a time. This is deliberately conservative — quorum safety matters across the union of all pools.

Installation

Requirement

• Helm V3
• The RustFS image from the same release as the chart. If image.rustfs.tag is overridden, that image must support RUSTFS_LOCAL_ENDPOINT_HOST.

Due to the traefik and ingress has different session sticky/affinity annotations, and rustfs support both those two controller, you should specify parameter ingress.className to select the right one which suits for you.

Installation with traefik controller

If your ingress class is traefik, running the command:

helm install rustfs -n rustfs --create-namespace ./ --set ingress.className="traefik"

Installation with nginx controller

If your ingress class is nginx, running the command:

helm install rustfs -n rustfs --create-namespace ./ --set ingress.className="nginx"

Installation check and rustfs login

Check the pod status

kubectl -n rustfs get pods -w
NAME       READY   STATUS    RESTARTS        AGE
rustfs-0   1/1     Running   0               2m27s
rustfs-1   1/1     Running   0               2m27s
rustfs-2   1/1     Running   0               2m27s
rustfs-3   1/1     Running   0               2m27s

Check the ingress status

kubectl -n rustfs get ing
NAME     CLASS   HOSTS            ADDRESS         PORTS     AGE
rustfs   nginx   example.rustfs.com   10.43.237.152   80, 443   29m

Access the rustfs cluster via https://example.rustfs.com with the default username and password rustfsadmin.

Replace the example.rustfs.com with your own domain as well as the certificates.

TLS configuration

By default, tls is not enabled. If you want to enable tls(recommendated),you can follow below steps:

• Step 1: Certification generation

You can request cert and key from CA or use the self-signed cert(not recommendated on prod), and put those two files(eg, tls.crt and tls.key) under some directory on server, for example tls directory.

• Step 2: Certification specifying

You should use --set-file parameter when running helm install command, for example, running the below command can enable ingress tls and generate tls secret:

helm install rustfs rustfs/rustfs -n rustfs --set tls.enabled=true,--set-file tls.crt=./tls.crt,--set-file tls.key=./tls.key

Gateway API support (alpha)

Due to ingress nginx retirement in March 2026, so RustFS adds support for gateway api. Currently, RustFS only supports traefik as gateway class, more and more gateway class support will be added in the future after those classes are tested. If you want to enable gateway api, specify gatewayApi.enabled to true while specify ingress.enabled to false. After installation, you can find the Gateway and HttpRoute resources,

$ kubectl -n rustfs get gateway
NAME             CLASS     ADDRESS   PROGRAMMED   AGE
rustfs-gateway   traefik             True         169m

$ kubectl -n rustfs get httproute
NAME           HOSTNAMES            AGE
rustfs-route   ["example.rustfs.com"]   172m

Then, via RustFS instance via https://example.rustfs.com or http://example.rustfs.com.

Uninstall

Uninstalling the rustfs installation with command,

helm uninstall rustfs -n rustfs