Help Center> Cloud Container Engine> API Reference> Kubernetes APIs> PersistentVolume> Creating a PersistentVolume
View PDF

Creating a PersistentVolume

Function

This API is used to create a PersistentVolume.

URI

POST /api/v1/persistentvolumes

Table 1 describes the parameters of this API.

Table 1 Parameter description

Parameter

Mandatory

Description

pretty

No

If 'true', then the output is pretty printed.

Request

Request parameters:

Table 2 describes the request parameters.

Table 2 Request parameter

Parameter

Mandatory

Type

Description

apiVersion

Yes

String

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values.

kind

Yes

String

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase.

metadata

Yes

metadata object

Standard object's metadata.

spec

Yes

spec object

Spec defines a specification of a persistent volume owned by the cluster. Provisioned by an administrator.

status

No

status object

Status represents the current information/status for the persistent volume. Populated by the system. Read-only.
Table 3 Data structure of the spec field

Parameter

Mandatory

Type

Description

accessModes

Yes

Array of strings

Access mode.

Options:

  • ReadWriteOnce: can be read and written by a single node.
  • ReadOnlyMany: can only be read by multiple nodes.
  • ReadWriteMany: can be read and written by multiple nodes.

capacity

Yes

Object

A description of the persistent volume's resources and capacity.

claimRef

No

claimRef object

ClaimRef is part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. claim. VolumeName is the authoritative bind between PV and PVC.

hostPath

No

hostPath object

HostPath represents a directory on the host. Provisioned by a developer or tester. This is useful for single-node development and testing only! On-host storage is not supported in any way and WILL NOT WORK in a multi-node cluster.

nfs

No

nfs object

NFS represents an NFS mount on the host. Provisioned by an admin.

persistentVolumeReclaimPolicy

No

String

What happens to a persistent volume when released from its claim. Valid options are Retain (default) and Recycle. Recycling must be supported by the volume plugin underlying this persistent volume.

storageClassName

No

String

Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass.

flexVolume

No

flexVolume

object

FlexVolume represents a generic volume resource that is

provisioned/attached using an exec based plugin. The cluster earlier than v1.15(v1.9/v1.11/v1.13) which use CCE FlexVolume fuxi driver must fill in this field.

CSI

No

CSI

object

CSI represents storage that is handled by an external CSI driver. The cluster of v1.15 or later which use CCE SCI everest must fill in this filed.
Table 4 Data structure of the status field

Parameter

Mandatory

Type

Description

message

No

String

A human-readable message indicating details about why the volume is in this state.

phase

No

String

Phase indicates if a volume is available, bound to a claim, or released by a claim.

reason

No

String

Reason is a brief CamelCase string that describes any failure and is meant for machine parsing and tidy display in the CLI.
Table 5 Data structure of the claimRef field

Parameter

Mandatory

Type

Description

apiVersion

No

String

API version of the referent.

fieldPath

No

String

If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.

kind

No

String

Kind of the referent.

name

No

String

Name of the referent.

namespace

No

String

Namespace of the referent.

resourceVersion

No

String

Specific resourceVersion to which this reference is made, if any.

uid

No

String

UID of the referent.
Table 6 Data structure of the hostPath field

Parameter

Mandatory

Type

Description

path

No

String

Path of the directory on the host.
Table 7 Data structure of the nfs field

Parameter

Mandatory

Type

Description

path

No

String

Path that is exported by the NFS server.

readOnly

No

Boolean

ReadOnly here will force the NFS export to be mounted with read-only permissions. Defaults to false.

server

No

String

Server is the hostname or IP address of the NFS server.
Table 8 Data structure of the flexVolume field

Name

Mandatory

Type

Description

driver

Yes

String

 
Driver is the name of the driver to use for this volume.
If the storage type is EVS, set this parameter to huawei.com/fuxivol.
If the storage type is SFS, set this parameter to huawei.com/fuxinfs.
If the storage type is OBS, set this parameter to huawei.com/fuxiobs.
If the storage type is SFS-Turboe, set this parameter to
huawei.com/fuxiefs

fsType

Yes

String

Required: Filesystem type to mount. Must be a filesystem type supported by the host operating system.

If the storage type is EVS, set this parameter to ext4.

If the storage type is SFS, set this parameter to nfs.

If the storage type is OBS, set this parameter to obs.

If the storage type is SFS-Turbo, set this parameter to efs.

