(Recommended) Creating an SFS Turbo Subdirectory Using a Dynamic PV

Prerequisites

• 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.
• You have created an available SFS Turbo file system that is in the same VPC as the cluster.

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.
• 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.
• Constraints on the subdirectory quota:
  • If the subdirectory quota is less than 1 GiB, it is automatically set to 1 GiB. The maximum quota cannot exceed the capacity of the target SFS Turbo file system. The minimum scale-out step is 1 GiB, and capacity reduction is not allowed.
  • Once a subdirectory quota is configured, it cannot be canceled.
  • The number of files or subdirectories in a file system is determined by the quota capacity (in KB) divided by 16. The upper limit is set at 1 billion and cannot be changed by users.

Using the Console

1. Log in to the CCE console and click the cluster name to access the cluster console.
2. 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	Select New subdirectory.
   Storage Class	Choose csi-sfsturbo.
   Access Mode	SFS Turbo volumes support only ReadWriteMany, indicating that a storage volume can be mounted to multiple pods in read/write mode. For details, see Volume Access Modes.
   SFS Turbo	Click Select SFS Turbo. On the displayed page, select the SFS Turbo file system that meets your requirements and click OK.
   Subdirectory	Enter the absolute path of a subdirectory, for example, /a/b. If the subdirectory does not exist, a subdirectory is automatically created.
   Subdirectory Reclaim Policy	Whether to retain subdirectories when a PVC is deleted. 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. 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.
   Subdirectory Capacity	Not limited: The subdirectory capacity is not limited. Limited: The subdirectory capacity is limited.
   Capacity	The maximum capacity of the subdirectory, in GiB. This parameter is available only when the subdirectory capacity limit is enabled.

3. 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.

4. Create a workload.
   1. In the navigation pane on the left, choose Workloads. Then click the Deployments tab.
   2. 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 Parameters for 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. tmp, for example, indicates 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
      

   3. 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

1. Use kubectl to connect to the cluster.
2. Create the pvc-sfsturbo-subpath.yaml file.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: pvc-sfsturbo-subpath    # PVC name.
     namespace: default
     annotations:
       everest.io/volume-as: absolute-path                # An SFS Turbo subdirectory is used.
       everest.io/sfsturbo-share-id: <sfsturbo_id>        # SFS Turbo ID.
       everest.io/path: /a                                # Subdirectory that is automatically created, which must be an absolute path.
       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.
   spec:
     accessModes:
       - ReadWriteMany      # ReadWriteMany must be selected for SFS Turbo.
     resources:
       requests:
         storage: 10Gi      # For SFS Turbo subdirectory PVCs, this configuration is meaningless and only used for verification (the value cannot be empty or 0) (the value cannot be empty or 0).
     storageClassName: csi-sfsturbo     # Storage class name of the SFS Turbo volume.

   Table 2 Key parameters

   Parameter	Mandatory	Description
   everest.io/volume-as	No	The value is fixed at absolute-path, indicating that a dynamically created SFS Turbo subdirectory is used.
   everest.io/sfsturbo-share-id	No	SFS Turbo 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/path	No	Subdirectory that is automatically created, which must be an absolute path.
   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.
   storage	Yes	Requested capacity in the PVC, in Gi. For dynamically created subdirectories using a PVC: You can specify the subdirectory capacity. If subdirectory capacity is not limited, this parameter is meaningless and is used only for verification. You can set this parameter to a fixed value 10Gi.
   everest.io/csi.enable-sfsturbo-dir-quota	No	Whether to limit the subdirectory capacity. If the value is set to true, the subdirectory capacity is limited. If the value is empty or set to any other value, the subdirectory capacity is not limited.

3. Run the following command to create a PVC:

   kubectl apply -f pvc-sfsturbo-subpath.yaml

4. Create a workload.
   1. 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-subpath    # PVC name.
   2. 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 verify it by referring to the procedure in Verifying Data Persistence and Sharing.

Verifying Data Persistence and Sharing

1. View the deployed application and files.
   1. Run the following command to view the pods:

      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.

2. Run the following command to create a file named static in the /data path:

   kubectl exec web-demo-846b489584-mjhm9 --  touch /data/static

3. Run the following command to view the created file in the /data path:

   kubectl exec web-demo-846b489584-mjhm9 -- ls /data

   Expected output:

   static

4. 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 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 file in the /data path of the new pod has been modified:

      kubectl exec web-demo-846b489584-d4d4j -- ls /data

      Expected output:

      static

      The static file is retained, indicating that the data can be stored persistently.

5. Verify data sharing.
   1. Run the following command to view the 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