Skip to content

Commit 2b0fad4

Browse files
huffmancahuffmanca
authored
Merge pull request #13944 from huffmanca/OSDOCS-318
OSDOCS-318: Included introduction to Persistent Storage.
2 parents f7c6a36 + 3f7dea5 commit 2b0fad4

10 files changed

+707
-0
lines changed

‎_topic_map.yml

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,20 @@ Topics:
294294
- Name: Routing optimization
295295
File: routing-optimization
296296
---
297+
Name: Storage
298+
Dir: storage
299+
Distros: openshift-*
300+
Topics:
301+
- Name: Persistent storage
302+
File: understanding-persistent-storage
303+
- Name: Configuring persistent storage
304+
Dir: persistent-storage
305+
Topics:
306+
- Name: Persistent storage using AWS Elastic Block Store
307+
File: persistent-storage-aws
308+
- Name: Persistent Storage using iSCSI
309+
File: persistent-storage-iscsi
310+
---
297311
Name: Nodes
298312
Dir: nodes
299313
Distros: openshift-*

‎modules/storage-persistent-storage-block-volume-examples.adoc

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/understanding-persistent-storage.adoc
4+
//
5+
// This module should only be present in openshift-enterprise and
6+
// openshift-origin distributions.
7+
8+
[id='block-volume-examples-{context}']
9+
= Block volume examples
10+
11+
.PV example
12+
[source, yaml]
13+
----
14+
apiVersion: v1
15+
kind: PersistentVolume
16+
metadata:
17+
name: block-pv
18+
spec:
19+
capacity:
20+
storage: 10Gi
21+
accessModes:
22+
- ReadWriteOnce
23+
volumeMode: Block <1>
24+
persistentVolumeReclaimPolicy: Retain
25+
fc:
26+
targetWWNs: ["50060e801049cfd1"]
27+
lun: 0
28+
readOnly: false
29+
----
30+
<1> `volumeMode` field indicating that this PV is a raw block volume.
31+
32+
.PVC example
33+
[source, yaml]
34+
----
35+
apiVersion: v1
36+
kind: PersistentVolumeClaim
37+
metadata:
38+
name: block-pvc
39+
spec:
40+
accessModes:
41+
- ReadWriteOnce
42+
volumeMode: Block <1>
43+
resources:
44+
requests:
45+
storage: 10Gi
46+
----
47+
<1> `volumeMode` field indicating that a raw block PV is requested.
48+
49+
.Pod specification example
50+
[source, yaml]
51+
----
52+
apiVersion: v1
53+
kind: Pod
54+
metadata:
55+
name: pod-with-block-volume
56+
spec:
57+
containers:
58+
- name: fc-container
59+
image: fedora:26
60+
command: ["/bin/sh", "-c"]
61+
args: [ "tail -f /dev/null" ]
62+
volumeDevices: <1>
63+
- name: data
64+
devicePath: /dev/xvda <2>
65+
volumes:
66+
- name: data
67+
persistentVolumeClaim:
68+
claimName: block-pvc <3>
69+
----
70+
<1> `volumeDevices`, similar to `volumeMounts`, is used for block devices
71+
and can only be used with `PersistentVolumeClaim` sources.
72+
<2> `devicePath`, similar to `mountPath`, represents the path to the
73+
physical device.
74+
<3> The volume source must be of type `persistentVolumeClaim` and must
75+
match the name of the PVC as expected.
76+
77+
.Accepted values for `VolumeMode`
78+
[cols="1,2",options="header"]
79+
|===
80+
81+
|Value
82+
|Default
83+
84+
|Filesystem
85+
|Yes
86+
87+
|Block
88+
|No
89+
|===
90+
91+
.Binding scenarios for block volumes
92+
[cols="1,2,3",options="header"]
93+
|===
94+
95+
|PV VolumeMode
96+
|PVC VolumeMode
97+
|Binding Result
98+
99+
|Filesystem
100+
|Filesystem
101+
|Bind
102+
103+
|Unspecified
104+
|Unspecified
105+
|Bind
106+
107+
|Filesystem
108+
|Unspecified
109+
|Bind
110+
111+
|Unspecified
112+
|Filesystem
113+
|Bind
114+
115+
|Block
116+
|Block
117+
|Bind
118+
119+
|Unspecified
120+
|Block
121+
|No Bind
122+
123+
|Block
124+
|Unspecified
125+
|No Bind
126+
127+
|Filesystem
128+
|Block
129+
|No Bind
130+
131+
|Block
132+
|Filesystem
133+
|No Bind
134+
|===
135+
136+
[IMPORTANT]
137+
====
138+
Unspecified values result in the default value of *Filesystem*.
139+
====

‎modules/storage-persistent-storage-block-volume.adoc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/understanding-persistent-storage.adoc
4+
//
5+
// This module should only be present in openshift-enterprise and
6+
// openshift-origin distributions.
7+
8+
[id='block-volume-support-{context}']
9+
= Block volume support
10+
11+
You can statically provision raw block volumes by including API fields
12+
in your PV and PVC specifications. This functionality is only available for
13+
manually provisioned PVs.
14+
15+
To use block volume, you must first enable the `BlockVolume` feature gate.
16+
To enable the feature gates for master(s), add `feature-gates` to
17+
`apiServerArguments` and `controllerArguments`. To enable the feature
18+
gates fornode(s), add `feature-gates` to `kubeletArguments`. For example:
19+
20+
----
21+
kubeletArguments:
22+
feature-gates:
23+
- BlockVolume=true
24+
----

