Help Center/ Cloud Container Engine/ User Guide/ Storage/ SFS/ Creating an SFS Subdirectory Using a Dynamic PV
Updated on 2025-09-04 GMT+08:00

Creating an SFS Subdirectory Using a Dynamic PV

When an SFS volume is mounted to a workload container, the root directory is mounted to the container by default. To properly use the storage capacity, CCE allows you to dynamically create an SFS subdirectory when creating a PVC so that different workloads can share one SFS volume.

Only general purpose file systems (SFS 3.0 Capacity-Oriented) support dynamic creation of subdirectories.

Prerequisites

  • You have created a cluster and installed the CCE Container Storage (Everest) add-on of v2.4.41 or later in the cluster.
  • To create a cluster using commands, ensure kubectl is used. For details, see Accessing a Cluster Using kubectl.
  • You have created an available SFS file system, and the SFS file system and the cluster are in the same VPC. Before using a general purpose file system (SFS 3.0 Capacity-Oriented) for storage, ensure a VPC endpoint has been created in the VPC where the cluster is located for the cluster to access the file system. For details, see Configuring a VPC Endpoint.

Dynamically Creating an SFS Subdirectory

CCE allows you to create SFS subdirectory PVCs via the console or kubectl based on the configured StorageClasses. After PVC creation, CCE dynamically allocates storage resources and mounts the PVCs to the specified workloads. To do so, perform the following operations.

  1. Log in to the CCE console and click the cluster name to access the cluster console.
  2. Choose Storage in the navigation pane. In the right pane, click the PVCs tab. Click Create PVC in the upper right corner. In the dialog box displayed, configure PVC parameters.

    Parameter

    Description

    PVC Type

    In this example, select SFS.

    PVC Name

    Enter the PVC name, which must be unique in a namespace.

    Creation Method

    Select New subdirectory.

    Storage Classes

    Select csi-sfs for SFS.

    You can customize a StorageClass and configure its reclaim policy and binding mode. For details, see Through the Console.

    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.

    File Storage

    Click Select SFS. On the displayed page, select the SFS file system that meets your requirements and click OK.

    Subdirectory

    Enter the absolute path of a subdirectory, for example, /a/b.

    Subdirectory Reclaim Policy

    Determine whether to retain subdirectories when a PVC is deleted.

    • Retain: When a PVC is deleted, the PV is deleted, but its associated subdirectories are retained.
    • Delete: When a PVC is deleted, the PV and its associated subdirectories are also deleted.
      NOTE:

      When a subdirectory is deleted, only the absolute path of the subdirectory specified in the PVC is deleted. The parent directory remains unchanged.

  3. Click Create to create a PVC and a PV.

    You can choose Storage in the navigation pane and view the created PVC and PV on the PVCs and PVs tab pages, respectively.

  1. Use kubectl to access the cluster.
  2. Create the pvc-sfs-subpath.yaml file.

    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: pvc-sfs-subpath    # PVC name
      namespace: default
      annotations:
        everest.io/csi.volume-as: absolute-path                # An SFS subdirectory is used.
        everest.io/csi.sfs30-name: <sfs_name>                    # Name of the SFS instance
        everest.io/csi.path: /a                                # Subdirectory that is automatically created, which must be an absolute path
        everest.io/csi.reclaim-policy: retain-volume-only      # When a PVC is deleted, the PV is deleted, but its associated subdirectories are retained.
    spec:
      accessModes:
        - ReadWriteMany      # ReadWriteMany must be selected for SFS.
      resources:
        requests:
          storage: 1Gi      # For SFS subdirectory PVCs, this configuration is only used for verification and must not be empty or 0.
      storageClassName: csi-sfs     # StorageClass name of a general purpose file system (SFS 3.0 Capacity-Oriented)
    Table 1 Key parameters

    Parameter

    Mandatory

    Description

    everest.io/csi.volume-as

    Yes

    When a dynamically created SFS subdirectory is used, the value of this parameter is consistently absolute-path.

    everest.io/csi.sfs30-name

    Yes

    An SFS instance name.

    everest.io/csi.path

    Yes

    Subdirectory that is automatically created, which must be an absolute path.

    everest.io/csi.reclaim-policy

    Yes

    Whether to retain subdirectories when deleting a PVC. This parameter must be used with PV Reclaim Policy. This parameter is available only when the PV reclaim policy is Delete. Options:

    • retain-volume-only: When a PVC is deleted, the PV is deleted, but its associated subdirectories are retained.
    • delete: When a PVC is deleted, the PV and its associated subdirectories are also deleted.
      NOTE:

      When a subdirectory is deleted, only the absolute path of the subdirectory specified in the PVC is deleted. The parent directory remains unchanged.

    storage

    Yes

    Requested capacity in the PVC, in Gi.

    This parameter is only used for verifying SFS subdirectory PVCs. The value cannot be empty or 0, and can be fixed at 1 because any value you set does not take effect.

  3. Run the following command to create a PVC:

    kubectl apply -f pvc-sfs-subpath.yaml

Helpful Links

If a storage volume fails to mount to a workload, rectify the fault by referring to What Should I Do If a Storage Volume Cannot Be Mounted or the Mounting Times Out?