Help Center/ Cloud Container Engine_Autopilot/ User Guide/ Storage/ SFS Turbo/ Using an Existing SFS Turbo File System Through a Static PV

Updated on 2025-01-27 GMT+08:00

View PDF

Using an Existing SFS Turbo File System Through a Static PV

SFS Turbo is a shared file system with high availability and durability. It is suitable for applications that contain massive small files and require low latency, and high IOPS. You can use a manually created SFS Turbo file system to create a PV, which can be bound to a PVC to allow pods share this PV for persistent data storage. This section describes how to use an existing SFS Turbo file system to statically create PVs and PVCs and implement data persistence and sharing in workloads. You can choose to create new subdirectories when creating a PV.

Prerequisites

You have created an available SFS Turbo file system that is in the same VPC as the cluster.
If you want to create a cluster using commands, kubectl has been used to connect to the cluster. For details, see Connecting to a Cluster Using kubectl.

Constraints

Not all regions support SFS Turbo volumes. View the regions where SFS Turbo volumes are supported on the console. You can also view Function Overview to learn about all regions where SFS Turbo volumes are supported.
Multiple PVs can use the same SFS Turbo file system with the following restrictions:
- All PVCs or PVs that use the same SFS Turbo file system cannot be mounted to a pod. This will result in a pod startup failure because not all PVCs can be mounted to the pod due to the same volumeHandle values of these PVs.
- The persistentVolumeReclaimPolicy parameter in the PVs should be set to Retain. If any other value is used, when a PV is deleted, the associated underlying volume may be deleted. In this case, other PVs associated with the underlying volume malfunction.
- When a file system is repeatedly used, enable isolation and protection for ReadWriteMany at the application layer to prevent data overwriting and loss.
To create subdirectories for an SFS Turbo volume, the cluster version must be v1.27.9-r0, v1.28.7-r0, or later. If the cluster version does not meet the requirements, you need to upgrade the cluster.
For SFS Turbo storage, the yearly/monthly SFS Turbo resources will not be reclaimed when the cluster or PVC is deleted. Reclaim the resources on the SFS Turbo console.

Using the Console

Statically create a PVC and PV.

In the navigation pane on the left, choose Storage. Then click the PVCs tab. In the upper right corner, click Create PVC. In the displayed dialog box, configure the parameters.

Parameter	Description
PVC Type	In this example, select SFS Turbo.
PVC Name	Enter the PVC name, which must be unique in the same namespace.
Namespace	Namespace of the PVC. In the navigation pane, choose Storage. If Namespace in the upper part of the page is All namespaces or Non-system namespace, you can select an appropriate namespace. If you choose Storage in the navigation pane and a non-system namespace (for example, default) has been specified for Namespace in the upper part of the page, the namespace is displayed here.
Creation Method	You can create a storage volume or use an existing storage volume to statically create a PVC based on whether a PV is available. In this example, select Create new to create a PV and PVC at the same time on the console.
PV^a	Select an existing PV in the cluster. Create a PV in advance. For details, see "Creating a storage volume" in Related Operations. You do not need to specify this parameter in this example.
SFS Turbo^b	Click Select SFS Turbo. On the displayed page, select the SFS Turbo file system that meets your requirements and click OK.
Subdirectory^b	Determine whether to use subdirectories to create PVs. If this parameter is set to Yes, enter the absolute path of the subdirectory, for example, /a/b. In this case, the underlying storage associated with the PV is a subdirectory in the selected SFS Turbo file system. Ensure that the subdirectory is available.
PV Name^b	Enter the PV name, which must be unique in the same cluster.
Access Mode^b	SFS Turbo volumes support only ReadWriteMany, indicating that a storage volume can be mounted to multiple nodes in read/write mode. For details, see Volume Access Modes.
Reclaim Policy^b	Only Retain is available if you do not use subdirectories to create PVs. This indicates that the PV is not deleted when the PVC is deleted. For details, see PV Reclaim Policy. If you choose to create a subdirectory, this parameter can only be set to Delete.
Subdirectory Reclaim Policy^b	Determine whether to retain subdirectories when a PVC is deleted. This parameter must be used with PV Reclaim Policy and can be configured when PV Reclaim Policy is set to Delete. Retain: If a PVC is deleted, the PV will be deleted, but the subdirectories associated with the PV will be retained. Delete: After a PVC is deleted, the PV and its associated subdirectories will also be deleted.
Mount Options^b	Enter the mounting parameter key-value pairs. For details, see Configuring SFS Turbo Mount Options.

