DEV Community

giveitatry
giveitatry

Posted on

Deploying RustFS (Single Node) on k3s

#rustfs #kubernetes

RustFS is an S3-compatible object storage system designed for high performance and distributed environments. For development, testing, or edge deployments, it can be run in standalone mode (single node, single disk).

This guide covers:

  • Helm-based installation
  • Correct credential configuration
  • Optional ingress exposure
  • Verification steps
  • Troubleshooting common issues

1. Prerequisites

Ensure the following:

  • Running k3s cluster
  • kubectl configured
  • Helm installed

Check cluster:

kubectl get nodes
Enter fullscreen mode Exit fullscreen mode

2. Add RustFS Helm repository 

helm repo add rustfs https://charts.rustfs.com
helm repo update
Enter fullscreen mode Exit fullscreen mode

3. Create namespace 

kubectl create namespace rustfs
Enter fullscreen mode Exit fullscreen mode

4. Prepare values.yaml

This is the recommended configuration for single-node deployment.

mode:
  standalone:
    enabled: true
  distributed:
    enabled: false

replicaCount: 1

image:
  repository: rustfs/rustfs
  tag: latest

storageclass:
  name: local-path

secret:
  rustfs:
    access_key: admin
    secret_key: supersecretpassword

ingress:
  enabled: false

tls:
  enabled: false
Enter fullscreen mode Exit fullscreen mode

5. Install RustFS 

helm install rustfs rustfs/rustfs \
  -n rustfs \
  -f values.yaml
Enter fullscreen mode Exit fullscreen mode

6. Verify deployment

Check pods:

kubectl get pods -n rustfs
Enter fullscreen mode Exit fullscreen mode

Expected:

rustfs-0   Running
Enter fullscreen mode Exit fullscreen mode

7. Access RustFS

Option A: Port-forward (recommended) 

kubectl port-forward svc/rustfs-svc 9000:9000 -n rustfs
Enter fullscreen mode Exit fullscreen mode

Then:

Option B: Enable ingress (optional)

Update values.yaml:

ingress:
  enabled: true
  className: traefik
  hosts:
    - host: rustfs.127.0.0.1.nip.io
      paths:
        - path: /
          pathType: Prefix
Enter fullscreen mode Exit fullscreen mode

Apply:

helm upgrade rustfs rustfs/rustfs -n rustfs -f values.yaml
Enter fullscreen mode Exit fullscreen mode

8. Login

Default credentials (as configured):

  • Username: admin
  • Password: supersecretpassword

Access the web console on port 9001.

9. Key Configuration Notes

Standalone vs Distributed

  • standalone = single pod, one volume
  • distributed = multiple pods, erasure coding

Do not mix both modes.

Credentials

RustFS Helm chart uses:

secret.rustfs.access_key
secret.rustfs.secret_key
Enter fullscreen mode Exit fullscreen mode

Not:

auth.*
Enter fullscreen mode Exit fullscreen mode

Storage

Default:

storageclass.name: local-path
Enter fullscreen mode Exit fullscreen mode

Suitable for k3s environments.

10. Troubleshooting

1. Login does not work

Cause:

  • Wrong Helm keys used (auth.* instead of secret.rustfs.*)
  • Secret not updated

Fix:

kubectl get secret -n rustfs
kubectl delete secret <secret-name> -n rustfs
helm upgrade rustfs rustfs/rustfs -n rustfs -f values.yaml
Enter fullscreen mode Exit fullscreen mode

2. Pods fail with "not first disk" or quorum errors

Cause:

  • Distributed mode enabled unintentionally
  • Invalid cluster topology

Fix:

Ensure:

mode:
  standalone:
    enabled: true
  distributed:
    enabled: false
Enter fullscreen mode Exit fullscreen mode

3. TCP connection errors between nodes

Cause:

  • Port mismatch (9000 vs 9001)
  • Incorrect service configuration

Fix:

  • Ensure consistent port usage
  • Verify endpoints: 
kubectl get endpoints -n rustfs
Enter fullscreen mode Exit fullscreen mode

4. Ingress fails with validation error

Error:

spec.rules[0].http.paths: Required value
Enter fullscreen mode Exit fullscreen mode

Cause:

  • Missing paths definition

Fix:

paths:
  - path: /
    pathType: Prefix
Enter fullscreen mode Exit fullscreen mode

5. Ingress not reachable

Cause:

  • Missing ingress controller
  • Wrong class name

Fix:

For k3s:

ingress:
  className: traefik
Enter fullscreen mode Exit fullscreen mode

6. Cannot access service externally

Cause:

  • Using ClusterIP without port-forward

Fix:

kubectl port-forward svc/rustfs-svc 9000:9000 -n rustfs
Enter fullscreen mode Exit fullscreen mode

7. Credentials do not change after upgrade

Cause:

  • Kubernetes Secret not overwritten

Fix:

kubectl delete secret <secret-name> -n rustfs
helm upgrade ...
Enter fullscreen mode Exit fullscreen mode

Conclusion

Running RustFS in standalone mode on k3s is straightforward when:

  • Helm values are correctly defined
  • Secrets use the correct keys
  • Distributed mode is disabled

This setup provides a lightweight, S3-compatible storage backend suitable for development and edge use cases, while preserving a clear upgrade path to distributed deployments.

Top comments (0)