Skip to content

OSDOCS-16945#CQA work Stor1 -- dynamic provisioning #106217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lpettyjo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

OSDOCS-16945#CQA work Stor1 -- dynamic provisioning #106217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 6 additions & 16 deletions modules/dynamic-provisioning-about.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,11 @@
[id="about_{context}"]
= About dynamic provisioning

The `StorageClass` resource object describes and classifies storage that can
be requested, as well as provides a means for passing parameters for
dynamically provisioned storage on demand. `StorageClass` objects can also
serve as a management mechanism for controlling different levels of
storage and access to the storage. Cluster Administrators (`cluster-admin`)
or Storage Administrators (`storage-admin`) define and create the
`StorageClass` objects that users can request without needing any detailed
knowledge about the underlying storage volume sources.
[role="_abstract"]
The `StorageClass` resource object describes and classifies storage that can be requested, as well as provides a means for passing parameters for dynamically provisioned storage on demand.
Comment thread
lpettyjo marked this conversation as resolved.

The {product-title} persistent volume framework enables this functionality
and allows administrators to provision a cluster with persistent storage.
The framework also gives users a way to request those resources without
having any knowledge of the underlying infrastructure.
`StorageClass` objects can also serve as a management mechanism for controlling different levels of storage and access to the storage. Cluster Administrators (`cluster-admin`)or Storage Administrators (`storage-admin`) define and create the `StorageClass` objects that users can request without needing any detailed knowledge about the underlying storage volume sources.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing space here:

Suggested change
`StorageClass` objects can also serve as a management mechanism for controlling different levels of storage and access to the storage. Cluster Administrators (`cluster-admin`)or Storage Administrators (`storage-admin`) define and create the `StorageClass` objects that users can request without needing any detailed knowledge about the underlying storage volume sources.
`StorageClass` objects can also serve as a management mechanism for controlling different levels of storage and access to the storage. Cluster Administrators (`cluster-admin`) or Storage Administrators (`storage-admin`) define and create the `StorageClass` objects that users can request without needing any detailed knowledge about the underlying storage volume sources.


Many storage types are available for use as persistent volumes in
{product-title}. While all of them can be statically provisioned by an
administrator, some types of storage are created dynamically using the
built-in provider and plugin APIs.
The {product-title} persistent volume framework enables this functionality and allows administrators to provision a cluster with persistent storage. The framework also gives users a way to request those resources without having any knowledge of the underlying infrastructure.

Many storage types are available for use as persistent volumes in {product-title}. While all of them can be statically provisioned by an administrator, some types of storage are created dynamically using the built-in provider and plugin APIs.
41 changes: 16 additions & 25 deletions modules/dynamic-provisioning-annotations.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,21 @@

:_mod-docs-content-type: PROCEDURE
[id="storage-class-annotations_{context}"]
= Storage class annotations
= Setting the default storage class

To set a storage class as the cluster-wide default, add
the following annotation to your storage class metadata:
[role="_abstract"]
To set a storage class as the cluster-wide default, you need to add an annotation to your storage class metadata.

[source,yaml]
----
storageclass.kubernetes.io/is-default-class: "true"
----
This enables any persistent volume claim (PVC) that does not specify a specific storage class to automatically be provisioned by the default storage class. While your cluster can have more than one storage class, only one can be the default storage class.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing I recently learned is that when we move our content to DITA, any prereqs will be placed in between the short description and any other intro content that precedes the .Procedure title. Here's a link for more info.

Not saying this needs to be addressed now, and the link specifically says not to move the prereqs yourself, but it might be worth considering whether intro content like this would stand on its own once a prereqs list was put between it and the short description.


For example:
.Prerequisites
* Logged in to a running {product-title} cluster with administrator privileges.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggesting a use of a pronoun for user focus here:

Suggested change
* Logged in to a running {product-title} cluster with administrator privileges.
* You are logged in to a running {product-title} cluster with administrator privileges.


.Procedure

. For your desired storage class, set the `metadata.annotations.storageclass.kubernetes.io/is-default-class` field to `true` as in the following example:
+
.Example storage class YAML file
[source,yaml]
----
apiVersion: storage.k8s.io/v1
Expand All @@ -26,27 +29,15 @@ metadata:
storageclass.kubernetes.io/is-default-class: "true"
...
----

This enables any persistent volume claim (PVC) that does not specify a
specific storage class to automatically be provisioned through the
default storage class. However, your cluster can have more than one storage class, but only one of them can be the default storage class.

+
[NOTE]
====
The beta annotation `storageclass.beta.kubernetes.io/is-default-class` is
still working; however, it will be removed in a future release.
The beta annotation `storageclass.beta.kubernetes.io/is-default-class` is still working; however, it will be removed in a future release.
====

