Configure an Extended Storage Backend¶

Overview

This section explains how to define an ESB, assign it to OpenStack services, and verify its configuration. Use the first procedure as a baseline for any backend, then adjust the protocol, StorageClass, and driver options to match your storage array.

Backend Configuration Schema ¶

A storage_conf.backends_conf entry uses the following fields.

Field	Description
`name`	Required. Must match an entry in `storage_conf.storage_backends` and is the name you reference in the priority lists. .. note: The backend names ``ceph``, ``netapp-nfs``, ``netapp-iscsi``, and ``netapp-fc`` are reserved for platform-managed backends and must not be used for extended backends. In this release, any ``backends_conf`` entry that uses a reserved name is silently ignored. Similarly, ``rbd`` is reserved for the platform Ceph backend and is not supported as a protocol for extended backends. Use only ``iscsi``, ``fcp``, or ``nfs`` as the protocol value.
`protocol`	Required. Must be `iscsi`, `fcp`, or `nfs`. Determines the pod-level settings StarlingX OpenStack applies (host networking, iSCSI, multipath). The value `rbd` is reserved for Ceph and is not valid; use `fcp`, not `fc`.
`k8s_storage_class`	Optional. Specifies a StorageClass name, or `none` (the default) if the backend does not provision PVCs. A backend configured with `none` cannot be used for control-plane services, Glance, or Nova ephemeral PVCs.
`secretRef`	Optional. References a Kubernetes Secret and maps its keys to the `cinder.conf` fields. See Configure a Backend (to create the Cinder override file).
`volume_backend`	Optional. Specifies driver options that are passed directly to `cinder.conf` without modification. Provide the full set of keys the driver requires; StarlingX OpenStack does not validate them.
`nfs_shares`	Optional, applies only when `protocol: nfs`. One or more NFS exports (one per line), for drivers that read their shares from an `nfs_shares_config` file instead of a driver-specific option.

Note

A backend is used by a service only when it is enabled in storage_conf.storage_backends and included in that service’s priority list. A backend that is described but not listed in a priority list is not used, and no message is logged for it. When you update a priority list or backends_conf with system helm-override-update, provide the complete list, as the override replaces the value at that path.

Configure a Backend ¶

Use this procedure to declare a backend and select it for Cinder volumes and Cinder backup. The example configures a Dell PowerStore iSCSI backend configured to serve Cinder volumes only (k8s_storage_class: none).

Prerequisites

Ensure that the ESB prerequisites are met. For more information, see Extended Storage Backend Prerequisites.

Procedure

Create openstack namespace if it does not exist, before creating the credentials Secret.
```
~(keystone_admin)]$ kubectl create namespace openstack
```

Create the credentials Secret, if the backend requires one, using the array’s management credentials.

~(keystone_admin)]$ kubectl create secret generic dell-powerstore-credentials \
                    --namespace openstack \
                    --from-literal=username=<array-admin-user> \
                    --from-literal=password=<array-admin-password>

Create the Cinder override file, replacing the placeholders with values specific to your storage array. Include all required driver options, such as the array’s management address and iSCSI target ports.

cinder-overrides.yaml

storage_conf:
  storage_backends:
    - name: dell-powerstore-iscsi
      enabled: true
  volume_storage_class_priority:
    - dell-powerstore-iscsi
  backup_storage_class_priority:
    - dell-powerstore-iscsi
  backends_conf:
    - name: dell-powerstore-iscsi
      protocol: iscsi
      k8s_storage_class: none
      secretRef:
        name: dell-powerstore-credentials
        namespace: openstack
        keys:
          san_login: username      # cinder.conf field : Secret key
          san_password: password
      volume_backend:
        volume_backend_name: dell-powerstore-iscsi
        volume_driver: cinder.volume.drivers.dell_emc.powerstore.driver.PowerStoreDriver
        san_ip: <array-management-ip>
        powerstore_ports: <target-ip-1>,<target-ip-2>

The secretRef.keys map is read as <cinder.conf field>: <Secret key>. StarlingX OpenStack resolves each Secret value into the backend’s cinder.conf section, so no credentials are stored in your overrides. By convention, keep volume_backend_name equal to the entry’s name.

