1=================================================== 2Pure Storage iSCSI and Fibre Channel volume drivers 3=================================================== 4 5The Pure Storage FlashArray volume drivers for OpenStack Block Storage 6interact with configured Pure Storage arrays and support various 7operations. 8 9Support for iSCSI storage protocol is available with the PureISCSIDriver 10Volume Driver class, and Fibre Channel with PureFCDriver. 11 12All drivers are compatible with Purity FlashArrays that support the REST 13API version 1.2, 1.3, 1.4, or 1.5 (Purity 4.0.0 and newer). 14 15Limitations and known issues 16~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 17 18If you do not set up the nodes hosting instances to use multipathing, 19all network connectivity will use a single physical port on the array. 20In addition to significantly limiting the available bandwidth, this 21means you do not have the high-availability and non-disruptive upgrade 22benefits provided by FlashArray. Multipathing must be used to take advantage 23of these benefits. 24 25Supported operations 26~~~~~~~~~~~~~~~~~~~~ 27 28* Create, delete, attach, detach, retype, clone, and extend volumes. 29 30* Create a volume from snapshot. 31 32* Create, list, and delete volume snapshots. 33 34* Create, list, update, and delete consistency groups. 35 36* Create, list, and delete consistency group snapshots. 37 38* Manage and unmanage a volume. 39 40* Manage and unmanage a snapshot. 41 42* Get volume statistics. 43 44* Create a thin provisioned volume. 45 46* Replicate volumes to remote Pure Storage array(s). 47 48Configure OpenStack and Purity 49~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 50 51You need to configure both your Purity array and your OpenStack cluster. 52 53.. note:: 54 55 These instructions assume that the ``cinder-api`` and ``cinder-scheduler`` 56 services are installed and configured in your OpenStack cluster. 57 58Configure the OpenStack Block Storage service 59--------------------------------------------- 60 61In these steps, you will edit the ``cinder.conf`` file to configure the 62OpenStack Block Storage service to enable multipathing and to use the 63Pure Storage FlashArray as back-end storage. 64 65#. Install Pure Storage PyPI module. 66 A requirement for the Pure Storage driver is the installation of the 67 Pure Storage Python SDK version 1.4.0 or later from PyPI. 68 69 .. code-block:: console 70 71 $ pip install purestorage 72 73#. Retrieve an API token from Purity. 74 The OpenStack Block Storage service configuration requires an API token 75 from Purity. Actions performed by the volume driver use this token for 76 authorization. Also, Purity logs the volume driver's actions as being 77 performed by the user who owns this API token. 78 79 If you created a Purity user account that is dedicated to managing your 80 OpenStack Block Storage volumes, copy the API token from that user 81 account. 82 83 Use the appropriate create or list command below to display and copy the 84 Purity API token: 85 86 * To create a new API token: 87 88 .. code-block:: console 89 90 $ pureadmin create --api-token USER 91 92 The following is an example output: 93 94 .. code-block:: console 95 96 $ pureadmin create --api-token pureuser 97 Name API Token Created 98 pureuser 902fdca3-7e3f-d2e4-d6a6-24c2285fe1d9 2014-08-04 14:50:30 99 100 * To list an existing API token: 101 102 .. code-block:: console 103 104 $ pureadmin list --api-token --expose USER 105 106 The following is an example output: 107 108 .. code-block:: console 109 110 $ pureadmin list --api-token --expose pureuser 111 Name API Token Created 112 pureuser 902fdca3-7e3f-d2e4-d6a6-24c2285fe1d9 2014-08-04 14:50:30 113 114#. Copy the API token retrieved (``902fdca3-7e3f-d2e4-d6a6-24c2285fe1d9`` from 115 the examples above) to use in the next step. 116 117#. Edit the OpenStack Block Storage service configuration file. 118 The following sample ``/etc/cinder/cinder.conf`` configuration lists the 119 relevant settings for a typical Block Storage service using a single 120 Pure Storage array: 121 122 .. code-block:: ini 123 124 [DEFAULT] 125 enabled_backends = puredriver-1 126 default_volume_type = puredriver-1 127 128 [puredriver-1] 129 volume_backend_name = puredriver-1 130 volume_driver = PURE_VOLUME_DRIVER 131 san_ip = IP_PURE_MGMT 132 pure_api_token = PURE_API_TOKEN 133 use_multipath_for_image_xfer = True 134 135 Replace the following variables accordingly: 136 137 PURE_VOLUME_DRIVER 138 Use either ``cinder.volume.drivers.pure.PureISCSIDriver`` for iSCSI or 139 ``cinder.volume.drivers.pure.PureFCDriver`` for Fibre Channel 140 connectivity. 141 142 IP_PURE_MGMT 143 The IP address of the Pure Storage array's management interface or a 144 domain name that resolves to that IP address. 145 146 PURE_API_TOKEN 147 The Purity Authorization token that the volume driver uses to 148 perform volume management on the Pure Storage array. 149 150.. note:: 151 152 The volume driver automatically creates Purity host objects for 153 initiators as needed. If CHAP authentication is enabled via the 154 ``use_chap_auth`` setting, you must ensure there are no manually 155 created host objects with IQN's that will be used by the OpenStack 156 Block Storage service. The driver will only modify credentials on hosts that 157 it manages. 158 159.. note:: 160 161 If using the PureFCDriver it is recommended to use the OpenStack 162 Block Storage Fibre Channel Zone Manager. 163 164Volume auto-eradication 165~~~~~~~~~~~~~~~~~~~~~~~ 166 167To enable auto-eradication of deleted volumes, snapshots, and consistency 168groups on deletion, modify the following option in the ``cinder.conf`` file: 169 170.. code-block:: ini 171 172 pure_eradicate_on_delete = true 173 174By default, auto-eradication is disabled and all deleted volumes, snapshots, 175and consistency groups are retained on the Pure Storage array in a recoverable 176state for 24 hours from time of deletion. 177 178SSL certification 179~~~~~~~~~~~~~~~~~ 180 181To enable SSL certificate validation, modify the following option in the 182``cinder.conf`` file: 183 184.. code-block:: ini 185 186 driver_ssl_cert_verify = true 187 188By default, SSL certificate validation is disabled. 189 190To specify a non-default path to ``CA_Bundle`` file or directory with 191certificates of trusted CAs: 192 193 194.. code-block:: ini 195 196 driver_ssl_cert_path = Certificate path 197 198.. note:: 199 200 This requires the use of Pure Storage Python SDK > 1.4.0. 201 202Replication configuration 203~~~~~~~~~~~~~~~~~~~~~~~~~ 204 205Add the following to the back-end specification to specify another Flash 206Array to replicate to: 207 208.. code-block:: ini 209 210 [puredriver-1] 211 replication_device = backend_id:PURE2_NAME,san_ip:IP_PURE2_MGMT,api_token:PURE2_API_TOKEN 212 213Where ``PURE2_NAME`` is the name of the remote Pure Storage system, 214``IP_PURE2_MGMT`` is the management IP address of the remote array, 215and ``PURE2_API_TOKEN`` is the Purity Authorization token 216of the remote array. 217 218Note that more than one ``replication_device`` line can be added to allow for 219multi-target device replication. 220 221A volume is only replicated if the volume is of a volume-type that has 222the extra spec ``replication_enabled`` set to ``<is> True``. 223 224To create a volume type that specifies replication to remote back ends: 225 226.. code-block:: console 227 228 $ openstack volume type create ReplicationType 229 $ openstack volume type set --property replication_enabled='<is> True' ReplicationType 230 231The following table contains the optional configuration parameters available 232for replication configuration with the Pure Storage array. 233 234==================================================== ============= ====== 235Option Description Default 236==================================================== ============= ====== 237``pure_replica_interval_default`` Snapshot 238 replication 239 interval in 240 seconds. ``3600`` 241``pure_replica_retention_short_term_default`` Retain all 242 snapshots on 243 target for 244 this time 245 (in seconds). ``14400`` 246``pure_replica_retention_long_term_per_day_default`` Retain how 247 many 248 snapshots 249 for each 250 day. ``3`` 251``pure_replica_retention_long_term_default`` Retain 252 snapshots 253 per day 254 on target 255 for this 256 time (in 257 days). ``7`` 258==================================================== ============= ====== 259 260 261.. note:: 262 263 ``replication-failover`` is only supported from the primary array to any of the 264 multiple secondary arrays, but subsequent ``replication-failover`` is only 265 supported back to the original primary array. 266 267Automatic thin-provisioning/oversubscription ratio 268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 269 270To enable this feature where we calculate the array oversubscription ratio as 271(total provisioned/actual used), add the following option in the 272``cinder.conf`` file: 273 274.. code-block:: ini 275 276 [puredriver-1] 277 pure_automatic_max_oversubscription_ratio = True 278 279By default, this is disabled and we honor the hard-coded configuration option 280``max_over_subscription_ratio``. 281 282.. note:: 283 284 Arrays with very good data reduction rates (compression/data deduplication/thin provisioning) 285 can get *very* large oversubscription rates applied. 286 287Scheduling metrics 288~~~~~~~~~~~~~~~~~~ 289 290A large number of metrics are reported by the volume driver which can be useful 291in implementing more control over volume placement in multi-backend 292environments using the driver filter and weighter methods. 293 294Metrics reported include, but are not limited to: 295 296.. code-block:: text 297 298 total_capacity_gb 299 free_capacity_gb 300 provisioned_capacity 301 total_volumes 302 total_snapshots 303 total_hosts 304 total_pgroups 305 writes_per_sec 306 reads_per_sec 307 input_per_sec 308 output_per_sec 309 usec_per_read_op 310 usec_per_read_op 311 queue_depth 312 313.. note:: 314 315 All total metrics include non-OpenStack managed objects on the array. 316 317In conjunction with QOS extra-specs, you can create very complex algorithms to 318manage volume placement. More detailed documentation on this is available in 319other external documentation. 320