To set a storage class description, add the following annotation
to your storage class metadata:

[source,yaml]
----
kubernetes.io/description: My Storage Class Description
----

For example:

. (Optional) Create a storage class description in the `metadata.annotations.kubernetes.io/description` field as in the following example:

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per the ISG there's a slightly different way to indicate optional steps:

Suggested change
. (Optional) Create a storage class description in the `metadata.annotations.kubernetes.io/description` field as in the following example:
. Optional: Create a storage class description in the `metadata.annotations.kubernetes.io/description` field as in the following example:

+
.Example storage class YAML file
[source,yaml]
----
apiVersion: storage.k8s.io/v1
Expand Down
24 changes: 11 additions & 13 deletions modules/dynamic-provisioning-available-plugins.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,14 @@
[id="available-plug-ins_{context}"]
= Available dynamic provisioning plugins

{product-title} provides the following provisioner plugins, which have
generic implementations for dynamic provisioning that use the cluster's
configured provider's API to create new storage resources:
[role="_abstract"]
{product-title} provides the following provisioner plugins, which have generic implementations for dynamic provisioning using the cluster's configured provider's API to create new storage resources.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think using "the following" is technically self referential to the doc, which we're supposed to avoid in short descriptions. It's probably fine to keep as is, but maybe it can be removed and perhaps even another sentence outside the short description could be added to introduce the table. Up to you:

Suggested change
{product-title} provides the following provisioner plugins, which have generic implementations for dynamic provisioning using the cluster's configured provider's API to create new storage resources.
{product-title} provides several provisioner plugins, which have generic implementations for dynamic provisioning using the cluster's configured provider's API to create new storage resources.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually I see now that some distros have only one plugin in the table, so if you do choose to remove "the following", it would be better not to use "several" in its place


[IMPORTANT]
====
Any chosen provisioner plugin also requires configuration for the relevant
cloud, host, or third-party provider as in the relevant documentation.
====

[options="header",cols="1,1,1"]
|===
Expand All @@ -25,7 +29,7 @@ ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

|{rh-openstack} Manila Container Storage Interface (CSI)
|`manila.csi.openstack.org`
|Once installed, the OpenStack Manila CSI Driver Operator and ManilaDriver automatically create the required storage classes for all available Manila share types needed for dynamic provisioning.
|After being installed, the OpenStack Manila CSI Driver Operator and ManilaDriver automatically create the required storage classes for all available Manila share types needed for dynamic provisioning.
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]

|Amazon Elastic Block Store (Amazon EBS)
Expand All @@ -49,8 +53,8 @@ ifndef::openshift-rosa,openshift-rosa-hcp[]
|GCE Persistent Disk (gcePD)
|`kubernetes.io/gce-pd`
|In multi-zone configurations, it is advisable to run one {product-title}
cluster per GCE project to avoid PVs from being created in zones where
no node in the current cluster exists.
cluster per GCE project to avoid persistent volumes (PVs) from being created in zones where
no node exists in the current cluster.

|{ibm-power-server-name} Block
|`powervs.csi.ibm.com`
Expand All @@ -70,7 +74,7 @@ endif::openshift-rosa,openshift-rosa-hcp[]
//|Storage orchestrator for NetApp ONTAP, SolidFire, and E-Series storage.

ifndef::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
|link:https://www.vmware.com/support/vsphere.html[VMware vSphere]
|VMware vSphere
|`kubernetes.io/vsphere-volume`
|
endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
Expand All @@ -81,9 +85,3 @@ endif::openshift-dedicated,openshift-rosa,openshift-rosa-hcp[]
//HPE Nimble Kube Storage Controller.

|===

[IMPORTANT]
====
Any chosen provisioner plugin also requires configuration for the relevant
cloud, host, or third-party provider as per the relevant documentation.
====
59 changes: 29 additions & 30 deletions modules/dynamic-provisioning-aws-definition.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,41 @@

:_mod-docs-content-type: REFERENCE
[id="aws-definition_{context}"]
= AWS Elastic Block Store (EBS) object definition
= AWS Elastic Block Store (EBS) StorageObject object definition

.aws-ebs-storageclass.yaml
[role="_abstract"]
The following is an example AWS Elastic Block Store (EBS) storage class object definition.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is also kind of self referential, is there some other way to rewrite this? Maybe a sentence describing the capability as the short description and then this introductory sentence can be a separate paragraph:

Suggested change
The following is an example AWS Elastic Block Store (EBS) storage class object definition.
You can define an AWS Elastic Block Store (EBS) storage class object.
The following is an example AWS EBS storage class object definition.