Apply the overrides and the application.

~(keystone_admin)]$ source /etc/platform/openrc
~(keystone_admin)]$ system helm-override-update --reuse-values --values cinder-overrides.yaml stx-openstack cinder openstack
~(keystone_admin)]$ system application-apply stx-openstack

Results

StarlingX OpenStack starts the backend with the resolved credentials. To verify that the backend is running, see Verify an Extended Backend.

Select the Backend for Other Services ¶

Once a backend is configured on the Cinder chart, other services select it by name from their own priority lists. Use only a backend with a real k8s_storage_class. A none backend can be used only for Cinder volumes.

MariaDB and RabbitMQ

Set the backend name in storage_conf.volume_storage_class_priority on each chart. To keep these services on the platform Ceph storage, use the ceph backend name instead.

storage_conf:
  volume_storage_class_priority:
    - <extended-backend-name>

Important

Choose the StorageClass for MariaDB and RabbitMQ during first installation. Their PVCs are created once, and Kubernetes does not allow the StorageClass of an existing claim to be changed. Attempting to change it on a running system causes the application apply to fail when upgrading the MariaDB or RabbitMQ release. To move these services to a different StorageClass later, back up their data, remove the application using system application-remove stx-openstack, delete the existing MariaDB and RabbitMQ PVCs from the openstack namespace, and re-apply the application.

Glance

Glance uses the Cinder store by default, storing images as Cinder volumes on the extended backend. This configuration works for every protocol, including k8s_storage_class: none, and is the recommended configuration.

storage_conf:
  volume_storage_class_priority:
    - cinder

To store images on a Glance PVC instead, set the priority list to pvc and add the backend name to storage_conf.pvc.storage_class_priority. A SAN (iSCSI or FC) StorageClass supports only ReadWriteOnce, which limits Glance to a single API replica. For more than one replica, use an NFS-based StorageClass.

Nova and Libvirt

If any active extended backend uses protocol: iscsi or protocol: fcp, StarlingX OpenStack automatically enables multipath and iSCSI for Nova. No Nova override is required, and Nova ephemeral storage continues to use the default host-path configuration.

For Nova ephemeral storage on an NFS extended backend, set pvc first in the Nova storage_conf.volume_storage_class_priority and add the backend name to storage_conf.pvc.storage_class_priority.

Note

Nova ephemeral PVCs require an NFS-based StorageClass. Pointing the Nova PVC path at a SAN (iSCSI or FC) StorageClass does not fail immediately: instead, the claim never binds, the Libvirt pod stays Pending, and the application apply eventually times out on the Libvirt release. Use host-path ephemeral for SAN backends.

Libvirt takes its storage configuration from the Nova chart and needs no separate configuration.

Additional Options ¶

TLS to the storage array

storage_conf.tls configures the CA certificate the Cinder pods use to connect to an array over HTTPS. The container_cert field is a list, so the bundle can be mounted into more than one container.

storage_conf:
  tls:
    host_cert: /var/opt/openstack/certs/storage.pem
    container_cert:
      - /usr/lib/ssl/cert.pem

The certificate file must exist at host_cert when you apply. See Extended Storage Backend Prerequisites.

Cinder backup driver

StarlingX OpenStack selects the backup driver from the highest-priority entry in storage_conf.backup_storage_class_priority:

An nfs backend uses the NFS backup driver; provide conf.cinder.DEFAULT.backup_share.
An iscsi or fcp backend uses the Posix backup driver, which needs a real k8s_storage_class (not none). As SAN StorageClass is ReadWriteOnce only, Cinder backup runs with a single replica.

To specify the backend driver explicitly, set conf.cinder.DEFAULT.backup_driver.

Extra pod mounts

storage_conf.extra_mounts injects additional volumes and volumeMounts into the cinder_volume and cinder_backup pods for drivers that need a host path or credential file inside the container.

NFS shares for a driver that needs them

Some Cinder NFS drivers read their exports from a file referenced by nfs_shares_config rather than from a driver-specific option. For a protocol: nfs backend using such a driver, configure nfs_shares with one export per line.

By default, StarlingX OpenStack derives nfs_shares_config from volume_backend_name. An explicit nfs_shares_config is always normalized to /etc/cinder/<file name>, because the chart mounts configuration files only under this fixed directory.

Two configurations are rejected, with the backend still enabled but without a shares file: nfs_shares_config resolving to the strict netapp-nfs backend’s reserved file or two backends resolving to the same file (usually a copied volume_backend_name). To avoid these conflicts, assign a unique volume_backend_name to each backend.

Examples ¶

Example 1. Dell PowerStore iSCSI and NFS (ESB-only)

This example configures two extended backends on an ESB-only system: a Dell PowerStore iSCSI backend for Cinder volumes and a Dell PowerStore NFS backend used for Cinder backup. Both backends share one credentials Secret.

storage_conf:
  storage_backends:
    - name: dell-iscsi
      enabled: true
    - name: dell-nfs
      enabled: true
  volume_storage_class_priority:
    - dell-iscsi
  backup_storage_class_priority:
    - dell-nfs
  backends_conf:
    - name: dell-iscsi
      protocol: iscsi
      k8s_storage_class: none
      secretRef:
        name: cinder-backend-credentials
        namespace: openstack
        keys:
          san_login: dell_username
          san_password: dell_password
      volume_backend:
        volume_backend_name: dell-iscsi
        volume_driver: cinder.volume.drivers.dell_emc.powerstore.driver.PowerStoreDriver
        san_ip: <array-management-ip>
        powerstore_ports: <target-ip-1>,<target-ip-2>
    - name: dell-nfs
      protocol: nfs
      k8s_storage_class: none
      secretRef:
        name: cinder-backend-credentials
        namespace: openstack
        keys:
          san_login: dell_username
          san_password: dell_password
      volume_backend:
        volume_backend_name: dell-nfs
        volume_driver: cinder.volume.drivers.dell_emc.powerstore.driver.PowerStoreDriver
        san_ip: <array-management-ip>
        powerstore_ports: <target-ip-1>,<target-ip-2>
        powerstore_nas: <nas-server-name>
conf:
  cinder:
    DEFAULT:
      backup_share: "<backup-nfs-export>"

Example 2. NetApp FC with a pure iSCSI extended backend

This example runs the platform-managed netapp-fc backend alongside an extended backend. The extended backend is selected as the default volume type, while Cinder backup continues to use the NetApp NFS backend. The strict NetApp backends still need to be enabled for the backup to resolve. Configure the strict NetApp backends as described in Configure an External NetApp Storage Backend for OpenStack; this example shows only the extended backend.

storage_conf:
  storage_backends:
    - name: netapp-fc
      enabled: true
    - name: pure-iscsi
      enabled: true
  volume_storage_class_priority:
    - pure-iscsi
    - netapp-fc
  backup_storage_class_priority:
    - netapp-nfs
  backends_conf:
    - name: pure-iscsi
      protocol: iscsi
      k8s_storage_class: none
      secretRef:
        name: cinder-backend-credentials
        namespace: openstack
        keys:
          pure_api_token: pure_api_token
      volume_backend:
        volume_backend_name: pure-iscsi
        volume_driver: cinder.volume.drivers.pure.PureISCSIDriver
        san_ip: <array-management-ip>

Verify an Extended Backend ¶

Follow these steps to verify that the extended backend is correctly configured and operational.

Procedure

Verify that each configured backend is operational. The backend appears with its volume_backend_name as the host identifier.
```
~(keystone_admin)]$ openstack volume service list
```
Verify that a volume type exists for each enabled backend.
```
~(keystone_admin)]$ openstack volume type list
```
Confirm that the claims are bound to the expected StorageClass, for PVC consumers.
```
~(keystone_admin)]$ kubectl -n openstack get pvc -o wide
```

Results

Each backend shows up and a matching volume type exists. If a backend shows down, see Troubleshoot Extended Storage Backend Issues.