{"id":486,"date":"2025-09-10T11:28:34","date_gmt":"2025-09-10T11:28:34","guid":{"rendered":"https:\/\/blog.ngocha.biz\/?p=486"},"modified":"2025-09-10T11:28:34","modified_gmt":"2025-09-10T11:28:34","slug":"oci-image-volume-kubernetes-pods","status":"publish","type":"post","link":"https:\/\/blog.ngocha.biz\/?p=486","title":{"rendered":"How to Mount OCI Image as Volume in Kubernetes Pod"},"content":{"rendered":"

In this guide, you will learn how to mount OCI container images as volumes in Kubernetes Pods using the ImageVolume feature.<\/p>\n

This feature is especially useful for ML projects that work with LLMs, as it allows you to package model data in OCI images and easily switch between different models.<\/p>\n

ImageVolume (beta feature)<\/h2>\n

Kubernetes version 1.31 has introduced a new alpha feature that allows you to use OCI image volumes directly within Kubernetes pods<\/a>. In Kubernetes version 1.33, it has been changed to a beta feature.<\/p>\n

So what are OCI images?<\/p>\n

OCI images are images that follow Open Container Initiative<\/a> specifications. For example, Docker<\/a>, Podman<\/a>, containerd and CRI-O<\/strong> runtimes used OCI image specifications for images.<\/p>\n

You can use the ImageVolume<\/code><\/strong> feature to store binary artifacts in images and mount them to pods. Also, a key thing about this feature is, it is a read only Volume.<\/strong><\/p>\n

\"Mount<\/figure>\n

Now, lets get started with the practical example.<\/p>\n

Step 1: Enable the ImageVolume Feature Gate<\/h2>\n

ImageVolume<\/strong> feature is not enabled by default. <\/p>\n

So, to mount OCI image in a pods volume, first you need to enable the feature gate <\/a>ImageVolume<\/code><\/strong> in the Kubernetes cluster<\/a><\/p>\n

\n
\u26a0\ufe0f<\/div>\n
If you are using CRI-O as the runtime, the version should be above or atleast v1.31<\/strong><\/b>, and if the runtime you are using containerd, the version should be above or atleast v2.1.0.<\/strong><\/b><\/div>\n<\/div>\n

To enable this feature gate, you have to modify the API server manifest and kubelet config file as given below.<\/p>\n

To edit the API server manifest file, open the manifest file using the following command.<\/p>\n

sudo vi \/etc\/kubernetes\/manifests\/kube-apiserver.yaml\n<\/code><\/pre>\n
Then add the following line.<\/p>\n
- --feature-gates=ImageVolume=true<\/code><\/pre>\n
Once you save the file, the API server will restart automatically.<\/p>\n
Now, modify the kubelet config file.<\/p>\n
sudo vi \/var\/lib\/kubelet\/config.yaml<\/code><\/pre>\n
And add the following block inside the config file.<\/p>\n
featureGates:\n  ImageVolume: true<\/code><\/pre>\n
Then restart the kubelet.<\/p>\n
sudo systemctl daemon-reload\n\nsudo systemctl restart kubelet<\/code><\/pre>\n
Testing in Kind Cluster (Optional)<\/h2>\n
If you just want to check this feature and you dont have an active cluster, you can create a Kind cluster in which we can enable ImageVolume feature gates during creation.<\/p>\n
kind: Cluster\napiVersion: kind.x-k8s.io\/v1alpha4\nname: multi-node-cluster\nfeatureGates:\n  ImageVolume: true\nnodes:\n  - role: control-plane\n    image: kindest\/node:v1.33.1\n    extraPortMappings:\n      - containerPort: 30000\n        hostPort: 30000\n        protocol: TCP\n      - containerPort: 31000\n        hostPort: 31000\n        protocol: TCP\n      - containerPort: 32000\n        hostPort: 32000\n        protocol: TCP\n      - containerPort: 80\n        hostPort: 80\n        protocol: TCP\n      - containerPort: 443\n        hostPort: 443\n        protocol: TCP\n  - role: worker\n    image: kindest\/node:v1.33.1\n  - role: worker\n    image: kindest\/node:v1.33.1<\/code><\/pre>\n
Step 2: Build an OCI Image<\/h2>\n
The next step is to build an OCI image.<\/p>\n
For this example, I am using a prediction model that I have locally. You can replace the model file with any file for testing.<\/p>\n
Here is the Dockerfile.<\/p>\n
FROM scratch\nCOPY model.pkl \/models\/model.pkl<\/code><\/pre>\n
\n
I have uploaded this image to Docker Hub as devopscube\/oci-image:1.0<\/code>.
You can use it directly for testing.<\/div>\n<\/div>\n
Step 3: Deploy a Predictor Application<\/h2>\n
To test the ImageVolume, we will deploy a simple Python predictor application. This application loads the model.pkl<\/code> file directly from the mounted image volume.<\/p>\n
\n
I have already built the app and published it as devopscube\/predictor:1.0<\/code>, which you can use for testing.<\/div>\n<\/div>\n
Here is the python code that is part of the predictor image.<\/p>\n
import os\nimport joblib\nimport numpy as np\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel\n\nMODEL_PATH = os.environ.get(\"MODEL_PATH\", \"\/models\/model.pkl\")\nmodel = joblib.load(MODEL_PATH)\n\napp = FastAPI()\n\nclass PredictIn(BaseModel):\n    instances: list\n\n@app.get(\"\/healthz\")\ndef healthz():\n    return {\"ok\": True, \"model_path\": MODEL_PATH}\n\n@app.post(\"\/v1\/models\/model:predict\")\ndef predict(p: PredictIn):\n    X = p.instances\n    try:\n        X_arr = np.array(X, dtype=float)\n        preds = model.predict(X_arr).tolist()\n    except Exception:\n        preds = model.predict(X).tolist()\n    return {\"predictions\": preds}<\/code><\/pre>\n
Step 4: Test the ImageVolume<\/h2>\n
Now, lets deploy the predictor image and the OCI volume image to test the image volume.<\/p>\n
Here are the Deployment and Service manifests.<\/p>\n
apiVersion: apps\/v1\nkind: Deployment\nmetadata:\n  name: predictor\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: predictor\n  template:\n    metadata:\n      labels:\n        app: predictor\n    spec:\n      containers:\n      - name: app\n        image: devopscube\/predictor:1.0                    \n        ports:\n        - containerPort: 8000\n        env:\n        - name: MODEL_PATH\n          value: \/volume\/models\/model.pkl\n        volumeMounts:\n        - name: model-vol\n          mountPath: \/volume\n      volumes:\n      - name: model-vol\n        image:\n          reference: devopscube\/oci-image:1.0\n          pullPolicy: IfNotPresent\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: predictor-svc\nspec:\n  selector:\n    app: predictor\n  ports:\n  - port: 80\n    targetPort: 8000<\/code><\/pre>\n
Deploy the above manifest and once the pod is running without issues, check if the model.pkl<\/code> file is inside the volume.<\/p>\n
$ kubectl exec -it predictor-7f7ff66689-gwg5w -- ls \/volume\/models\n\nmodel.pkl<\/code><\/pre>\n
Now run the following command to port-forward the predictor service so that we can test the prediction endpoint.<\/p>\n
kubectl port-forward svc\/predictor-svc 8080:80<\/code><\/pre>\n
Now, use the following curl<\/code> command from your workstation to send a prediction request to the predictor application. This will validate whether the application is able to access the model.pkl<\/code> file from the ImageVolume<\/code><\/strong>.<\/p>\n
curl -X POST \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n        \"instances\": [\n          \"sparrow\",\n          \"elephant\",\n          \"rose\"     \n        ]\n      }' \\\n  \"http:\/\/127.0.0.1:8080\/v1\/models\/model:predict\"<\/code><\/pre>\n
You will get the following output.<\/p>\n
\"\"<\/figure>\n
This is the expected output, 0<\/code> means animal, 1<\/code> means bird, and 2<\/code> means plant.<\/p>\n
That\u2019s a wrap! \ud83c\udf89<\/p>\n
Conclusion<\/h2>\n
In this post, you learned how to enable the ImageVolume feature in Kubernetes, build an OCI image, and test it with a sample predictor ML application. <\/p>\n
This feature makes it easy to package data, tools , or models and switch between models without managing complex storage setups.<\/p>\n
Refer the Kubernetes ML features<\/a> blog to know more about native ML support in Kubernetes.<\/p>\n
If you want to learn more Kubernetes concepts, look at our Kubernetes tutorial<\/a> blog.<\/p>\n
Try this feature and let me know how it goes!<\/p>\n
\n
Ngu\u1ed3n:<\/strong> How to Mount OCI Image as Volume in Kubernetes Pod \u2014 DevOpsCube<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Source: https:\/\/devopscube.com\/oci-image-volume-kubernetes-pods\/<\/p>\n","protected":false},"author":1,"featured_media":487,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-486","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops"],"_links":{"self":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts\/486","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=486"}],"version-history":[{"count":0,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/posts\/486\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=\/wp\/v2\/media\/487"}],"wp:attachment":[{"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=486"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=486"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.ngocha.biz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=486"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}