Documentation for volume scheduling alpha feature
This commit is contained in:
Michelle Au
@@ -7,18 +7,18 @@ approvers:
|
||||
title: Persistent Volumes
|
||||
---
|
||||
|
||||
This document describes the current state of `PersistentVolumes` in Kubernetes. Familiarity with [volumes](/docs/concepts/storage/volumes/) is suggested.
|
||||
This document describes the current state of `PersistentVolumes` in Kubernetes. Familiarity with [volumes](/docs/concepts/storage/volumes/) is suggested.
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
|
||||
## Introduction
|
||||
|
||||
Managing storage is a distinct problem from managing compute. The `PersistentVolume` subsystem provides an API for users and administrators that abstracts details of how storage is provided from how it is consumed. To do this we introduce two new API resources: `PersistentVolume` and `PersistentVolumeClaim`.
|
||||
Managing storage is a distinct problem from managing compute. The `PersistentVolume` subsystem provides an API for users and administrators that abstracts details of how storage is provided from how it is consumed. To do this we introduce two new API resources: `PersistentVolume` and `PersistentVolumeClaim`.
|
||||
|
||||
A `PersistentVolume` (PV) is a piece of storage in the cluster that has been provisioned by an administrator. It is a resource in the cluster just like a node is a cluster resource. PVs are volume plugins like Volumes, but have a lifecycle independent of any individual pod that uses the PV. This API object captures the details of the implementation of the storage, be that NFS, iSCSI, or a cloud-provider-specific storage system.
|
||||
A `PersistentVolume` (PV) is a piece of storage in the cluster that has been provisioned by an administrator. It is a resource in the cluster just like a node is a cluster resource. PVs are volume plugins like Volumes, but have a lifecycle independent of any individual pod that uses the PV. This API object captures the details of the implementation of the storage, be that NFS, iSCSI, or a cloud-provider-specific storage system.
|
||||
|
||||
A `PersistentVolumeClaim` (PVC) is a request for storage by a user. It is similar to a pod. Pods consume node resources and PVCs consume PV resources. Pods can request specific levels of resources (CPU and Memory). Claims can request specific size and access modes (e.g., can be mounted once read/write or many times read-only).
|
||||
A `PersistentVolumeClaim` (PVC) is a request for storage by a user. It is similar to a pod. Pods consume node resources and PVCs consume PV resources. Pods can request specific levels of resources (CPU and Memory). Claims can request specific size and access modes (e.g., can be mounted once read/write or many times read-only).
|
||||
|
||||
While `PersistentVolumeClaims` allow a user to consume abstract storage
|
||||
resources, it is common that users need `PersistentVolumes` with varying
|
||||
@@ -33,14 +33,14 @@ Please see the [detailed walkthrough with working examples](/docs/tasks/configur
|
||||
|
||||
## Lifecycle of a volume and claim
|
||||
|
||||
PVs are resources in the cluster. PVCs are requests for those resources and also act as claim checks to the resource. The interaction between PVs and PVCs follows this lifecycle:
|
||||
PVs are resources in the cluster. PVCs are requests for those resources and also act as claim checks to the resource. The interaction between PVs and PVCs follows this lifecycle:
|
||||
|
||||
### Provisioning
|
||||
|
||||
There are two ways PVs may be provisioned: statically or dynamically.
|
||||
|
||||
#### Static
|
||||
A cluster administrator creates a number of PVs. They carry the details of the real storage which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption.
|
||||
A cluster administrator creates a number of PVs. They carry the details of the real storage which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption.
|
||||
|
||||
#### Dynamic
|
||||
When none of the static PVs the administrator created matches a user's `PersistentVolumeClaim`,
|
||||
@@ -60,13 +60,13 @@ please check [kube-apiserver](/docs/admin/kube-apiserver/) documentation.
|
||||
|
||||
### Binding
|
||||
|
||||
A user creates, or has already created in the case of dynamic provisioning, a `PersistentVolumeClaim` with a specific amount of storage requested and with certain access modes. A control loop in the master watches for new PVCs, finds a matching PV (if possible), and binds them together. If a PV was dynamically provisioned for a new PVC, the loop will always bind that PV to the PVC. Otherwise, the user will always get at least what they asked for, but the volume may be in excess of what was requested. Once bound, `PersistentVolumeClaim` binds are exclusive, regardless of the mode used to bind them.
|
||||
A user creates, or has already created in the case of dynamic provisioning, a `PersistentVolumeClaim` with a specific amount of storage requested and with certain access modes. A control loop in the master watches for new PVCs, finds a matching PV (if possible), and binds them together. If a PV was dynamically provisioned for a new PVC, the loop will always bind that PV to the PVC. Otherwise, the user will always get at least what they asked for, but the volume may be in excess of what was requested. Once bound, `PersistentVolumeClaim` binds are exclusive, regardless of how they were bound. A PVC to PV binding is a one-to-one mapping.
|
||||
|
||||
Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.
|
||||
Claims will remain unbound indefinitely if a matching volume does not exist. Claims will be bound as matching volumes become available. For example, a cluster provisioned with many 50Gi PVs would not match a PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the cluster.
|
||||
|
||||
### Using
|
||||
|
||||
Pods use claims as volumes. The cluster inspects the claim to find the bound volume and mounts that volume for a pod. For volumes which support multiple access modes, the user specifies which mode desired when using their claim as a volume in a pod.
|
||||
Pods use claims as volumes. The cluster inspects the claim to find the bound volume and mounts that volume for a pod. For volumes which support multiple access modes, the user specifies which mode desired when using their claim as a volume in a pod.
|
||||
|
||||
Once a user has a claim and that claim is bound, the bound PV belongs to the user for as long as they need it. Users schedule Pods and access their claimed PVs by including a persistentVolumeClaim in their Pod's volumes block. [See below for syntax details](#claims-as-volumes).
|
||||
|
||||
|
||||
@@ -78,6 +78,7 @@ for provisioning PVs. This field must be specified.
|
||||
| PortworxVolume | ✓ | [Portworx Volume](#portworx-volume) |
|
||||
| ScaleIO | ✓ | [ScaleIO](#scaleio) |
|
||||
| StorageOS | ✓ | [StorageOS](#storageos) |
|
||||
| Local | - | [Local](#local) |
|
||||
|
||||
You are not restricted to specifying the "internal" provisioners
|
||||
listed here (whose names are prefixed with "kubernetes.io" and shipped
|
||||
@@ -634,3 +635,22 @@ Secrets used for dynamically provisioned volumes may be created in any namespace
|
||||
and referenced with the `adminSecretNamespace` parameter. Secrets used by
|
||||
pre-provisioned volumes must be created in the same namespace as the PVC that
|
||||
references it.
|
||||
|
||||
#### Local
|
||||
|
||||
{% assign for_k8s_version="v1.9" %}{% include feature-state-alpha.md %}
|
||||
|
||||
This feature requires the `VolumeScheduling` feature gate to be enabled.
|
||||
|
||||
```yaml
|
||||
kind: StorageClass
|
||||
apiVersion: storage.k8s.io/v1
|
||||
metadata:
|
||||
name: local-fast
|
||||
provisioner: kubernetes.io/no-provisioner
|
||||
volumeBindingMode: WaitForFirstConsumer
|
||||
```
|
||||
|
||||
Local volumes do not support dynamic provisioning yet, however a StorageClass
|
||||
should still be created to delay volume binding until pod scheduling. This is
|
||||
specified by the `WaitForFirstConsumer` volume binding mode.
|
||||
|
||||
@@ -434,7 +434,13 @@ See the [iSCSI example](https://github.com/kubernetes/examples/tree/{{page.githu
|
||||
|
||||
### local
|
||||
|
||||
This volume type is alpha in 1.7.
|
||||
{% assign for_k8s_version="v1.7" %}{% include feature-state-alpha.md %}
|
||||
|
||||
This alpha feature requires the `PersistentLocalVolumes` feature gate to be
|
||||
enabled.
|
||||
|
||||
**Note:** Starting in 1.9, the `VolumeScheduling` feature gate must also be enabled.
|
||||
{: .note}
|
||||
|
||||
A `local` volume represents a mounted local storage device such as a disk,
|
||||
partition or directory.
|
||||
@@ -443,7 +449,7 @@ Local volumes can only be used as a statically created PersistentVolume.
|
||||
|
||||
Compared to HostPath volumes, local volumes can be used in a durable manner
|
||||
without manually scheduling pods to nodes, as the system is aware of the volume's
|
||||
node constraints.
|
||||
node constraints by looking at the node affinity on the PersistentVolume.
|
||||
|
||||
However, local volumes are still subject to the availability of the underlying
|
||||
node and are not suitable for all applications.
|
||||
@@ -481,6 +487,13 @@ spec:
|
||||
**Note:** The local PersistentVolume cleanup and deletion requires manual intervention without the external provisioner.
|
||||
{: .note}
|
||||
|
||||
Starting in 1.9, local volume binding can be delayed until pod scheduling by
|
||||
creating a StorageClass with `volumeBindingMode` set to `WaitForFirstConsumer`.
|
||||
See the [example](storage-classes.md#local). Delaying volume binding ensures
|
||||
that the volume binding decision will also be evaluated with any other node
|
||||
constraints the pod may have, such as node resource requirements, node
|
||||
selectors, pod affinity, and pod anti-affinity.
|
||||
|
||||
For details on the `local` volume type, see the [Local Persistent Storage
|
||||
user guide](https://github.com/kubernetes-incubator/external-storage/tree/master/local-volume).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user