‎modules/storage-persistent-storage-lifecycle.adoc

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/understanding-persistent-storage.adoc
4+
5+
[id=lifecycle-volume-claim-{context}]
6+
= Lifecycle of a volume and claim
7+
8+
PVs are resources in the cluster. PVCs are requests for those resources
9+
and also act as claim checks to the resource. The interaction between PVs
10+
and PVCs have the following lifecycle.
11+
12+
[[provisioning]]
13+
== Provision storage
14+
15+
In response to requests from a developer defined in a PVC, a cluster
16+
administrator configures one or more dynamic provisioners that provision
17+
storage and a matching PV.
18+
19+
Alternatively, a cluster administrator can create a number of PVs in advance
20+
that carry the details of the real storage that is available for use. PVs
21+
exist in the API and are available for use.
22+
23+
[[binding]]
24+
== Bind claims
25+
26+
When you create a PVC, you request a specific amount of storage, specify the
27+
required access mode, and create a storage class to describe and classify
28+
the storage. The control loop in the master watches for new PVCs and binds
29+
the new PVC to an appropriate PV. If an appropriate PV does not exist, a
30+
provisioner for the storage class creates one.
31+
32+
The PV volume might exceed your requested volume. This is especially true
33+
with manually provisioned PVs. To minimize the excess, {product-title}
34+
binds to the smallest PV that matches all other criteria.
35+
36+
Claims remain unbound indefinitely if a matching volume does not exist or
37+
cannot be created with any available provisioner servicing a storage
38+
class. Claims are bound as matching volumes become available. For example,
39+
a cluster with many manually provisioned 50Gi volumes would not match a
40+
PVC requesting 100Gi. The PVC can be bound when a 100Gi PV is added to the
41+
cluster.
42+
43+
[[using]]
44+
== Use pods and claimed PVs
45+
46+
Pods use claims as volumes. The cluster inspects the claim to find the bound
47+
volume and mounts that volume for a pod. For those volumes that support
48+
multiple access modes, you must specify which mode applies when you use
49+
the claim as a volume in a pod.
50+
51+
Once you have a claim and that claim is bound, the bound PV belongs to you
52+
for as long as you need it. You can schedule pods and access claimed
53+
PVs by including `persistentVolumeClaim` in the pod's volumes block.
54+
55+
ifdef::openshift-origin,openshift-enterprise[]
56+
57+
[[pvcprotection]]
58+
== PVC protection
59+
60+
PVC protection is enabled by default.
61+
62+
endif::openshift-origin,openshift-enterprise[]
63+
64+
[[releasing]]
65+
== Release volumes
66+
67+
When you are finished with a volume, you can delete the PVC object from
68+
the API, which allows reclamation of the resource. The volume is
69+
considered released when the claim is deleted, but it is not yet available
70+
for another claim. The previous claimant's data remains on the volume and
71+
must be handled according to policy.
72+
73+
[[reclaiming]]
74+
== Reclaim volumes
75+
76+
The reclaim policy of a `PersistentVolume` tells the cluster what to do with
77+
the volume after it is released. Volumes reclaim policy can either be
78+
`Retain`, `Recycle`, or `Delete`.
79+
80+
`Retain` reclaim policy allows manual reclamation of the resource for
81+
those volume plug-ins that support it. `Delete` reclaim policy deletes
82+
both the `PersistentVolume` object from {product-title} and the associated
83+
storage asset in external infrastructure, such as AWS EBS, GCE PD, or
84+
Cinder volume.
85+
86+
[NOTE]
87+
====
88+
Dynamically provisioned volumes are always deleted.
89+
====
90+

‎modules/storage-persistent-storage-overview.adoc

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
// Module included in the following assemblies:
2+
//
3+
// storage/understanding-persistent-storage.adoc[leveloffset=+1]
4+
5+
[id=persistent-storage-overview-{context}]
6+
= Persistent Storage Overview
7+
8+
Managing storage is a distinct problem from managing compute resources.
9+
{product-title} uses the Kubernetes persistent volume (PV) framework to
10+
allow cluster administrators to provision persistent storage for a cluster.
11+
Developers can use persistent volume claims (PVCs) to request PV resources
12+
without having specific knowledge of the underlying storage infrastructure.
13+
14+
PVCs are specific to a project, and are created and used by developers as
15+
a means to use a PV. PV resources on their own are not scoped to any
16+
single project; they can be shared across the entire {product-title}
17+
cluster and claimed from any project. After a PV is bound to a PVC
18+
that PV cannot then be bound to additional PVCs. This has the effect of
19+
scoping a bound PV to a single namespace, that of the binding project.
20+
21+
PVs are defined by a `PersistentVolume` API object, which represents a
22+
piece of existing, networked storage in the cluster that was provisioned
23+
by the cluster administrator. It is a resource in the cluster just like a
24+
node is a cluster resource. PVs are volume plug-ins like `Volumes` but
25+
have a lifecycle that is independent of any individual pod that uses the
26+
PV. PV objects capture the details of the implementation of the storage,
27+
be that NFS, iSCSI, or a cloud-provider-specific storage system.
28+
29+
[IMPORTANT]
30+
====
31+
High availability of storage in the infrastructure is left to the underlying
32+
storage provider.
33+
====
34+
35+
PVCs are defined by a `PersistentVolumeClaim` API object, which represents a
36+
request for storage by a developer. It is similar to a pod in that pods
37+
consume node resources and PVCs consume PV resources. For example, pods
38+
can request specific levels of resources (e.g., CPU and memory), while
39+
PVCs can request specific storage capacity and access modes. For example,
40+
they can be mounted once read/write or many times read-only.

0 commit comments

Comments
 (0)