mapfs-csi AWS EKS Deployment

This is the AWS EKS bundle — IRSA (IAM Roles for Service Accounts), not static access key/secret key — IRSA only supports cloud: s3 (AWS); there is no equivalent mechanism for Azure/GCS/other vendors, so this bundle has no Azure/MinIO/etc. variants.

If you genuinely want static credentials on an EKS cluster instead (e.g. quick local testing, not a Marketplace deployment), see /docs/k8s/k8s_deploy.html instead — that's a separate, independently released bundle, not a variant of this one.

Download the Bundle

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

Directory Layout

mapfs-csi-manifests-eks-1.1.3/
├── channel-server.yaml       # ChannelServer (channeld) Deployment+Service
├── mapfs-csi-chart/          # Helm chart (IRSA-only, defaults to Marketplace ECR images)
├── storageclass.yaml         # Dynamic-provisioning StorageClass template (irsa: "true")
└── pv.yaml / pvc.yaml        # Static-provisioning templates

Prerequisites

An EKS cluster with kubectl, helm (v3+), aws, and eksctl configured against it
A valid mapfs license (email + token, from https://mapfs.cloud/)
An existing S3 bucket

One-Time Cluster Setup

Associate the cluster's OIDC provider (once per cluster; safe to re-run), create an IAM policy scoped to your bucket, then create the ServiceAccount + IAM Role + trust relationship in one step (eksctl sets the trust policy's subject to exactly system:serviceaccount:kube-system:mapfs-mount-sa, which a hand-rolled IAM Role easily gets wrong):

eksctl utils associate-iam-oidc-provider \
  --cluster <cluster-name> --region <region> --approve

aws iam create-policy \
  --policy-name mapfs-irsa-test \
  --policy-document file://mapfs-irsa-policy.json   # scoped to s3:ListBucket/GetObject/PutObject/DeleteObject

eksctl create iamserviceaccount \
  --cluster <cluster-name> --region <region> \
  --namespace kube-system \
  --name mapfs-mount-sa \
  --attach-policy-arn <arn from create-policy above> \
  --approve

See /docs/k8s/eks_quickstart.html for the full IAM policy JSON and verification commands.

Install the Driver

This is a one-time, per-cluster step.

Deploy the ChannelServer (channeld); one per cluster, not per-volume:
```
kubectl apply -f channel-server.yaml
```
Log in to the Marketplace ECR registry, then install the chart, pointing channelServer.address at the Service from step 1:
```
aws ecr get-login-password --region us-east-1 | \
  helm registry login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

helm install mapfs-csi oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/wyflow/mapfs-csi-chart --version 1.1.3 \
  --set license.email=you@example.com \
  --set license.token=<token-from-mapfs-portal> \
  --set channelServer.address=mapfs-channel.kube-system.svc.cluster.local:7777 \
  --set irsa.acknowledgePreCreatedSA=true
```
irsa.acknowledgePreCreatedSA=true tells the chart's install-time validation "I already created mapfs-mount-sa myself" — the chart otherwise refuses to install rather than silently deploy mount pods that reference a ServiceAccount which doesn't exist. This chart has no irsa.enabled toggle; IRSA is the whole chart. On Graviton (arm64) nodes, also add --set nodeSelector."kubernetes\.io/arch"=arm64 (only needed for mixed amd64/arm64 clusters).

Check status:

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

To upgrade to a newer version later:

helm upgrade mapfs-csi oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/wyflow/mapfs-csi-chart --version <new-version>

Configure a Storage Backend

No Secret to create — credentials come from IRSA. Repeat this for every bucket you want to expose to the cluster. The diffs below show the minimum edits for a working example; see each file's own comments for the rest (cache sizing, etc).

Dynamic provisioning: storageclass.yaml

--- storageclass.yaml
+++ storageclass.yaml
@@
   cloud: "aws"
-  bucket: "<YOUR_BUCKET>"
+  bucket: "my-mapfs-bucket"
-  region: "<YOUR_REGION>"    # e.g. us-east-1, must match the bucket's actual region
+  region: "us-east-1"
   irsa: "true"

kubectl apply -f storageclass.yaml

A PVC with storageClassName: mapfs-s3-eks then gets its PV created automatically.

Static provisioning: pv.yaml + pvc.yaml

Edit pv.yaml:

--- pv.yaml
+++ pv.yaml
@@
-  name: __PV_NAME__                   # e.g. mapfs-prod-bucket-pv
+  name: mapfs-prod-bucket-pv
@@
     # used as the mapfs volume name passed to "mapfs mount"
     # lowercase letters, digits, hyphen and dot only, max 253 chars
-    volumeHandle: __VOLUME_NAME__
+    volumeHandle: prod-bucket-vol
@@
       cloud: "aws"
-      bucket: "__BUCKET_NAME__"
+      bucket: "my-mapfs-bucket"
       irsa: "true"
-      region: "__REGION__"  # e.g. us-east-1, must match the bucket's actual region
+      region: "us-east-1"

Edit pvc.yaml (a matching Pod ships in the same file) — identical shape to the generic Kubernetes bundle's pvc.yaml, see /docs/k8s/k8s_deploy.html for that diff.

kubectl apply -f pv.yaml -f pvc.yaml

See /docs/k8s/eks_quickstart.html for a full walkthrough, including how to verify IRSA is actually in effect on the mount pod.

Uninstalling

Removing a storage backend

kubectl delete -f storageclass.yaml

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

Uninstalling the driver

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

helm uninstall mapfs-csi
kubectl delete -f channel-server.yaml

If you also want to tear down the IAM Role/ServiceAccount from the one-time setup:

eksctl delete iamserviceaccount \
  --cluster <cluster-name> --region <region> \
  --namespace kube-system --name mapfs-mount-sa