Postinstallation storage configuration

After installing OKD, you can further expand and customize your cluster to your requirements, including storage configuration.

Dynamic provisioning

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.

The OKD 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 OKD. 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.

Available dynamic provisioning plugins

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

Storage typeProvisioner plugin nameNotes

OpenStack Cinder

kubernetes.io/cinder

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.

Amazon Elastic Block Store (Amazon EBS)

kubernetes.io/aws-ebs

For dynamic provisioning when using multiple clusters in different zones, tag each node with Key=kubernetes.io/cluster/<cluster_name>,Value=<cluster_id> where <cluster_name> and <cluster_id> are unique per cluster.

Azure Disk

kubernetes.io/azure-disk

Azure File

kubernetes.io/azure-file

The persistent-volume-binder service account requires permissions to create and get secrets to store the Azure storage account and keys.

GCE Persistent Disk (gcePD)

kubernetes.io/gce-pd

In multi-zone configurations, it is advisable to run one OKD cluster per GCE project to avoid PVs from being created in zones where no node in the current cluster exists.

IBM Power® Virtual Server Block

powervs.csi.ibm.com

After installation, the IBM Power® Virtual Server Block CSI Driver Operator and IBM Power® Virtual Server Block CSI Driver automatically create the required storage classes for dynamic provisioning.

VMware vSphere

kubernetes.io/vsphere-volume

Any chosen provisioner plugin also requires configuration for the relevant cloud, host, or third-party provider as per the relevant documentation.

Defining a storage class

StorageClass objects are currently a globally scoped object and must be created by cluster-admin or storage-admin users.

The Cluster Storage Operator might install a default storage class depending on the platform in use. This storage class is owned and controlled by the Operator. It cannot be deleted or modified beyond defining annotations and labels. If different behavior is desired, you must define a custom storage class.

The following sections describe the basic definition for a StorageClass object and specific examples for each of the supported plugin types.

Basic StorageClass object definition

The following resource shows the parameters and default values that you use to configure a storage class. This example uses the AWS ElasticBlockStore (EBS) object definition.

Sample StorageClass definition

  1. kind: StorageClass (1)
  2. apiVersion: storage.k8s.io/v1 (2)
  3. metadata:
  4. name: <storage-class-name> (3)
  5. annotations: (4)
  6. storageclass.kubernetes.io/is-default-class: 'true'
  7. ...
  8. provisioner: kubernetes.io/aws-ebs (5)
  9. parameters: (6)
  10. type: gp3
  11. ...
1(required) The API object type.
2(required) The current apiVersion.
3(required) The name of the storage class.
4(optional) Annotations for the storage class.
5(required) The type of provisioner associated with this storage class.
6(optional) The parameters required for the specific provisioner, this will change from plugin to plug-iin.

Storage class annotations

To set a storage class as the cluster-wide default, add the following annotation to your storage class metadata:

  1. storageclass.kubernetes.io/is-default-class: "true"

For example:

  1. apiVersion: storage.k8s.io/v1
  2. kind: StorageClass
  3. metadata:
  4. annotations:
  5. storageclass.kubernetes.io/is-default-class: "true"
  6. ...

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.

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:

  1. kubernetes.io/description: My Storage Class Description

For example:

  1. apiVersion: storage.k8s.io/v1
  2. kind: StorageClass
  3. metadata:
  4. annotations:
  5. kubernetes.io/description: My Storage Class Description
  6. ...

OpenStack Cinder object definition

cinder-storageclass.yaml

  1. kind: StorageClass
  2. apiVersion: storage.k8s.io/v1
  3. metadata:
  4. name: <storage-class-name> (1)
  5. provisioner: kubernetes.io/cinder
  6. parameters:
  7. type: fast (2)
  8. availability: nova (3)
  9. fsType: ext4 (4)
1Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
2Volume type created in Cinder. Default is empty.
3Availability Zone. If not specified, volumes are generally round-robined across all active zones where the OKD cluster has a node.
4File 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.