a: The parameter is available when Creation Method is set to Use existing.

b: The parameter is available when Creation Method is set to Create new.

Click Create to create a PVC and a PV.
In the navigation pane on the left, choose Storage. View the created PVC and PV on the PVCs and PVs tabs, respectively.

Create a workload.

In the navigation pane on the left, choose Workloads. Then click the Deployments tab.

In the upper right corner, click Create Workload. On the displayed page, click Data Storage in the Container Settings area and click Add Volume to select PVC.

Table 1 describes the parameters for mounting the volume. For details about other parameters, see Workloads.

**Table 1** Mounting a storage volume
Parameter	Description
PVC	Select an existing SFS Turbo volume.
Mount Path	Enter a mount path, for example, /tmp. This parameter indicates the container path that the volume will be mounted to. Do not mount the volume to a system directory such as / or /var/run. This may cause container errors. Mount the volume to an empty directory. If the directory is not empty, ensure that there are no files that affect container startup. If there are such files, they will be replaced, which will lead to a container startup or workload creation failure. NOTICE: If a volume is mounted to a high-risk directory, use an account with minimum permissions to start the container, or high-risk files on the host may be damaged.
Subpath	Enter a subdirectory of the PV. This subdirectory will be mounted to a specified path of a container. In this way, different subdirectories of the same PV can be used in a single pod. Enter a subpath, for example, tmp, indicating that data in the mount path of the container is stored in the tmp directory of the storage volume. If this parameter is left blank, the root path is used by default.
Permission	Read-only: You can only read the data in the mounted volume. Read-write: You can modify the volume mounted to the path. Newly written data will not be migrated if the container is migrated, which may cause data loss.

In this example, the volume is mounted to the /data path of the container. The container data generated in this path is stored in the SFS Turbo file system.

Figure 1 Mounting a PV
Click to enlarge

Configure other parameters and click Create Workload.
After the workload is created, the data in the container mount directory will be persistently stored. Verify the storage by referring to Verifying Data Persistence and Sharing.

Using kubectl

You can determine whether to use subdirectories based on your service requirements.

An entire SFS Turbo file system is used, and there are no subdirectories.

Use kubectl to connect to the cluster.

Create a PV.

Create the pv-sfsturbo.yaml file.

apiVersion: v1
kind: PersistentVolume
metadata:
  annotations:
    pv.kubernetes.io/provisioned-by: everest-csi-provisioner
  name: pv-sfsturbo    # PV name.
spec:
  accessModes:
  - ReadWriteMany      # Access mode. The value must be ReadWriteMany for SFS Turbo.
  capacity:
    storage: 500Gi       # SFS Turbo volume capacity.
  csi:
    driver: sfsturbo.csi.everest.io    # Dependent storage driver for the mounting.
    fsType: nfs
    volumeHandle: <your_volume_id>   # SFS Turbo volume ID.
    volumeAttributes:
      everest.io/share-export-location: <your_location>   # Shared path of the SFS Turbo volume.
      everest.io/enterprise-project-id: <your_project_id>  # Project ID of the SFS Turbo volume.

      storage.kubernetes.io/csiProvisionerIdentity: everest-csi-provisioner
  persistentVolumeReclaimPolicy: Retain    # Reclaim policy.
  storageClassName: csi-sfsturbo          # Storage class name of the SFS Turbo volume.
  mountOptions: []                         # Mount options.

