Ossfs 1.0 release notes-Container Service for Kubernetes(ACK)-阿里云帮助中心

The ossfs 1.0 client version upgrades as CSI iterates. This topic explains the version format, how to check your ossfs version, and how to switch to 1.91 or later.

How ossfs works

ossfs 1.0 is a userspace filesystem that mounts an OSS bucket to a Linux local filesystem. When you mount an OSS volume with CSI, csi-plugin starts an ossfs process that mounts the bucket to a container path, enabling POSIX read and write operations on OSS objects.

ossfs 1.0 inherits all s3fs features and adds:

Most POSIX file operations, including file and directory upload, download, and permission management
Multipart and resumable upload, 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.

Version format

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

x.yy — the upstream s3fs version. Roll back to a specific x.yy version with CSI environment variables.
z — the ossfs iteration version, adding OSS- and ACK-specific enhancements such as monitoring, authentication, and encryption. 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 ossfs version depends on the 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

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. Select your CSI version below.

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

Choose a method based on your CSI version.

Upgrade CSI (recommended)

CSI 1.30.4 or later uses ossfs 1.91+ by default, so upgrading CSI switches ossfs automatically.

Enable the UpdatedOssfsVersion feature gate

If you cannot upgrade CSI, 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 mounting the same OSS volume on the same node share one ossfs process, so only one csi-fuse-ossfs-*** pod runs per shared volume.

Prerequisites

csi-plugin is 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 your cluster name, then click Add-ons in the left navigation pane.
On the Add-ons page, locate csi-plugin and check its version. If earlier than 1.30.1, click Upgrade on the csi-plugin 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 enabled, append 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 existing feature gate configuration. If unsure whether other feature gates are enabled, use kubectl 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 enabled, use the format xxxxxx=true,yyyyyy=false,UpdatedOssfsVersion=true.

Next steps

New features and performance benchmarks of ossfs 1.0