AWS Elastic Block Store (EBS) object definition

aws-ebs-storageclass.yaml

  1. kind: StorageClass
  2. apiVersion: storage.k8s.io/v1
  3. metadata:
  4. name: <storage-class-name> (1)
  5. provisioner: kubernetes.io/aws-ebs
  6. parameters:
  7. type: io1 (2)
  8. iopsPerGB: "10" (3)
  9. encrypted: "true" (4)
  10. kmsKeyId: keyvalue (5)
  11. fsType: ext4 (6)
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 AWS documentation for valid Amazon Resource Name (ARN) values.
3Optional: 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 AWS documentation for further details.
4Optional: Denotes whether to encrypt the EBS volume. Valid values are true or false.
5Optional: 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 AWS documentation for a valid ARN value.
6Optional: 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.

Azure Disk object definition

azure-advanced-disk-storageclass.yaml

  1. apiVersion: storage.k8s.io/v1
  2. kind: StorageClass
  3. metadata:
  4. name: <storage-class-name> (1)
  5. provisioner: kubernetes.io/azure-disk
  6. volumeBindingMode: WaitForFirstConsumer (2)
  7. allowVolumeExpansion: true
  8. parameters:
  9. kind: Managed (3)
  10. storageaccounttype: Premium_LRS (4)
  11. reclaimPolicy: Delete
1Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
2Using 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.
3Possible values are Shared (default), Managed, and Dedicated.

Red Hat only supports the use of kind: Managed in the storage class.

With Shared and Dedicated, Azure creates unmanaged disks, while OKD 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 OKD nodes.

4Azure 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.
  1. 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.

  2. If kind is set to Managed, Azure creates new managed disks.

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

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

Azure File object definition

The Azure File storage class uses secrets to store the Azure storage account name and the storage account key that are required to create an Azure Files share. These permissions are created as part of the following procedure.

Procedure

  1. Define a ClusterRole object that allows access to create and view secrets:

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: ClusterRole
    3. metadata:
    4. # name: system:azure-cloud-provider
    5. name: <persistent-volume-binder-role> (1)
    6. rules:
    7. - apiGroups: ['']
    8. resources: ['secrets']
    9. verbs: ['get','create']
    1The name of the cluster role to view and create secrets.
  2. Add the cluster role to the service account:

    1. $ oc adm policy add-cluster-role-to-user <persistent-volume-binder-role> system:serviceaccount:kube-system:persistent-volume-binder
  3. Create the Azure File StorageClass object:

    1. kind: StorageClass
    2. apiVersion: storage.k8s.io/v1
    3. metadata:
    4. name: <azure-file> (1)
    5. provisioner: kubernetes.io/azure-file
    6. parameters:
    7. location: eastus (2)
    8. skuName: Standard_LRS (3)
    9. storageAccount: <storage-account> (4)
    10. reclaimPolicy: Delete
    11. volumeBindingMode: Immediate
    1Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
    2Location of the Azure storage account, such as eastus. Default is empty, meaning that a new Azure storage account will be created in the OKD cluster’s location.
    3SKU tier of the Azure storage account, such as Standard_LRS. Default is empty, meaning that a new Azure storage account will be created with the Standard_LRS SKU.
    4Name of the Azure storage account. If a storage account is provided, then skuName and location are ignored. If no storage account is provided, then the storage class searches for any storage account that is associated with the resource group for any accounts that match the defined skuName and location.

Considerations when using Azure File

The following file system features are not supported by the default Azure File storage class:

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

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

  1. kind: StorageClass
  2. apiVersion: storage.k8s.io/v1
  3. metadata:
  4. name: azure-file
  5. mountOptions:
  6. - uid=1500 (1)
  7. - gid=1500 (2)
  8. - mfsymlinks (3)
  9. provisioner: kubernetes.io/azure-file
  10. parameters:
  11. location: eastus
  12. skuName: Standard_LRS
  13. reclaimPolicy: Delete
  14. volumeBindingMode: Immediate
