mapfs-csi Kubernetes Deployment

This directory contains everything needed to deploy mapfs-csi (a CSI driver
for object storage) to a Kubernetes cluster.

Two separate concerns, don't confuse them:

  • Installing the driver (once per cluster, no cloud/bucket knowledge needed) —
    a Helm chart.
  • Configuring a storage backend (repeat for every bucket/cloud you want
    to use — a single driver install can serve many of these at once) —
    plain YAML templates, applied with kubectl apply -f.

Download the storage-backend templates

$ wget https://mapfs.cloud/dist/mapfs-csi-manifests-2.3.tar.gz
$ tar xzf mapfs-csi-manifests-2.3.tar.gz && cd mapfs-csi-manifests

This archive contains the Phase 2 templates (cloud-secret.yaml,
storageclass.yaml), the eks/ and example/ directories — everything
except the driver itself, which is installed via Helm (see Phase 1 below).

Directory layout

mapfs-csi-manifests/
├── cloud-secret.yaml            # Cloud credentials Secret template (Phase 2)
├── storageclass.yaml            # StorageClass template for dynamic provisioning (Phase 2)
│
├── eks/                         # AWS EKS examples (arm64 nodes)
│   ├── storageclass.yaml        # Example pointed at real AWS S3
│   ├── cloud-secret.yaml
│   ├── test-pods.yaml           # Advanced example: verify cross-node RWX mounting
│   └── test-pod-same-node.yaml  # Advanced example: verify same-node mount reuse
│
└── example/                     # Usage examples, not required for installation
    ├── pv.yaml / pvc.yaml              # Generic static-provisioning template (S3, etc.)
    ├── azure-pv.yaml / azure-storageclass.yaml  # Azure Blob Storage example
    └── minio-*.yaml                    # Self-hosted MinIO (S3-compatible) static/dynamic examples

Prerequisites

  • A Kubernetes cluster with kubectl and helm (v3+) configured against it
  • A valid mapfs license (email + token, from https://mapfs.cloud/)
  • Access credentials for your target cloud storage (access_key/secret_key,
    or an Azure connectionString)
  • An existing bucket / container

Quick start (generic S3-compatible cloud)

Phase 1: Install the driver

This is a one-time, per-cluster step. It doesn't need any cloud/bucket
information — just your mapfs license.

  1. Install the chart:

    helm install mapfs-csi oci://registry-1.docker.io/wyflow/mapfs-csi-chart --version 2.3 \
  --set license.email=you@example.com \
  --set license.token=<token-from-mapfs-portal>

    On AWS EKS with Graviton (arm64) nodes, also add:

      --set nodeSelector."kubernetes\.io/arch"=arm64

  2. Check status:

    kubectl -n kube-system get pod -l app=mapfs-csi-controller
kubectl -n kube-system get pod -l app=mapfs-csi-node

To upgrade to a newer version later:

helm upgrade mapfs-csi oci://registry-1.docker.io/wyflow/mapfs-csi-chart --version <new-version>

Phase 2: Configure a storage backend

Repeat this phase for every bucket/cloud you want to expose to the
cluster — it's independent of Phase 1, and doesn't require reinstalling or
upgrading the driver.

  1. Create the cloud credentials Secret:

    kubectl create secret generic mapfs-cloud-creds -n kube-system \
  --from-literal=access_key=<AccessKeyID> \
  --from-literal=secret_key=<SecretAccessKey>

    For Azure Blob Storage, use connectionString instead of the two fields
    above — see the comments in cloud-secret.yaml.

  2. Edit storageclass.yaml and fill in at least cloud and bucket (some
    clouds also need region/endpoint/accountId/ociNamespace — see the
    comments in the file for details), then apply it:

    kubectl apply -f storageclass.yaml

Usage examples

Dynamic provisioning (recommended)

Once storageclass.yaml is applied, just create a PVC — the PV is created
automatically by csi-provisioner:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes: ["ReadWriteMany"]
  resources:
    requests:
      storage: 1Ti
  storageClassName: mapfs-s3   # must match metadata.name in storageclass.yaml

Static provisioning

To point at an existing bucket/volume manually instead of using dynamic
provisioning, start from example/pv.yaml + example/pvc.yaml: replace the
placeholders __PV_NAME__, __VOLUME_NAME__, __CLOUD__,
__BUCKET_NAME__, etc. with real values, then kubectl apply -f.

Azure Blob Storage

Use example/azure-pv.yaml (static) or example/azure-storageclass.yaml
(dynamic) instead of the S3 versions — credentials use connectionString
instead of access_key/secret_key.

Self-hosted MinIO / other S3-compatible storage

See example/minio-pv.yaml (static) or example/minio-storageclass.yaml +
example/minio-dynamic-pvc.yaml (dynamic) — set cloud to s3compatible
and fill in endpoint.

Deploying to AWS EKS

If the target cluster is EKS with Graviton (arm64) nodes, add
--set nodeSelector."kubernetes\.io/arch"=arm64 to the helm install
command in Phase 1 — the chart pins both the controller Deployment and the
node DaemonSet to arm64 nodes. The rest of the flow (Phase 2) is the same;
eks/storageclass.yaml and eks/cloud-secret.yaml are examples pointed at
real AWS S3. eks/test-pods.yaml and eks/test-pod-same-node.yaml are
optional, advanced examples that verify cross-node/same-node RWX mounting
behavior.

Uninstalling

Removing a storage backend (Phase 2)

kubectl delete -f storageclass.yaml
kubectl -n kube-system delete secret mapfs-cloud-creds

A StorageClass/PV with reclaimPolicy: Retain never deletes data in the
cloud bucket — deleting the PV only removes the Kubernetes record.

Uninstalling the driver (Phase 1)

Only do this once no storage backend depends on it anymore.

helm uninstall mapfs-csi