.Example AWS EBS storage class YAML file
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
name: <storage-class-name> <1>
name: <storage-class-name>
provisioner: ebs.csi.aws.com
parameters:
type: io1 <2>
iopsPerGB: "10" <3>
encrypted: "true" <4>
kmsKeyId: keyvalue <5>
fsType: ext4 <6>
type: io1
iopsPerGB: "10"
encrypted: "true"
kmsKeyId: keyvalue
fsType: ext4
----
<1> (required) Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
<2> (required) Select from `io1`, `gp3`, `sc1`, `st1`. The default is `gp3`.
See the
link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[AWS documentation]
for valid Amazon Resource Name (ARN) values.
<3> Optional: Only for *io1* volumes. I/O operations per second per GiB.
The AWS volume plugin multiplies this with the size of the requested
volume to compute IOPS of the volume. The value cap is 20,000 IOPS, which
is the maximum supported by AWS. See the
link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[AWS documentation]
for further details.
<4> Optional: Denotes whether to encrypt the EBS volume. Valid values
are `true` or `false`.
<5> Optional: The full ARN of the key to use when encrypting the volume.
If none is supplied, but `encypted` is set to `true`, then AWS generates a
key. See the
link:http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html[AWS documentation]
for a valid ARN value.
<6> Optional: File system that is created on dynamically provisioned
volumes. This value is copied to the `fsType` field of dynamically
provisioned persistent volumes and the file system is created when the
volume is mounted for the first time. The default value is `ext4`.
* `metadata.name`: Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.

* `parameters.type`: Select from `io1`, `gp3`, `sc1`, `st1`. The default is `gp3`. For valid Amazon Resource Name (ARN) values, see the AWS documentation, _Identify AWS resources with Amazon Resource Names (ARNs)_.

* Optional: `parameters.iopsPerGB`. Only for *io1* volumes. I/O operations per second per GiB.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Totally up to you, but for visual/structural consistency, how about making "Optional" its own sentence and starting with the parameter name?

Suggested change
* Optional: `parameters.iopsPerGB`. Only for *io1* volumes. I/O operations per second per GiB.
* `parameters.iopsPerGB`: Optional. Only for *io1* volumes. I/O operations per second per GiB.

Either way looks fine though, and if you make this change please apply the same update to all other optional list items here

+
The AWS volume plugin multiplies this with the size of the requested volume to compute IOPS of the volume. The maximum value is 20,000 IOPS, which
is the maximum supported by AWS.
+
For more information, see the AWS documentation, _Identify AWS resources with Amazon Resource Names (ARNs)_.

* Optional: `parameters.encrypted`. Indicates whether to encrypt the EBS volume. Valid values are `true` or `false`.

* Optional: `parameters.kmsKeyId`. The full ARN of the key to use when encrypting the volume. If none is supplied, but `encypted` is set to `true`, then AWS generates a key.
+
For valid ARN values, see the AWS documentation, _Identify AWS resources with Amazon Resource Names (ARNs)_.

* Optional: `parameters.fsType`. File system that is created on dynamically provisioned volumes. This value is copied to the `fsType` field of dynamically provisioned persistent volumes, and the file system is created when the volume is mounted for the first time. The default value is `ext4`.
40 changes: 23 additions & 17 deletions modules/dynamic-provisioning-azure-disk-definition.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,39 +4,45 @@

:_mod-docs-content-type: REFERENCE
[id="azure-disk-definition_{context}"]
= Azure Disk object definition
= Azure Disk StorageClass object definition

.azure-advanced-disk-storageclass.yaml
[role="_abstract"]
The following is an example Azure Disk storage class object definition.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same suggestion about making a generic-ish short description about the capability and saving the self referential language for another paragraph:

Suggested change
The following is an example Azure Disk storage class object definition.
You can define an Azure Disk storage class object.
The following is an example Azure Disk storage class object definition.

I see multiple other modules like this for other platforms, so I will stop commenting on each one and just say that if you choose to implement this feedback for one of these modules, please apply the same feedback to all the others in the PR


.Example Azure Disk storage class YAML file
[source,yaml]
----
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: <storage-class-name> <1>
name: <storage-class-name>
provisioner: kubernetes.io/azure-disk
volumeBindingMode: WaitForFirstConsumer <2>
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
parameters:
kind: Managed <3>
storageaccounttype: Premium_LRS <4>
kind: Managed
storageaccounttype: Premium_LRS
reclaimPolicy: Delete
----
<1> Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
<2> Using `WaitForFirstConsumer` is strongly recommended. This provisions the volume while allowing enough storage to schedule the pod on a free worker node from an available zone.
<3> Possible values are `Shared` (default), `Managed`, and `Dedicated`.
* `metadata.name`: Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.

* `volumeBindingMode`: Using `WaitForFirstConsumer` is strongly recommended. This provisions the volume while allowing enough storage to schedule the pod on a free worker node from an available zone.