1Specifies the user identifier to use for the mounted directory.
2Specifies the group identifier to use for the mounted directory.
3Enables symlinks.

GCE PersistentDisk (gcePD) object definition

gce-pd-storageclass.yaml

  1. apiVersion: storage.k8s.io/v1
  2. kind: StorageClass
  3. metadata:
  4. name: <storage-class-name> (1)
  5. provisioner: kubernetes.io/gce-pd
  6. parameters:
  7. type: pd-standard (2)
  8. replication-type: none
  9. volumeBindingMode: WaitForFirstConsumer
  10. allowVolumeExpansion: true
  11. reclaimPolicy: Delete
1Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
2Select either pd-standard or pd-ssd. The default is pd-standard.

VMware vSphere object definition

vsphere-storageclass.yaml

  1. kind: StorageClass
  2. apiVersion: storage.k8s.io/v1
  3. metadata:
  4. name: <storage-class-name> (1)
  5. provisioner: csi.vsphere.vmware.com (2)
1Name of the storage class. The persistent volume claim uses this storage class for provisioning the associated persistent volumes.
2For more information about using VMware vSphere CSI with OKD, see the Kubernetes documentation.

Changing the default storage class

Use the following procedure to change the default storage class.

For example, if you have two defined storage classes, gp3 and standard, and you want to change the default storage class from gp3 to standard.

Prerequisites

  • Access to the cluster with cluster-admin privileges.

Procedure

To change the default storage class:

  1. List the storage classes:

    1. $ oc get storageclass

    Example output

    1. NAME TYPE
    2. gp3 (default) kubernetes.io/aws-ebs (1)
    3. standard kubernetes.io/aws-ebs
    1(default) indicates the default storage class.
  2. Make the desired storage class the default.

    For the desired storage class, set the storageclass.kubernetes.io/is-default-class annotation to true by running the following command:

    1. $ oc patch storageclass standard -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "true"}}}'

    You can have multiple default storage classes for a short time. However, you should ensure that only one default storage class exists eventually.

    With multiple default storage classes present, any persistent volume claim (PVC) requesting the default storage class (pvc.spec.storageClassName=nil) gets the most recently created default storage class, regardless of the default status of that storage class, and the administrator receives an alert in the alerts dashboard that there are multiple default storage classes, MultipleDefaultStorageClasses.

  3. Remove the default storage class setting from the old default storage class.

    For the old default storage class, change the value of the storageclass.kubernetes.io/is-default-class annotation to false by running the following command:

    1. $ oc patch storageclass gp3 -p '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}'
  4. Verify the changes:

    1. $ oc get storageclass

    Example output

    1. NAME TYPE
    2. gp3 kubernetes.io/aws-ebs
    3. standard (default) kubernetes.io/aws-ebs

Optimizing storage

Optimizing storage helps to minimize storage use across all resources. By optimizing storage, administrators help ensure that existing storage resources are working in an efficient manner.

Available persistent storage options

Understand your persistent storage options so that you can optimize your OKD environment.

Table 1. Available storage options
Storage typeDescriptionExamples

Block

  • Presented to the operating system (OS) as a block device

  • Suitable for applications that need full control of storage and operate at a low level on files bypassing the file system

  • Also referred to as a Storage Area Network (SAN)

  • Non-shareable, which means that only one client at a time can mount an endpoint of this type

AWS EBS and VMware vSphere support dynamic persistent volume (PV) provisioning natively in OKD.

File

  • Presented to the OS as a file system export to be mounted

  • Also referred to as Network Attached Storage (NAS)

  • Concurrency, latency, file locking mechanisms, and other capabilities vary widely between protocols, implementations, vendors, and scales.

RHEL NFS, NetApp NFS [1], and Vendor NFS