**Table 2** Key parameters
Parameter	Mandatory	Description
volumeHandle	Yes	SFS Turbo volume ID. How to obtain: Log in to the console, choose Service List > Storage > Scalable File Service, and select SFS Turbo. In the list, click the name of the target SFS Turbo file system. On the details page, copy the content following ID.
everest.io/share-export-location	Yes	Shared path of the SFS Turbo volume. Log in to the console, choose Service List > Storage > Scalable File Service, and select SFS Turbo. You can obtain the shared path of the file system from the Mount Address column.
everest.io/enterprise-project-id	No	Project ID of the SFS Turbo volume. If you use the default enterprise project, set this field to 0. How to obtain: On the SFS console, click SFS Turbo in the left navigation pane. Click the name of the SFS Turbo file system to interconnect. On the Basic Info tab, find and click the enterprise project to go to the console, and copy the ID.
mountOptions	No	Mount options. If this parameter is not specified, the following configurations are used by default. For details, see Configuring SFS Turbo Mount Options. mountOptions: - vers=3 - timeo=600 - nolock - hard
persistentVolumeReclaimPolicy	Yes	Only the Retain reclaim policy is supported. For details, see PV Reclaim Policy. Retain: When a PVC is deleted, both the PV and underlying storage are retained. You need to manually delete these resources. After the PVC is deleted, the PV is in the Released state and cannot be bound to a PVC again.
storage	Yes	Requested capacity in the PVC, in Gi.
storageClassName	Yes	The storage class name of SFS Turbo volumes is csi-sfsturbo.

Run the following command to create a PV:
```
kubectl apply -f pv-sfsturbo.yaml
```

Create a PVC.

Create the pvc-sfsturbo.yaml file.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-sfsturbo
  namespace: default
  annotations:
    volume.beta.kubernetes.io/storage-provisioner: everest-csi-provisioner
    everest.io/enterprise-project-id: <your_project_id>  # Project ID of the SFS Turbo volume.

spec:
  accessModes:
  - ReadWriteMany                  # The value must be ReadWriteMany for SFS Turbo.
  resources:
    requests:
      storage: 500Gi               # SFS Turbo volume capacity.
  storageClassName: csi-sfsturbo       # Storage class of the SFS Turbo volume. It must be the same as that of the PV.
  volumeName: pv-sfsturbo    # PV name.

**Table 3** Key parameters
Parameter	Mandatory	Description
everest.io/enterprise-project-id	No	Project ID of the SFS Turbo volume. If you use the default enterprise project, set this field to 0. How to obtain: On the SFS console, click SFS Turbo in the left navigation pane. Click the name of the SFS Turbo file system to interconnect. On the Basic Info tab, find and click the enterprise project to go to the console, and copy the ID.
storage	Yes	Requested capacity in the PVC, in Gi. The value must be the same as the storage size of the existing PV.
storageClassName	Yes	Storage class name, which must be the same as the storage class of the PV in 2.a. The storage class name of SFS Turbo volumes is csi-sfsturbo.
volumeName	Yes	PV name, which must be the same as the PV name in 2.a.

Run the following command to create a PVC:
```
kubectl apply -f pvc-sfsturbo.yaml
```

Create a workload.

Create a file named web-demo.yaml. In this example, the SFS Turbo volume is mounted to the /data path.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-demo
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-demo
  template:
    metadata:
      labels:
        app: web-demo
    spec:
      containers:
      - name: container-1
        image: nginx:latest
        volumeMounts:
        - name: pvc-sfsturbo-volume    #Volume name, which must be the same as the volume name in the volumes field.
          mountPath: /data  #Location where the storage volume is mounted.
      imagePullSecrets:
        - name: default-secret
      volumes:
        - name: pvc-sfsturbo-volume    #Volume name, which can be changed as needed.
          persistentVolumeClaim:
            claimName: pvc-sfsturbo    #Name of the created PVC.