* `parameters.kind`: Possible values are `Shared` (default), `Managed`, and `Dedicated`.
+
[IMPORTANT]
====
Red Hat only supports the use of `kind: Managed` in the storage class.
Red Hat only supports the use of `Managed`.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small nit:

Suggested change
Red Hat only supports the use of `Managed`.
Red{nbsp}Hat only supports the use of `Managed`.

@skopacz1 skopacz1 Feb 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another small nit is, per the ISG, to move "only" as close as possible to the phrase it modifies:

Suggested change
Red Hat only supports the use of `Managed`.
Red Hat supports only the use of `Managed`.


With `Shared` and `Dedicated`, Azure creates unmanaged disks, while {product-title} creates a managed disk for machine OS (root) disks. But because Azure Disk does not allow the use of both managed and unmanaged disks on a node, unmanaged disks created with `Shared` or `Dedicated` cannot be attached to {product-title} nodes.
====

<4> Azure storage account SKU tier. Default is empty. Note that Premium VMs can attach both `Standard_LRS` and `Premium_LRS` disks, Standard VMs can only attach `Standard_LRS` disks, Managed VMs can only attach managed disks, and unmanaged VMs can only attach unmanaged disks.
* `parameters.storageaccounttype`: Azure storage account SKU tier. Default is empty. Note that Premium VMs can attach both `Standard_LRS` and `Premium_LRS` disks. Standard VMs can only attach `Standard_LRS` disks. Managed VMs can only attach managed disks. Unmanaged VMs can only attach unmanaged disks.
+
.. If `kind` is set to `Shared`, Azure creates all unmanaged disks in a few shared storage accounts in the same resource group as the cluster.
.. If `kind` is set to `Managed`, Azure creates new managed disks.
.. If `kind` is set to `Dedicated` and a `storageAccount` is specified, Azure uses the specified storage account for the new unmanaged disk in the same resource group as the cluster. For this to work:
* The specified storage account must be in the same region.
* Azure Cloud Provider must have write access to the storage account.
.. If `kind` is set to `Dedicated` and a `storageAccount` is not specified, Azure creates a new dedicated storage account for the new unmanaged disk in the same resource group as the cluster.
** `Shared`: Azure creates all unmanaged disks in a few shared storage accounts in the same resource group as the cluster.

** `Managed`: Azure creates new managed disks.

** `Dedicated`, and a `storageAccount` is not specified: Azure creates a new dedicated storage account for the new unmanaged disk in the same resource group as the cluster.

** `Dedicated`, and a `storageAccount` is specified: Azure uses the specified storage account for the new unmanaged disk in the same resource group as the cluster. For this to work, the specified storage account must be in the same region, and Azure Cloud Provider must have write access to the storage account.
29 changes: 19 additions & 10 deletions modules/dynamic-provisioning-azure-file-considerations.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,36 +6,45 @@
[id="azure-file-considerations_{context}"]
= Considerations when using Azure File

The following file system features are not supported by the default Azure File storage class:
[role="_abstract"]
The default Azure File storage class does not support certain file system features.

The following features are not supported:

* Symlinks

* Hard links

* Extended attributes

* Sparse files

* Named pipes

Additionally, the owner user identifier (UID) of the Azure File mounted directory is different from the process UID of the container. The `uid` mount option can be specified in the `StorageClass` object to define
a specific user identifier to use for the mounted directory.
Additionally, the owner user identifier (UID) of the Azure File mounted directory is different from the process UID of the container. You can specify the `uid` mount option in the `StorageClass` object to define a specific user identifier to use for the mounted directory.

The following `StorageClass` object demonstrates modifying the user and group identifier, along with enabling symlinks for the mounted directory.
The following `StorageClass` object demonstrates modifying the `uid` and group identifier (`gid`), along with enabling symlinks for the mounted directory.

.Example Azure File storage class YAML file with modified `uid` and `gid`
[source,yaml]
----
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
name: azure-file
mountOptions:
- uid=1500 <1>
- gid=1500 <2>
- mfsymlinks <3>
- uid=1500
- gid=1500
- mfsymlinks
provisioner: kubernetes.io/azure-file
parameters:
location: eastus
skuName: Standard_LRS
reclaimPolicy: Delete
volumeBindingMode: Immediate
----
<1> Specifies the user identifier to use for the mounted directory.
<2> Specifies the group identifier to use for the mounted directory.
<3> Enables symlinks.
* `mountOptions.uid`: Specifies the user identifier to use for the mounted directory.

* `mountOptions.gid`: Specifies the group identifier to use for the mounted directory.

* `mountOptions.mfsymlinks`: Enables symlinks.
Loading