Object

  • Accessible through a REST API endpoint

  • Configurable for use in the OpenShift image registry

  • Applications must build their drivers into the application and/or container.

AWS S3

  1. NetApp NFS supports dynamic PV provisioning when using the Trident plugin.

The following table summarizes the recommended and configurable storage technologies for the given OKD cluster application.

Table 2. Recommended and configurable storage technology
Storage typeBlockFileObject

ROX1

Yes4

Yes4

Yes

RWX2

No

Yes

Yes

Registry

Configurable

Configurable

Recommended

Scaled registry

Not configurable

Configurable

Recommended

Metrics3

Recommended

Configurable5

Not configurable

Elasticsearch Logging

Recommended

Configurable6

Not supported6

Loki Logging

Not configurable

Not configurable

Recommended

Apps

Recommended

Recommended

Not configurable7

1 ReadOnlyMany

2 ReadWriteMany

3 Prometheus is the underlying technology used for metrics.

4 This does not apply to physical disk, VM physical disk, VMDK, loopback over NFS, AWS EBS, and Azure Disk.

5 For metrics, using file storage with the ReadWriteMany (RWX) access mode is unreliable. If you use file storage, do not configure the RWX access mode on any persistent volume claims (PVCs) that are configured for use with metrics.

6 For logging, review the recommended storage solution in Configuring persistent storage for the log store section. Using NFS storage as a persistent volume or through NAS, such as Gluster, can corrupt the data. Hence, NFS is not supported for Elasticsearch storage and LokiStack log store in OKD Logging. You must use one persistent volume type per log store.

7 Object storage is not consumed through OKD’s PVs or PVCs. Apps must integrate with the object storage REST API.

A scaled registry is an OpenShift image registry where two or more pod replicas are running.

Specific application storage recommendations

Testing shows issues with using the NFS server on Fedora as storage backend for core services. This includes the OpenShift Container Registry and Quay, Prometheus for monitoring storage, and Elasticsearch for logging storage. Therefore, using Fedora NFS to back PVs used by core services is not recommended.

Other NFS implementations on the marketplace might not have these issues. Contact the individual NFS implementation vendor for more information on any testing that was possibly completed against these OKD core components.

Registry

In a non-scaled/high-availability (HA) OpenShift image registry cluster deployment:

  • The storage technology does not have to support RWX access mode.

  • The storage technology must ensure read-after-write consistency.

  • The preferred storage technology is object storage followed by block storage.

  • File storage is not recommended for OpenShift image registry cluster deployment with production workloads.

Scaled registry

In a scaled/HA OpenShift image registry cluster deployment:

  • The storage technology must support RWX access mode.

  • The storage technology must ensure read-after-write consistency.

  • The preferred storage technology is object storage.

  • Red Hat OpenShift Data Foundation (ODF), Amazon Simple Storage Service (Amazon S3), Google Cloud Storage (GCS), Microsoft Azure Blob Storage, and OpenStack Swift are supported.

  • Object storage should be S3 or Swift compliant.

  • For non-cloud platforms, such as vSphere and bare metal installations, the only configurable technology is file storage.

  • Block storage is not configurable.

Metrics

In an OKD hosted metrics cluster deployment:

  • The preferred storage technology is block storage.

  • Object storage is not configurable.

It is not recommended to use file storage for a hosted metrics cluster deployment with production workloads.

Logging

In an OKD hosted logging cluster deployment:

  • Loki Operator:

    • The preferred storage technology is S3 compatible Object storage.

    • Block storage is not configurable.

  • OpenShift Elasticsearch Operator:

    • The preferred storage technology is block storage.

    • Object storage is not supported.

As of logging version 5.4.3 the OpenShift Elasticsearch Operator is deprecated and is planned to be removed in a future release. Red Hat will provide bug fixes and support for this feature during the current release lifecycle, but this feature will no longer receive enhancements and will be removed. As an alternative to using the OpenShift Elasticsearch Operator to manage the default log storage, you can use the Loki Operator.

