• Cloud Container Engine

cce
  1. Help Center
  2. Cloud Container Engine
  3. API Reference
  4. PersistentVolume (Native Kubernetes APIs)
  5. Creating a PersistentVolume

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

Table 11

Standard object's metadata.

spec

Yes

Table 3

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

status

No

Table 4

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

String Array

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

Table 5

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

Table 6

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.

NOTICE:

At least one of the following three parameters must be mandatory: hostPathnsf, and hwsElasticVolumeService. You have the option to choose which parameter will be mandatory.

nfs

No

Table 7

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

NOTICE:

At least one of the following three parameters must be mandatory: hostPathnsf, and hwsElasticVolumeService. You have the option to choose which parameter will be mandatory.

hwsElasticVolumeService

No

Table 8

hwsElasticVolumeService represents a Disk resource that is attached to a kubelet's host machine and then exposed to the pod.

NOTICE:
  • EVSs are AZ-specific and cannot be used cross AZs. Different EVSs must be created for different AZs.
  • At least one of the following three parameters must be mandatory: hostPathnsf, and hwsElasticVolumeService. You have the option to choose which parameter will be mandatory.

persistentVolumeReclaimPolicy

Yes

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

(A newly added parameter in Kubernetes 1.7)

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

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 hwsElasticVolumeService field

Name

Mandatory

Type

Description

volumeID

Yes

Array[string]

volume id used to identify the volume in evs

fsType

Yes

String

Required: Filesystem type to mount. Must be a filesystem type supported by the host operating system. Only ext3 and ext4 are allowed.

readOnly

No

Boolean

Optional: Defaults to false (read/write). ReadOnly here will force the ReadOnly setting in VolumeMounts.

Example request:

{
    "apiVersion": "v1",
    "kind": "PersistentVolume",
    "metadata": {
        "labels": {
            "name": "pv-test"
        },
        "name": "pv-test"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "capacity": {
            "storage": "1Gi"
        },
        "hostPath": {
            "path": "/home"
        },
        "persistentVolumeReclaimPolicy": "Recycle"
    }
}

Response

Response parameters:

For the description about response parameters, see Table 2.

Example response:

{
    "kind": "PersistentVolume",
    "apiVersion": "v1",
    "metadata": {
        "name": "pv-test",
        "namespace": "default",
        "selfLink": "/api/v1/namespaces/default/persistentvolumes/pv-test",
        "uid": "e174188f-ff21-11e7-855b-fa163eaf5675",
        "resourceVersion": "174229",
        "creationTimestamp": "2018-01-22T03:11:03Z",
        "labels": {
            "name": "pv-test"
        },
        "enable": true
    },
    "spec": {
        "capacity": {
            "storage": "1Gi"
        },
        "hostPath": {
            "path": "/home"
        },
        "accessModes": [
            "ReadWriteOnce"
        ],
        "persistentVolumeReclaimPolicy": "Recycle"
    },
    "status": {
        "phase": "Pending"
    }
}

Status Code

Table 9 describes the status code of this API.

Table 9 Status code

Status Code

Description

201

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

For the description about status codes, see Status Codes.