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