options

No

map

Map of string keys and values that can be used to record extra command options. The option key values are shown below, in the table 10.
Table 9 Data structure of the options field

Name

Mandatory

Type

Description

disk-mode

No

String

This parameter is required only when the storage type is EVS, the value can be "SCSI" or "VBD".

fsType

Yes

String

If the storage type is EVS, set this parameter to ext4.

If the storage type is SFS, set this parameter to nfs.

If the storage type is OBS, set this parameter to s3fs.(≥v1.15)

If the storage type is OBS, set this parameter to obs.(≤v1.13)

If the storage type is SFS-Turbo, set this parameter to efs.

volumeID

Yes

String

For EVS/SFS/SFS Turbo storage, fill the ID of the IaaS resource; for OBS, fill the name of OBS.

storage_class

No

String

This parameter is required when the storage type is OBS, used to specify OBS type. If there is no obs type, set the default value "STANDARD".

OBS bucket type, standard storage (STANDARD), Low frequency access storage(WARM).

region

No

String

This parameter is required when the storage type is OBS, used to specify the region of OBS resource.

deviceMountPath

No

String

This parameter is required when the storage type is SFS or SFS Turbo, used to specify the shared path of IaaS resources.
Table 10 Data structure of the CSI field

Name

Mandatory

Type

Description

driver

Yes

String

 
Driver is the name of the driver to use for this volume.
If the storage type is EVS, set this parameter to disk.csi.everest.io.
If the storage type is SFS, set this parameter to nas.csi.everest.io.
If the storage type is OBS, set this parameter to obs.csi.everest.io.
If the storage type is SFS-Turboe, set this parameter to
sfsturbo.csi.everest.io.

fsType

Yes

String

Required: Filesystem type to mount. Must be a filesystem type supported by the host operating system.

If the storage type is EVS, set this parameter to ext4.

If the storage type is SFS, set this parameter to nfs.

If the storage type is OBS, set this parameter to s3fs/obsfs.

If the storage type is SFS-Turbo, set this parameter to nfs.

volumeAttributes

No

map

Map of string keys and values that can be used to record extra command options. The option key values are shown below, in the table 12.

volumeHandle

Yes

string

VolumeHandle is the unique volume name returned by the CSI volume plugin' s CreateVolume to refer to the volume on all subsequent calls. For EVS\SFS\SFS-Turbo, fill the ID of the iaas resource, for OBS, fill the name of obs.
Table 11 Data structure of the volumeAttributes field

Name

Mandatory

Type

Description

storage.kubernetes.io/csiProvisionerIdentity

Yes

String

For all storage classes, this parameter should be set to "Set everest-csi-provisioner".

everest.io/disk-mode

No

String

This parameter is required only when the storage type is EVS, the value can be "SCSI" or "VBD". But for everest, this value can only be set to "SCSI".

everest.io/disk-volume-type

No

String

This parameter is required only when the storage type is EVS,

used to specify the type of EVS disk to be used.

EVS disk type, high I/O (SAS), ultra-high I/O (SSD), or common I/O (SATA).

everest.io/obs-volume-type

No

String

This parameter is required when the storage type is OBS, used to specify OBS type. If there is no obs type, set the default value "STANDARD".

OBS bucket type, standard storage (STANDARD), Low frequency access storage(WARM).

everest.io/region

No

String

This parameter is required when the storage type is OBS, used to specify the region of OBS resource.

everest.io/share-export-location

No

String

This parameter is required when the storage type is SFS or SFS Turbo, used to specify the shared path of IaaS resources.

Example request:

The following is an example of a cluster of 1.15 or later:

{
    "apiVersion": "v1",
    "kind": "PersistentVolume",
    "metadata": {
        "annotations": {
            "pv.kubernetes.io/provisioned-by": "everest-csi-provisioner"
        },
        "labels": {
            "failure-domain.beta.kubernetes.io/region": "cn-north-4",
            "failure-domain.beta.kubernetes.io/zone": "cn-north-4a"
        },
        "name": "pvc-efe92ec5-fb39-4e17-bb26-c5d336ce5c14"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "capacity": {
            "storage": "20Gi"
        },
        "csi": {
            "driver": "disk.csi.everest.io",
            "fsType": "ext4",
            "volumeAttributes": {
                "everest.io/disk-mode": "SCSI",
                "everest.io/disk-volume-type": "SATA",
                "storage.kubernetes.io/csiProvisionerIdentity": "everest-csi-provisioner"
            },
            "volumeHandle": "9c44d068-42ab-4fcf-bb8f-1609823da5bb"
        },
        "persistentVolumeReclaimPolicy": "Delete",
        "storageClassName": "csi-disk"
    }
}