Run the following command to create a workload that the SFS Turbo volume is mounted to:
```
kubectl apply -f web-demo.yaml
```
After the workload is created, you can try Verifying Data Persistence and Sharing.

Use kubectl to connect to the cluster.

Create a PV.

Create the pv-sfsturbo.yaml file.

Example:

apiVersion: v1
kind: PersistentVolume
metadata:
  annotations:
    pv.kubernetes.io/provisioned-by: everest-csi-provisioner
    everest.io/reclaim-policy: retain-volume-only    # When a PVC is deleted, the PV will be deleted but the subdirectories associated with the PV will be retained. This parameter is available only when subdirectories are used and the reclaim policy is Delete.
  name: pv-sfsturbo    # PV name.
spec:
  accessModes:
  - ReadWriteMany      # Access mode. The value must be ReadWriteMany for SFS Turbo.
  capacity:
    storage: 500Gi       # SFS Turbo volume capacity.
  csi:
    driver: sfsturbo.csi.everest.io    # Dependent storage driver for the mounting.
    fsType: nfs
    volumeHandle: pv-sfsturbo   # PV name when subdirectories are used.
    volumeAttributes:
      everest.io/share-export-location: <sfsturbo_path>:/<absolute_path>   # Shared path and subdirectory of the SFS Turbo file system.
      everest.io/enterprise-project-id: <your_project_id>  # Project ID of the SFS Turbo volume.
      storage.kubernetes.io/csiProvisionerIdentity: everest-csi-provisioner
      everest.io/volume-as: absolute-path   # (Optional) An SFS Turbo subdirectory is used.
  persistentVolumeReclaimPolicy: Retain    # Reclaim policy, which can be set to Delete when subdirectories are automatically created.
  storageClassName: csi-sfsturbo          # Storage class name of the SFS Turbo volume.
  mountOptions: []                         # Mount options.

**Table 4** Key parameters
Parameter	Mandatory	Description
volumeHandle	Yes	PV name when an SFS Turbo subdirectory is used to create the PV.
everest.io/share-export-location	Yes	Shared path of the SFS Turbo subdirectory. Format: {sfsturbo_path}:/{absolute_path} Log in to the console, choose Service List > Storage > Scalable File Service, and select SFS Turbo. You can obtain the shared path of the file system.
everest.io/enterprise-project-id	No	Project ID of the SFS Turbo volume. If you use the default enterprise project, set this field to 0. How to obtain: On the SFS console, click SFS Turbo in the left navigation pane. Click the name of the SFS Turbo file system to interconnect. On the Basic Info tab, find and click the enterprise project to go to the console, and copy the ID.
mountOptions	No	Mount options. If this parameter is not specified, the following configurations are used by default. For details, see Configuring SFS Turbo Mount Options. mountOptions: - vers=3 - timeo=600 - nolock - hard
persistentVolumeReclaimPolicy	Yes	Reclamation policy. For details, see PV Reclaim Policy. Retain: When a PVC is deleted, both the PV and underlying storage are retained. You need to manually delete these resources. After the PVC is deleted, the PV is in the Released state and cannot be bound to a PVC again. Delete: This parameter can be configured when subdirectories are automatically created, indicating that the PV is deleted when a PVC is deleted.
everest.io/reclaim-policy	No	Whether to retain the subdirectory when deleting the PVC. This parameter is used in conjunction with PV Reclamation Policy. This parameter is available only when the PV reclaim policy is Delete. retain-volume-only: If a PVC is deleted, the PV will be deleted, but the subdirectories associated with the PV will be retained. delete: After a PVC is deleted, the PV and its associated subdirectories will also be deleted. NOTE: When a subdirectory is deleted, only the absolute path of the subdirectory configured in the PVC will be deleted. The upper-layer directory will not be deleted.
everest.io/volume-as	No	The value is fixed at absolute-path, indicating that a dynamically created SFS Turbo subdirectory is used.
storage	Yes	Requested capacity in the PVC, in Gi. If a subdirectory is used, this parameter serves no purpose other than for verification and must have a non-empty, non-zero value.
storageClassName	Yes	The storage class name of SFS Turbo volumes is csi-sfsturbo.

