Container Service for Kubernetes:ossfs 1.0 release notes - Container Service for Kubernetes

How ossfs works

When you mount an OSS volume using CSI, the csi-plugin component starts an ossfs process. This process mounts data from an OSS bucket to a specified path inside a container, letting your application read and write objects using standard POSIX file operations.

ossfs 1.0 is built on s3fs and inherits all of its features. Additional capabilities include:

Support for most POSIX file protocol operations, including file and directory upload and download, and user permission management
Multipart upload and resumable upload for file transfers, enabled by default
MD5 verification for data integrity

Limitations

ossfs 1.0 supports most, but not all, POSIX file system features. For high-performance file operations, use ossfs 1.0 version 1.91 or later. See Best practices for enabling version 1.91 and later for use case guidance.

Version format

ossfs 1.0 version numbers follow the format x.yy.z:

x.yy — the upstream s3fs version ossfs is based on. Roll back to a specific x.yy version using CSI environment variables.
z — the ossfs iteration version, which adds OSS- and ACK-specific enhancements such as monitoring, authentication, and encryption features. For version details, see csi-plugin.

Container builds include an .ack.1 suffix to distinguish them from the open source ossfs release. For example: 1.80.6.ack.1.

Version compatibility

The following table shows the ossfs version deployed by each CSI version:

Architecture	ossfs 1.0 version	CSI version
Arm64	1.91 and later	v1.30.1-98960d8-aliyun (enabled through a feature gate) / v1.30.4-fe12624-aliyun (default)
Arm64	1.80.x	v1.20.5-ff6490f-aliyun (the first CSI version to support Arm64)
AMD64	1.91 and later	v1.30.1-98960d8-aliyun (enabled through a feature gate) / v1.30.4-fe12624-aliyun (default)
AMD64	1.88.x	v1.22.14-820d8870-aliyun
AMD64	1.86.x	v1.16.9.43-f36bb540-aliyun
AMD64	1.80.x	Initial version

For the full history of changes in ossfs 1.91 and later, see Version update features.

Check the ossfs version

How you check the ossfs version depends on your CSI version.

CSI earlier than 1.28 (and not 1.26.6) — ossfs runs directly on the node. Log on to any node and run:

/usr/local/bin/ossfs --version

CSI 1.26.6, or 1.28.1 or later — ossfs runs as a container pod inside the cluster. Use the appropriate method below based on your CSI version.

CSI 1.30.4 or later

CSI 1.30.4 or later creates ossfs pods in the ack-csi-fuse namespace after you mount an OSS volume.

List the running ossfs pods:

kubectl -n ack-csi-fuse get pod | grep csi-fuse-ossfs

Check the ossfs version:

kubectl -n ack-csi-fuse exec -it <csi-fuse-ossfs-xxxx> -- ossfs --version

CSI earlier than 1.30.4

CSI versions earlier than 1.30.4 create ossfs pods in the kube-system namespace.

List the running ossfs pods:

kubectl -n kube-system get pod | grep csi-fuse-ossfs

Check the ossfs version:

kubectl -n kube-system exec -it <csi-fuse-ossfs-xxxx> -- ossfs --version

Switch to ossfs 1.91 or later

Two methods are available. Choose based on your current CSI version.

Method 1: Upgrade the CSI component (recommended)

CSI 1.30.4 or later uses ossfs 1.91 or later by default. Upgrading the CSI component switches ossfs to 1.91 or later automatically.

Method 2: Enable the UpdatedOssfsVersion feature gate

If upgrading the CSI component is not an option, enable the UpdatedOssfsVersion feature gate on CSI 1.30.1 or later.

What changes and what doesn't:

Newly launched ossfs containers automatically use version 1.91 or later.
Existing applications that use OSS volumes are not affected immediately.
To upgrade a running application, restart its ossfs process. See How do I restart the ossfs process in shared mount mode?

Note

By default, pods that mount the same OSS volume on the same node share a single ossfs process, so the cluster runs only one pod named csi-fuse-ossfs-*** per shared volume.

Prerequisites

csi-plugin version 1.30.1 or later

To check your csi-plugin version:

Log on to the ACK console and click Clusters in the left navigation pane.
Click the name of your cluster, then click Add-ons in the left navigation pane.
On the Add-ons page, locate csi-plugin and check the displayed version. If the version is earlier than 1.30.1, click Upgrade in the lower-right corner of the component card.

Enable via kubectl

Edit the csi-plugin DaemonSet:

kubectl -n kube-system edit ds csi-plugin

In the args section of the csi-plugin container (not an init container), add the feature gate flag:
```
- args:
  - --endpoint=$(CSI_ENDPOINT)
  - --v=2
  - --driver=oss,nas,disk
  - --feature-gates=UpdatedOssfsVersion=true
```
If other feature gates are already enabled, append the new gate to the existing --feature-gates value:
```
- --feature-gates=xxxxxx=true,yyyyyy=false,UpdatedOssfsVersion=true
```

Enable via the ACK console

Important

Enabling a feature gate from the console overwrites any existing feature gate configuration. If you are unsure whether other feature gates are enabled, use the kubectl method instead.

On the Add-ons page, click Configuration on the csi-plugin card.
On the csi-plugin Parameters page, set FeatureGate to UpdatedOssfsVersion=true and click OK. If other feature gates are already enabled, use the format xxxxxx=true,yyyyyy=false,UpdatedOssfsVersion=true.

Next steps

New features and performance benchmarks of ossfs 1.0