Example for clusters of version 1.13 or earlier:

{
  "apiVersion": "v1",
  "kind": "PersistentVolume",
  "metadata": {
    "labels": {
      "failure-domain.beta.kubernetes.io/region": "cn-north-4",
      "failure-domain.beta.kubernetes.io/zone": "cn-north-4a"
    },
    "annotations": {
      "pv.kubernetes.io/provisioned-by": "flexvolume-huawei.com/fuxivol"
    },
    "name": "pv-evs-example"
  },
  "spec": {
    "accessModes": [
      "ReadWriteMany"
    ],
    "capacity": {
      "storage": "10Gi"
    },
    "flexVolume": {
      "driver": "huawei.com/fuxivol",
      "fsType": "ext4",
      "options": {
        "disk-mode": "SCSI",
        "fsType": "ext4",
        "volumeID": "0992dbda-6340-470e-a74e-4f0db288ed82"
      }
    },
    "persistentVolumeReclaimPolicy": "Delete",
    "storageClassName": "sata"
  }
}

Response

Response parameters:

For the description about response parameters, see Table 2.

Example response:

The following is an example of a cluster of 1.15 or later:

{
    "apiVersion": "v1",
    "kind": "PersistentVolume",
    "metadata": {
        "annotations": {
            "pv.kubernetes.io/provisioned-by": "everest-csi-provisioner"
        },
        "creationTimestamp": "2020-01-08T02:00:31Z",
        "deletionGracePeriodSeconds": 0,
        "deletionTimestamp": "2020-01-13T02:04:12Z",
        "finalizers": [
            "everest-csi-attacher/disk-csi-everest-io"
        ],
        "labels": {
            "failure-domain.beta.kubernetes.io/region": "cn-north-4",
            "failure-domain.beta.kubernetes.io/zone": "cn-north-4a"
        },
        "name": "pvc-efe92ec5-fb39-4e17-bb26-c5d336ce5c14"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "capacity": {
            "storage": "20Gi"
        },
        "csi": {
            "driver": "disk.csi.everest.io",
            "fsType": "ext4",
            "volumeAttributes": {
                "everest.io/disk-mode": "SCSI",
                "everest.io/disk-volume-type": "SATA",
                "storage.kubernetes.io/csiProvisionerIdentity": "everest-csi-provisioner"
            },
            "volumeHandle": "9c44d068-42ab-4fcf-bb8f-1609823da5bb"
        },
        "persistentVolumeReclaimPolicy": "Delete",
        "storageClassName": "csi-disk",
        "volumeMode": "Filesystem"
    }
}

Example for clusters of version 1.13 or earlier:

{
    "kind": "PersistentVolume",
    "apiVersion": "v1",
    "metadata": {
        "name": "pv-test-02",
        "namespace": "default",
        "selfLink": "/api/v1/namespaces/default/persistentvolumes/pv-test-02",
        "uid": "98efd6aa-920a-11e8-81cc-fa163e49263c",
        "resourceVersion": "5672675",
        "creationTimestamp": "2018-07-28T02:04:44Z",
        "labels": {
            "failure-domain.beta.kubernetes.io/region": "cn-north-4",
            "failure-domain.beta.kubernetes.io/zone": "cn-north-4a",
            "name": "pv-test-02"
        },
        "annotations": {
            "volume.beta.kubernetes.io/storage-class": "sata",
            "volume.beta.kubernetes.io/storage-provisioner": "flexvolume-huawei.com/fuxivol"
        }
    },
    "spec": {
        "capacity": {
            "storage": "10Gi"
        },
        "hostPath": {
            "path": "/home",
            "type": ""
        },
        "accessModes": [
            "ReadWriteMany"
        ],
        "persistentVolumeReclaimPolicy": "Delete"
    },
    "status": {
        "phase": "Pending"
    }
}

Status Code

Table 12 describes the status code of this API.

Table 12 Status code

Status Code

Description

201

The request has been fulfilled, resulting in the creation of a new resource.

For the description about error status codes, see Status Code.

Parent topic: PersistentVolume