This is an automated email from the ASF dual-hosted git repository.
weichiu pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 118a735d3 HDDS-14311. [Website v2] [Docs] [User Guide] CSI Protocol
(#197)
118a735d3 is described below
commit 118a735d38b227cb864c81285a8e8db5430bcd9d
Author: Eric C. Ho <[email protected]>
AuthorDate: Thu Jan 8 08:40:20 2026 +0800
HDDS-14311. [Website v2] [Docs] [User Guide] CSI Protocol (#197)
Co-authored-by: Wei-Chiu Chuang <[email protected]>
---
cspell.yaml | 1 +
.../01-client-interfaces/08-csi-protocol.md | 73 +++++++++++++++++++++
docs/04-user-guide/01-client-interfaces/CSI.png | Bin 0 -> 27210 bytes
.../persistent-volume-test-web-ui.png | Bin 0 -> 13830 bytes
4 files changed, 74 insertions(+)
diff --git a/cspell.yaml b/cspell.yaml
index df163bf73..5059d94cc 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -135,6 +135,7 @@ words:
- Boto3
- fsspec
- libhdfs
+- goofys
- WebHDFS
# Misc words
- acking
diff --git a/docs/04-user-guide/01-client-interfaces/08-csi-protocol.md
b/docs/04-user-guide/01-client-interfaces/08-csi-protocol.md
new file mode 100644
index 000000000..1f594e45a
--- /dev/null
+++ b/docs/04-user-guide/01-client-interfaces/08-csi-protocol.md
@@ -0,0 +1,73 @@
+---
+sidebar_label: CSI Protocol
+---
+
+# CSI Protocol
+
+:::warning
+Ozone CSI support is still in alpha phase and buckets can be mounted only via
3rd party S3 compatible Fuse implementation (like Goofys).
+Fuse over S3 can provide only limited performance compared to a native Fuse
file system.
+Long-term Ozone may support a custom solution to mount buckets which provides
better user experience (with fuse or NFS or any other solution).
+Until that CSI is recommended to use only if you can live with this limitation
and your use case is tested carefully.
+:::
+
+`Container Storage Interface` (CSI) will enable storage vendors (SP) to
develop a plugin once and have it work across a number of container
orchestration (CO) systems like Kubernetes or Yarn.
+
+To get more information about CSI at [SCI
spec](https://github.com/container-storage-interface/spec/blob/master/spec.md)
+
+CSI defined a simple gRPC interface with 3 interfaces (Identity, Controller,
Node). It defined how the Container Orchestrator can request the creation of a
new storage space or the mount of the newly created storage but doesn't define
how the storage can be mounted.
+
+
+
+By default Ozone CSI service uses a S3 fuse driver
([goofys](https://github.com/kahing/goofys)) to mount the created Ozone bucket.
Implementation of other mounting options such as a dedicated NFS server or
native Fuse driver is work in progress.
+
+Ozone CSI is an implementation of CSI, it can make possible of using Ozone as
a storage volume for a container.
+
+## Getting started
+
+First of all, we need an Ozone cluster with s3gateway, and its OM RPC port and
s3gateway port must be visible to CSI pod,
+because CSIServer will access OM to create or delete a bucket, also, CSIServer
will publish volume by creating a mount point to s3g
+through goofys.
+
+If you don't have an Ozone cluster on Kubernetes, you can reference
[Kubernetes](../../02-quick-start/01-installation/02-kubernetes.md) to create
one. Use the resources from `kubernetes/examples/ozone` where you can find all
the required Kubernetes resources to run cluster together with the dedicated
Ozone CSI daemon (check `kubernetes/examples/ozone/csi`)
+
+Now, create the CSI related resources by execute the follow command.
+
+```bash
+kubectl create -f /ozone/kubernetes/examples/ozone/csi
+```
+
+## Create pv-test and visit the result
+
+Create pv-test related resources by execute the follow command.
+
+```bash
+kubectl create -f /ozone/kubernetes/examples/ozone/pv-test
+```
+
+Attach the pod `scm-0` and put a key into the `/s3v/pvc*` bucket.
+
+```bash
+kubectl exec -it scm-0 bash
+[hadoop@scm-0 ~]$ ozone sh bucket list s3v
+[ {
+ "metadata" : { },
+ "volumeName" : "s3v",
+ "name" : "pvc-861e2d8b-2232-4cd1-b43c-c0c26697ab6b",
+ "storageType" : "DISK",
+ "versioning" : false,
+ "creationTime" : "2020-06-11T08:19:47.469Z",
+ "encryptionKeyName" : null
+} ]
+[hadoop@scm-0 ~]$ ozone sh key put
/s3v/pvc-861e2d8b-2232-4cd1-b43c-c0c26697ab6b/A LICENSE.txt
+```
+
+Now, let's forward port of the `ozone-csi-test-webserver-7cbdc5d65c-h5mnn` to
see the UI through the web browser.
+
+```bash
+kubectl port-forward ozone-csi-test-webserver-7cbdc5d65c-h5mnn 8000:8000
+```
+
+Eventually, we can see the result from `http://localhost:8000/`
+
+
diff --git a/docs/04-user-guide/01-client-interfaces/CSI.png
b/docs/04-user-guide/01-client-interfaces/CSI.png
new file mode 100644
index 000000000..38720c301
Binary files /dev/null and b/docs/04-user-guide/01-client-interfaces/CSI.png
differ
diff --git
a/docs/04-user-guide/01-client-interfaces/persistent-volume-test-web-ui.png
b/docs/04-user-guide/01-client-interfaces/persistent-volume-test-web-ui.png
new file mode 100644
index 000000000..69e0aa121
Binary files /dev/null and
b/docs/04-user-guide/01-client-interfaces/persistent-volume-test-web-ui.png
differ
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
