MinIO AIStor Memory Documentation

Mount an AIStor Memory Bucket at /workspace in a Red Hat OpenShift agent pod, so the agent's work survives the pod.

When an OpenShift agent pod is deleted, anything the agent wrote to the container's own filesystem is lost. AIStor Memory mounts a Memory Bucket at /workspace, so everything the agent writes there is stored in your AIStor. The next pod mounts the same bucket and starts with what the last one wrote.

The pod runs the AIStor Memory release image, quay.io/minio/aistor/aimem. It mounts the bucket, waits for the mount, and then runs your agent command or stays running for oc rsh.

Prerequisites

Use a Memory Bucket

aimem mounts only a Memory Bucket. See Prerequisites.

oc, and cluster-admin or kubeadmin credentials. The deployment adds a security context constraint (SCC), which needs cluster-admin.
An AIStor endpoint that the cluster can reach, and signing credentials for it.
Pull access to quay.io/minio/aistor/aimem.

Quick start

Download the example, then run the deployment script from that directory:

mkdir aimem-openshift && cd aimem-openshift
base=https://docs.min.io/aimem/examples/openshift
for f in aimem-workspace.yaml deploy.sh rbac.yaml scc.yaml; do
  curl -fsSLO "$base/$f"
done
chmod +x deploy.sh

oc login ...

AIMEM_BUCKET=my-project \
AIMEM_ENDPOINT=https://aistor.example.com \
AIMEM_ACCESS_KEY=... \
AIMEM_SECRET_KEY=... \
./deploy.sh

The script deploys into the aimem namespace. It applies the SCC, creates the aimem service account and its SCC binding, creates aimem-config and aimem-credentials, and deploys the aimem-workspace pod. It then waits for /workspace to become a FUSE mount, checks that the AIStor Memory skill is installed and that files can be written and read under /workspace, and leaves the pod running.

Open a shell in the mounted workspace:

oc rsh -n aimem aimem-workspace

To run an agent command after the mount is ready, set AIMEM_COMMAND:

AIMEM_BUCKET=my-project \
AIMEM_ENDPOINT=https://aistor.example.com \
AIMEM_ACCESS_KEY=... \
AIMEM_SECRET_KEY=... \
AIMEM_COMMAND='my-agent --flag' \
./deploy.sh

Options

Variable	Default	Use it for
`NAMESPACE`	`aimem`	A different target namespace.
`AIMEM_VERSION`	`latest`	A specific release image tag.
`AIMEM_IMAGE`	`quay.io/minio/aistor/aimem:<version>`	A mirrored copy of the release image.
`AIMEM_COMMAND`	`sleep infinity`	Starting an agent after the mount.
`AIMEM_REGION`	unset	Endpoints needing an explicit region.
`AIMEM_PREFIX`	unset	Mounting a sub-prefix of the Memory Bucket.
`AIMEM_LOCAL`	`/var/cache/aimem-staging`	Overriding the mandatory local staging dir.
`AIMEM_AGENT`	`auto`	Selecting the agent-memory profile.
`AIMEM_ALLOW_OTHER`	unset	Setting `allow_other` on the mount.
`KEEP`	`1`	Set `0` to delete the pod on exit.
`CLEANUP`	unset	With `KEEP=0`, also remove SCC/RBAC/config.

The release image holds aimem, the setuid aimem-fusermount helper, and aimem-workspace, which mounts the bucket at /workspace and then runs the workload command. There is no separate OpenShift image. For a disconnected cluster, mirror the release image into your registry and set AIMEM_IMAGE to the mirror.

Where this works

A FUSE mount needs CAP_SYS_ADMIN, privilege escalation for the setuid aimem-fusermount helper, and access to /dev/fuse. OpenShift's default restricted-v2 SCC blocks these, so the script applies scc.yaml.

Target	Works?	Notes
Self-managed OpenShift / OKD	Yes	Use a cluster-admin account.
OpenShift Local (CRC)	Yes	Log in as `kubeadmin`.
MicroShift	Yes	Use the generated kubeadmin kubeconfig.
ROSA / OpenShift Dedicated	Maybe	Grant cluster-admin first, then use this SCC path.
Free hosted Developer Sandbox	No	You cannot create or bind the SCC, so FUSE is blocked.

How FUSE works here

aimem opens /dev/fuse and calls mount(2) directly when it has CAP_SYS_ADMIN. If that fails with EPERM, it uses the setuid-root aimem-fusermount helper. The container still runs as a non-root user.

The manifest supports both ways a cluster can provide /dev/fuse, so you do not have to choose:

a hostPath CharDevice volume, for runtimes that expose /dev/fuse on the node, and
the OpenShift / CRI-O annotations used by OpenShift 4.15 and later.

Reference

deploy.sh: the deployment script.
aimem-workspace.yaml: the workspace pod.
scc.yaml: the FUSE SCC.
rbac.yaml: the service account and its SCC binding, as a manifest for the aimem namespace.