Run the following command to create a PV:
```
kubectl apply -f pv-sfsturbo.yaml
```

Create a PVC.

Create the pvc-sfsturbo.yaml file.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-sfsturbo
  namespace: default
  annotations:
    volume.beta.kubernetes.io/storage-provisioner: everest-csi-provisioner
      everest.io/enterprise-project-id: <your_project_id>  # Project ID of the SFS Turbo volume.
spec:
  accessModes:
  - ReadWriteMany                  # The value must be ReadWriteMany for SFS Turbo.
  resources:
    requests:
      storage: 500Gi               # SFS Turbo volume capacity.
  storageClassName: csi-sfsturbo       # Storage class of the SFS Turbo volume. It must be the same as that of the PV.
  volumeName: pv-sfsturbo    # PV name.

**Table 5** Key parameters
Parameter	Mandatory	Description
everest.io/enterprise-project-id	No	Project ID of the SFS Turbo volume. If you use the default enterprise project, set this field to 0. How to obtain: On the SFS console, click SFS Turbo in the left navigation pane. Click the name of the SFS Turbo file system to interconnect. On the Basic Info tab, find and click the enterprise project to go to the console, and copy the ID.
storage	Yes	Requested capacity in the PVC, in Gi. The value must be the same as the storage size of the existing PV.
storageClassName	Yes	Storage class name, which must be the same as the storage class of the PV in 2.a. The storage class name of SFS Turbo volumes is csi-sfsturbo.
volumeName	Yes	PV name, which must be the same as the PV name in 2.a.

Run the following command to create a PVC:
```
kubectl apply -f pvc-sfsturbo.yaml
```

Create a workload.

Create a file named web-demo.yaml. In this example, the SFS Turbo volume is mounted to the /data path.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-demo
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web-demo
  template:
    metadata:
      labels:
        app: web-demo
    spec:
      containers:
      - name: container-1
        image: nginx:latest
        volumeMounts:
        - name: pvc-sfsturbo-volume    #Volume name, which must be the same as the volume name in the volumes field.
          mountPath: /data  #Location where the storage volume is mounted.
      imagePullSecrets:
        - name: default-secret
      volumes:
        - name: pvc-sfsturbo-volume    # Volume name, which can be changed as needed.
          persistentVolumeClaim:
            claimName: pvc-sfsturbo    #Name of the created PVC.

Run the following command to create a workload that the SFS Turbo volume is mounted to:
```
kubectl apply -f web-demo.yaml
```
After the workload is created, you can try Verifying Data Persistence and Sharing.

Verifying Data Persistence and Sharing

View the deployed application and files.
1. Run the following command to view the created pod:
```
kubectl get pod | grep web-demo
```
  Expected output:
```
web-demo-846b489584-mjhm9   1/1     Running   0             46s
web-demo-846b489584-wvv5s   1/1     Running   0             46s
```
2. Run the following commands in sequence to view the files in the /data path of the pods:
```
kubectl exec web-demo-846b489584-mjhm9 -- ls /data
kubectl exec web-demo-846b489584-wvv5s -- ls /data
```
  If no result is returned for both pods, no file exists in the /data path.
Run the following command to create a file named static in the /data path:
```
kubectl exec web-demo-846b489584-mjhm9 --  touch /data/static
```
Run the following command to check the files in the /data path:
```
kubectl exec web-demo-846b489584-mjhm9 -- ls /data
```
Expected output:
```
static
```
Verify data persistence.
1. Run the following command to delete the pod named web-demo-846b489584-mjhm9:
```
kubectl delete pod web-demo-846b489584-mjhm9
```
  Expected output:
