Add section on storage classes to PV doc #1064
Conversation
wongma7
force-pushed
the
storage-class
branch
3 times, most recently
from
ecc7d33
to
2ab60ac
Compare
| @@ -20,6 +20,19 @@ A `PersistentVolume` (PV) is a piece of networked storage in the cluster that ha | |||
|
|
|||
| 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). | |||
|
|
|||
| Administrators often need to offer and provision a variety of | |||
There was a problem hiding this comment.
These paragraphs seem out of place. Maybe a better transition from the previously ideas would help?
There was a problem hiding this comment.
Maybe intro with:
While PersistentVolumeClaims allow a user to consume abstract storage resources, it is common that users need PersistentVolumes with varying properties, such as performance, for different problems. Cluster administrators need to be able to offer a variety of PersistentVolumes that differ in more ways than just size and access modes, without exposing users to the details of how those volumes are implemented. For these needs there is the StorageClass resource.
|
|
||
| ### Provisioner | ||
| Storage classes have a provisioner that determines what volume plugin is used | ||
| for provisioning PVs. This field must be specified. The available provisioner |
|
IMO, StorageClasses and PVCs and PVs are more entangled together than it was before and the page should reflect it. E.g. chapter Provisioning should mention both static and dynamic provisioning and how class on PVC influences that, especially that pvc.class="" effectively disables dynamic provisioning. Chapter Persistent Volumes should mention also class attribute/annotation Chapter PersistentVolumeClaims should mention also class attribute/annotation |
| ``` | ||
|
|
||
| * `type`: `io1`, `gp2`, `sc1`, `st1`. See AWS docs for details. Default: `gp2`. | ||
| * `zone`: AWS zone. If not specified, a random zone in the same region as |
There was a problem hiding this comment.
actually, it's not "random zone in the same region", it's "a random zone where this Kubernetes cluster has a node". I'll update kubernetes/examples/experimental/persistent-volume-provisioning.
There was a problem hiding this comment.
@jsafrane is this the same for gce?
|
I moved the defaulting but kept a little sentence under StorageClasses. Is it redundant given that the linked section is right above it? Still need to talk about dynamic provisioning throughout the page, as you say...I think right now it feels like it's an afterthought at the bottom of the page. (just wondering is spec.class going to be a mandatory field?) also in case this gets missed: I added this sentence 'This means that the PVs those PVCs would normally be bound to, the PVs that have no class (no annotation or annotation equal to ""), cannot be bound to any PVC. ' this is true and worth saying, right? edit: sorry for the weird commits |
| be bound to the PVC. | ||
|
|
||
| PVCs don't necessarily have to request a class, they can omit the annotation or | ||
| set it to `""`. The cluster treats PVCs that don't request a class differently |
There was a problem hiding this comment.
It's slightly more complicated.
- Missing class annotation in PVC means "I don't care about the class" and defaulting in the admission controller happens, i.e. the user gets the default class.
- If there is no default storage class set or the admission controller is not running, a classless PV is then requested (see below).
- Class annotation set to "" means that the PVC requests PV with class="" or missing annotation, i.e. a classless PV. That's the only way to get a PV with no/empty class.
| can only be bound to PVs with no class (no annotation or one set equal to | ||
| `""`). A PVC with no annotation is not quite the same and is treated differently | ||
| by the cluster depending on whether the | ||
| [`SimpleDefaultStorageClassForPVC` admission controller](docs/admin/admission-controllers/#simpledefaultstorageclassforpvc) |
There was a problem hiding this comment.
it's now DefaultStorageClass. And it's not "admission controller", but officially it is "admission plugin"
|
@wongma7, great work so far, now it looks much better than before. I have only couple of comments above. |
|
Admission controller got merged - please update this PR |
| iopsPerGB: "10" | ||
| ``` | ||
|
|
||
| * `type`: `io1`, `gp2`, `sc1`, `st1`. See AWS docs for details. Default: `gp2`. |
There was a problem hiding this comment.
we need a huge link to AWS docs (http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html) is necessary, rules about available sizes and types (and IOPS) are quite complicated.
|
I added this sentence: nvm, I see kubernetes/kubernetes#31243 |
|
@jaredbhatti @devin-donnelly @kubernetes/docs |
|
This looks more or less fine from a docs standpoint. |
Signed-off-by: William Morgan <william@buoyant.io>
For kubernetes/kubernetes#29006 & kubernetes/enhancements#36
edit: oops, reopening against 1.4 :)This change is