DataCore SANsymphony volume driver¶

DataCore SANsymphony volume driver provides OpenStack Compute instances with access to the SANsymphony(TM) Software-defined Storage Platform.

When volumes are created in OpenStack, the driver creates corresponding virtual disks in the SANsymphony server group. When a volume is attached to an instance in OpenStack, a Linux host is registered and the corresponding virtual disk is served to the host in the SANsymphony server group.

Requirements¶

DataCore server group running SANsymphony software version 10 PSP6 or later.
OpenStack Integration has been tested with the OpenStack environment installed on Ubuntu 20.04. For the list of qualified Linux host operating system types, refer to the Linux Host Configuration Guide on the DataCore Technical Support Web page.
If using multipath I/O, ensure that iSCSI ports are logged in on all OpenStack Compute nodes. (All Fibre Channel ports will be logged in automatically.)

Python dependencies¶

websocket-client>=0.32.0

Install this package using pip:
```
$ sudo pip install "websocket-client>=0.32.0"
```

Configuration¶

The volume driver can be configured by editing the cinder.conf file. The options below can be configured either per server group or as extra specifications in a volume type configuration.

Configuration options and default values:

datacore_disk_pools = None

Sets the pools to use for the DataCore OpenStack Cinder Volume Driver. This option acts like a filter and any number of pools may be specified. The list of specified pools will be used to select the storage sources needed for virtual disks; one for single or two for mirrored. Selection is based on the pools with the most free space.

This option may also be specified as an extra specification of a volume type.
datacore_disk_type = single

Sets the SANsymphony virtual disk type (single or mirrored). Single virtual disks are created by default. Specify mirrored to override this behavior. Mirrored virtual disks require two DataCore Servers in the server group.

This option may also be specified as an extra specification of a volume type.
datacore_storage_profile = Normal

Sets the storage profile of the virtual disk. The default setting is Normal. Other valid values include the standard storage profiles (Critical, High, Low, and Archive) and the names of custom profiles that have been created.

This option may also be specified as an extra specification of a volume type.
datacore_api_timeout = 300

Sets the number of seconds to wait for a response from a DataCore API call.

This option is used in the server group back-end configuration only.
datacore_disk_failed_delay = 300

Sets the number of seconds to wait for the SANsymphony virtual disk to come out of the “Failed” state.

This option is used in the server group back-end configuration only.
datacore_iscsi_unallowed_targets = []

Sets a list of iSCSI targets that cannot be used to attach to the volume. By default, the DataCore iSCSI volume driver attaches a volume through all target ports with the Front-end role enabled, unlike the DataCore Fibre Channel volume driver that attaches a volume only through target ports connected to initiator.

To prevent the DataCore iSCSI volume driver from using some front-end targets in volume attachment, specify this option and list the iqn and target machine for each target as the value, such as <iqn:target name>, <iqn:target name>, <iqn:target name>. For example, <iqn.2000-08.com.company:Server1-1, iqn.2000-08.com.company:Server2-1, iqn.2000-08.com.company:Server3-1>.

This option is used in the server group back-end configuration only.
use_chap_auth = False

Sets the CHAP authentication for the iSCSI targets that are used to serve the volume. This option is disabled by default and will allow hosts (OpenStack Compute nodes) to connect to iSCSI storage back-ends without authentication. To enable CHAP authentication, which will prevent hosts (OpenStack Compute nodes) from connecting to back-ends without authentication, set this option to True.

In addition, specify the location where the DataCore volume driver will store dynamically created CHAP secrets by setting the datacore_iscsi_chap_storage option.

This option is used in the server group back-end configuration only. The driver will enable CHAP only for involved target ports, therefore, not all DataCore Servers may have CHAP configured. Before enabling CHAP, ensure that there are no SANsymphony volumes attached to any instances.
datacore_iscsi_chap_storage = /var/lib/cinder/.datacore_chap

Sets the path to the iSCSI CHAP authentication password storage file. datacore_iscsi_chap_storage is only used when use_chap_auth = True and chap_password is not set. Default datacore_iscsi_chap_storage value is $state_path/.datacore_chap.

CHAP secrets are passed from OpenStack Block Storage to compute in clear text. This communication should be secured to ensure that CHAP secrets are not compromised. This can be done by setting up file permissions. Before changing the CHAP configuration, ensure that there are no SANsymphony volumes attached to any instances.

This option is used in the server group back-end configuration only.

Configuration Examples¶

Examples of option configuration in the cinder.conf file.

An example using datacore_disk_pools, datacore_disk_type, and datacore_storage_profile to create a mirrored virtual disk with a High priority storage profile using specific pools:

volume_driver = cinder.volume.drivers.datacore.iscsi.ISCSIVolumeDriver

san_ip = <DataCore Server IP or DNS name>

san_login = <User Name>

san_password = <Password>

datacore_disk_type = mirrored

datacore_disk_pools = Disk pool 1, Disk pool 2

datacore_storage_profile = High

An example using datacore_iscsi_unallowed_targets to prevent the volume from using the specified targets:

volume_driver = cinder.volume.drivers.datacore.iscsi.ISCSIVolumeDriver

san_ip = <DataCore Server IP or DNS name>

san_login = <User Name>