```
pod "web-demo-846b489584-mjhm9" deleted
```
  After the deletion, the Deployment controller automatically creates a replica.
2. Run the following command to view the created pod:
```
kubectl get pod | grep web-demo
```
  The expected output is as follows, in which web-demo-846b489584-d4d4j is the newly created pod:
```
web-demo-846b489584-d4d4j   1/1     Running   0             110s
web-demo-846b489584-wvv5s    1/1     Running   0             7m50s
```
3. Run the following command to check whether the files in the /data path of the new pod have been modified:
```
kubectl exec web-demo-846b489584-d4d4j -- ls /data
```
  Expected output:
```
static
```
  The static file is retained, indicating that the data in the file system can be stored persistently.
Verify data sharing.
1. Run the following command to view the created pod:
```
kubectl get pod | grep web-demo
```
  Expected output:
```
web-demo-846b489584-d4d4j   1/1     Running   0             7m
web-demo-846b489584-wvv5s   1/1     Running   0             13m
```
2. Run the following command to create a file named share in the /data path of either pod: In this example, select the pod named web-demo-846b489584-d4d4j.
```
kubectl exec web-demo-846b489584-d4d4j --  touch /data/share
```
  Check the files in the /data path of the pod.
```
kubectl exec web-demo-846b489584-d4d4j -- ls /data
```
  Expected output:
```
share
static
```
3. Check whether the share file exists in the /data path of another pod (web-demo-846b489584-wvv5s) as well to verify data sharing.
```
kubectl exec web-demo-846b489584-wvv5s -- ls /data
```
  Expected output:
```
share
static
```
  After you create a file in the /data path of a pod, if the file is also created in the /data path of the other pod, the two pods share the same volume.

Related Operations

You can also perform the operations described in Table 6.

**Table 6** Related operations
Operation	Description	Procedure
Creating a storage volume (PV)	Create a PV on the CCE console.	In the navigation pane on the left, choose Storage. Then click the PVs tab. In the upper right corner, click Create PersistentVolume. In the displayed dialog box, configure the parameters. Volume Type: Select SFS Turbo. SFS Turbo: Click Select SFS Turbo. On the displayed page, select the SFS Turbo volume that meets the requirements and click OK. Subdirectory: Determine whether to use subdirectories to create PVs. Enter the absolute path of a subdirectory, for example, /a/b. Ensure that the subdirectory is available. PV Name: Enter the PV name, which must be unique in the same cluster. Access Mode: SFS volumes support only ReadWriteMany, indicating that a storage volume can be mounted to multiple nodes in read/write mode. For details, see Volume Access Modes. Reclaim Policy: Only Retain is supported if you do not use subdirectories. For details, see PV Reclaim Policy. If you choose to create a subdirectory, this parameter can only be set to Delete. Mount Options: Enter the mounting parameter key-value pairs. For details, see Configuring SFS Turbo Mount Options. Click Create.
Expanding the capacity of an SFS Turbo volume	Quickly expand the capacity of a mounted SFS Turbo volume on the CCE console.	In the navigation pane on the left, choose Storage. Then click the PVCs tab. Locate the target PVC and click More > Scale-out in the Operation column. Enter the capacity to be added and click OK.
Viewing events	You can view event names, event types, number of occurrences, Kubernetes events, first occurrence time, and last occurrence time of the PVC or PV.	In the navigation pane on the left, choose Storage. Then click the PVCs or PVs tab. Locate the target PVC or PV, click View Events in the Operation column to view events generated within one hour (events are retained for one hour).
Viewing a YAML file	You can view, copy, and download the YAML files of a PVC or PV.	In the navigation pane on the left, choose Storage. Then click the PVCs or PVs tab. Locate the target PVC or PV, click View YAML in the Operation column to view or download the YAML.

Parent Topic: SFS Turbo

Previous topic: SFS Turbo Volume Overview

Next topic: Configuring SFS Turbo Mount Options

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot