Skip to main content

RustFS

Overview​

RustFS is an Apache-2.0 S3-compatible object store written in Rust, bundled with Ilum as a sub-chart of helm_aio. The upstream chart is published at https://charts.rustfs.com.

In the 6.7.x line RustFS ships bundled but disabled (rustfs.enabled=false); MinIO remains the default provider. RustFS is planned to become the default object storage backend in 6.8.0. Until then it is enabled explicitly, as shown below.

PropertyValue
LicenseApache-2.0
Status in IlumBundled, opt-in (planned default in 6.8.0)
Bundled chartRustFS chart 0.0.99 (upstream app version 1.0.0-alpha.99)
Bundled imageilum/rustfs:1.0.0-beta.1 (custom build, see below)
Default in helm_aioDisabled (rustfs.enabled=false)
Distributed modeAvailable upstream but marked "under testing"; the bundled defaults configure standalone mode with a single PersistentVolumeClaim
Console UXEmbedded same-origin iframe at /rustfs/console/
OIDC integrationOperator-supplied via rustfs.extraEnv; not auto-wired

When to use RustFS​

  • New Ilum installs that want the project's current default.
  • Existing MinIO installs that want to move to a permissively licensed storage layer (Apache-2.0 vs the MinIO server's AGPL-3.0).
  • Deployments that benefit from a smaller, Rust-based footprint at modest scale.

Enable RustFS as the active provider​

In the 6.7.x line MinIO is enabled by default, so RustFS must be turned on explicitly. On a net-new installation, enable RustFS and disable MinIO:

helm install ilum ilum/helm_aio \
  --set rustfs.enabled=true \
  --set minio.enabled=false

On an existing MinIO install, follow the migration playbook in Migrate Between Providers. The playbook keeps MinIO running side by side until the operator explicitly acknowledges the cutover.

Planned default change

From 6.8.0, RustFS is planned to become the default provider (rustfs.enabled=true, minio.enabled=false). On 6.8.0 and later, a net-new install will select RustFS with no flags. The instructions above apply to the 6.7.x line.

Why Ilum ships a custom image​

The upstream RustFS console hardcodes its admin and S3 API endpoints to the host root. Embedding it in the Ilum UI as a same-origin iframe would collide with the Ilum SPA routes at /. The bundled ilum/rustfs:1.0.0-beta.1 image carries a patched console built with NEXT_PUBLIC_API_PREFIX=/rustfs/api. The patched build sends every S3 and admin request through /rustfs/api/... and strips the prefix from the SigV4 canonical string before signing. The Ilum UI's nginx reverse proxy then strips /rustfs/api/ and forwards the un-prefixed request to the RustFS server, which verifies the signature against the same un-prefixed path.

The patch is being upstreamed to github.com/rustfs/console. Once the upstream tag includes the NEXT_PUBLIC_API_PREFIX knob, Ilum will switch back to the stock upstream image.

The image build pipeline lives in ops/docker/ilum-rustfs/ in the Ilum monorepo.

Registry entry​

The chart ships the following registry defaults for RustFS:

objectStorage:
  providers:
    rustfs:
      consolePath: /rustfs/console/
      consoleMode: same-origin

The consoleMode: same-origin instructs the Ilum UI to load the console iframe directly at /rustfs/console/ rather than rewriting the path. The patched console assets resolve relative to that base path.

Credentials​

RustFS root credentials are sourced from the shared ilum-objectstorage-credentials Secret, not from the rustfs.secret block. The chart sets rustfs.secret.existingSecret: ilum-objectstorage-credentials, which exposes the credentials to the RustFS Pod as the RUSTFS_ACCESS_KEY / RUSTFS_SECRET_KEY environment variables.

The default credentials for a net-new install are:

FieldDefault
Access key (admin user)admin
Secret key (admin password)admin12345

These are the credentials used both for the embedded admin console at /rustfs/console/ and for S3 API access. They are defined once in the chart under objectStorage.credentials (accessKey / secretKey).

Ignore the rustfs.secret.rustfs literals

The rustfs.secret.rustfs.access_key / secret_key values in values.yaml (shipped as admin / admin) are ignored whenever rustfs.secret.existingSecret is set, which is the bundled default. They are consulted only for standalone RustFS chart installs that bypass helm_aio. The active console and S3 credentials are always the objectStorage.credentials pair above (admin / admin12345).

The secret key default is 10 characters because the bundled mc client rejects secret keys shorter than 8 characters; operators overriding it must keep it at 8 or more. To rotate credentials, edit the shared Secret and restart the consuming Pods as described in Rotate Object Storage Credentials.

Prometheus metrics​

RustFS observability is in active development at the time of this writing. The upstream rustfs-obs crate ships OpenTelemetry-based metrics, logs, and traces. A stable /metrics Prometheus-format endpoint has not yet been documented in the upstream README, and community issues (rustfs/rustfs#796, rustfs/rustfs#1228) track the work.

Until the upstream endpoint stabilizes, operators that need Prometheus-format RustFS metrics today should run the upstream's OTel collector reference stack (Grafana, Prometheus, and Jaeger) from the RustFS project's docker-compose.yml. Configure the RUSTFS_OBS_ENDPOINT environment variable in rustfs.extraEnv to point at the collector. This integration is operator-driven; Ilum does not wire it automatically.

For Loki log shipping from the Ilum core services (which write to the ilum-files bucket on whichever provider is active), refer to the existing observability documentation. The log path is provider-agnostic.

Known limitations​

  • Alpha upstream status. The bundled RustFS chart 0.0.99 advertises app version 1.0.0-alpha.99. Distributed mode is marked "under testing" in the upstream README. The bundled defaults run in standalone mode with a single replica and a single PVC.
  • No Hydra OIDC auto-wiring in 6.7.2-RC2. Operators that need OIDC against the RustFS console must supply the integration through rustfs.extraEnv directly. The integration will stabilize in a future release.
  • Patched console fork. Until the upstream NEXT_PUBLIC_API_PREFIX patch lands, Ilum pins a custom image. The fork is small (under 50 lines across five files plus one new file) and tracked in ops/docker/ilum-rustfs/README.md.

Disable RustFS​

To roll back to MinIO or to disable RustFS in favour of an external S3 provider, set rustfs.enabled=false. The pre-upgrade hook detects existing RustFS PersistentVolumeClaims and refuses to proceed if disabling RustFS would orphan data. Follow Migrate Between Providers to disable RustFS safely.

Reference​

Last updated on