san_password = <Password>

datacore_iscsi_unallowed_targets = iqn.2000-08.com.datacore:mns-ssv-10-1,iqn.2000-08.com.datacore:mns-ssvdev-01-1

An example using use_chap_auth and chap_username and chap_password to enable CHAP authentication:

volume_driver = cinder.volume.drivers.datacore.iscsi.ISCSIVolumeDriver

use_chap_auth = True

chap_username = user1

chap_password = user1_password

An example using use_chap_auth and datacore_iscsi_chap_storage to enable CHAP authentication and provide the path to the CHAP password storage file:
```
volume_driver = cinder.volume.drivers.datacore.iscsi.ISCSIVolumeDriver

use_chap_auth = True

datacore_iscsi_chap_storage = /var/lib/cinder/.datacore_chap
```
DataCore volume driver stores CHAP secrets in clear text, and the password file must be secured by setting up file permissions. The following example shows how to create a password file and set up permissions. It assumes that the cinder-volume service is running under the user cinder. Please note that following steps are only required if the user wants to change the default datacore_iscsi_chap_storage location.
```
$ sudo mkdir /opt/user_dir/cinder -p

$ sudo /bin/sh -c "> /opt/user_dir/cinder/.datacore_chap"

$ sudo chown cinder:cinder /opt/user_dir/cinder

$ sudo chown cinder:cinder /opt/user_dir/cinder/.datacore_chap

$ sudo chmod -v 600 /opt/user_dir/cinder/.datacore_chap
```
CHAP will be enabled in SANsymphony after setting use_chap_auth = True. chap_username and chap_password will be used if mentioned, if not iSCSI initiator PortName will be used as chap_username with a random password, and the credentials will be stored in datacore_iscsi_chap_storage location.

Creating Volume Types¶

Volume types can be created with the DataCore disk type specified in the datacore:disk_type extra specification. In the following example, a volume type named mirrored_disk is created and the disk type is set to mirrored.

$ cinder type-create mirrored_disk

$ cinder type-key mirrored_disk set datacore:disk_type=mirrored

In addition, volume specifications can also be declared as extra specifications for volume types. The example below sets additional configuration options for the volume type mirrored_disk; storage profile will be set to High and virtual disks will be created from Disk pool 1, Disk pool 2, or Disk pool 3.

$ cinder type-key mirrored_disk set datacore:storage_profile=High

$ cinder type-key mirrored_disk set "datacore:disk_pools=Disk pool 1, Disk pool 2, Disk pool 3"

Configuring Multiple Storage Back Ends¶

OpenStack Block Storage can be configured to use several back-end storage solutions. Multiple back-end configuration allows you to configure different storage configurations for SANsymphony server groups. The configuration options for a group must be defined in the group.

To enable multiple back ends:

In the cinder.conf file, set the enabled_backends option to identify the groups. One name is associated with each server group back-end configuration. In the example below there are two groups, datacore-1 and datacore-2:
```
[DEFAULT]

enabled_backends = datacore-1, datacore-2
```

Define the back-end storage used by each server group in a separate section (for example [datacore-1]):

[datacore-1]

volume_driver = cinder.volume.drivers.datacore.iscsi.ISCSIVolumeDriver

volume_backend_name = DataCore_iSCSI

san_ip   = <ip_or_dns_name>

san_login = <user_name>

san_password = <password>

use_chap_auth = True

chap_username = <chap_username>

chap_password = <chap_password>

datacore_iscsi_chap_storage = /var/lib/cinder/.datacore_chap

datacore_iscsi_unallowed_targets = iqn.2000-08.com.datacore:mns-ssv-10-1

datacore_disk_type = mirrored

[datacore-2]

volume_driver = cinder.volume.drivers.datacore.fc.FibreChannelVolumeDriver

volume_backend_name = DataCore_FibreChannel

san_ip   = <ip_or_dns_name>

san_login = <user_name>

san_password = <password>

datacore_disk_type = mirrored

datacore_disk_pools = Disk pool 1, Disk pool 2

datacore_storage_profile = High

Create the volume types

$ cinder type-create datacore_iscsi

$ cinder type-create datacore_fc

Add an extra specification to link the volume type to a back-end name:

$ cinder type-key datacore_iscsi set volume_backend_name=DataCore_iSCSI

$ cinder type-key datacore_fc set volume_backend_name=DataCore_FibreChannel

See Configure multiple-storage back ends for additional information.

Detaching Volumes and Terminating Instances¶

Notes about the expected behavior of SANsymphony software when detaching volumes and terminating instances in OpenStack:

When a volume is detached from a host in OpenStack, the virtual disk will be unserved from the host in SANsymphony, but the virtual disk will not be deleted.
If all volumes are detached from a host in OpenStack, the host will remain registered and all virtual disks will be unserved from that host in SANsymphony. The virtual disks will not be deleted.
If an instance is terminated in OpenStack, the virtual disk for the instance will be unserved from the host and either be deleted or remain as unserved virtual disk depending on the option selected when terminating.

Support¶

In the event that a support bundle is needed, the administrator should save the files from the /var/log folder on the Linux host and attach to DataCore Technical Support incident manually.

DataCore SANsymphony volume driver