Applications

Application use cases vary from application to application, as described in the following examples:

  • Storage technologies that support dynamic PV provisioning have low mount time latencies, and are not tied to nodes to support a healthy cluster.

  • Application developers are responsible for knowing and understanding the storage requirements for their application, and how it works with the provided storage to ensure that issues do not occur when an application scales or interacts with the storage layer.

Other specific application storage recommendations

It is not recommended to use RAID configurations on Write intensive workloads, such as etcd. If you are running etcd with a RAID configuration, you might be at risk of encountering performance issues with your workloads.

  • OpenStack Cinder: OpenStack Cinder tends to be adept in ROX access mode use cases.

  • Databases: Databases (RDBMSs, NoSQL DBs, etc.) tend to perform best with dedicated block storage.

  • The etcd database must have enough storage and adequate performance capacity to enable a large cluster. Information about monitoring and benchmarking tools to establish ample storage and a high-performance environment is described in Recommended etcd practices.

Additional resources

Deploy Red Hat OpenShift Data Foundation

Red Hat OpenShift Data Foundation is a provider of agnostic persistent storage for OKD supporting file, block, and object storage, either in-house or in hybrid clouds. As a Red Hat storage solution, Red Hat OpenShift Data Foundation is completely integrated with OKD for deployment, management, and monitoring.

If you are looking for Red Hat OpenShift Data Foundation information about…​See the following Red Hat OpenShift Data Foundation documentation:

What’s new, known issues, notable bug fixes, and Technology Previews

OpenShift Data Foundation 4.12 Release Notes

Supported workloads, layouts, hardware and software requirements, sizing and scaling recommendations

Planning your OpenShift Data Foundation 4.12 deployment

Instructions on deploying OpenShift Data Foundation to use an external Red Hat Ceph Storage cluster

Deploying OpenShift Data Foundation 4.12 in external mode

Instructions on deploying OpenShift Data Foundation to local storage on bare metal infrastructure

Deploying OpenShift Data Foundation 4.12 using bare metal infrastructure

Instructions on deploying OpenShift Data Foundation on Red Hat OKD VMware vSphere clusters

Deploying OpenShift Data Foundation 4.12 on VMware vSphere

Instructions on deploying OpenShift Data Foundation using Amazon Web Services for local or cloud storage

Deploying OpenShift Data Foundation 4.12 using Amazon Web Services

Instructions on deploying and managing OpenShift Data Foundation on existing Red Hat OKD Google Cloud clusters

Deploying and managing OpenShift Data Foundation 4.12 using Google Cloud

Instructions on deploying and managing OpenShift Data Foundation on existing Red Hat OKD Azure clusters

Deploying and managing OpenShift Data Foundation 4.12 using Microsoft Azure

Instructions on deploying OpenShift Data Foundation to use local storage on IBM Power® infrastructure

Deploying OpenShift Data Foundation on IBM Power®

Instructions on deploying OpenShift Data Foundation to use local storage on IBM Z® infrastructure

Deploying OpenShift Data Foundation on IBM Z® infrastructure

Allocating storage to core services and hosted applications in Red Hat OpenShift Data Foundation, including snapshot and clone

Managing and allocating resources

Managing storage resources across a hybrid cloud or multicloud environment using the Multicloud Object Gateway (NooBaa)

Managing hybrid and multicloud resources

Safely replacing storage devices for Red Hat OpenShift Data Foundation

Replacing devices

Safely replacing a node in a Red Hat OpenShift Data Foundation cluster

Replacing nodes

Scaling operations in Red Hat OpenShift Data Foundation

Scaling storage

Monitoring a Red Hat OpenShift Data Foundation 4.12 cluster

Monitoring Red Hat OpenShift Data Foundation 4.12

Resolve issues encountered during operations

Troubleshooting OpenShift Data Foundation 4.12

Migrating your OKD cluster from version 3 to version 4

Migration

Additional resources