« back to all changes in this revision
Viewing changes to docs/quick_start.rst
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Narinder Gupta
- Date: 2019-02-06 16:03:16 UTC
- Revision ID: narinder.gupta@canonical.com-20190206160316-2mbba1k2ak000r9a
first version of package
- files added:
- .pc
- .pc/debianbuild
- .pc/debianbuild/purestorage.egg-info
- debian
- debian/patches
- debian/source
- docs
- docs/_static
- purestorage
- purestorage.egg-info
added
removed
docs/quick_start.rst
1
Quick Start Guide
2
=================
3
4
This guide is intended to give users a basic idea of REST Client usage
5
through examples.
6
7
8
Before You Begin
9
----------------
10
11
You should already have the Pure Storage FlashArray REST Client installed.
12
13
This includes installing REST Client package dependencies.
14
15
See :doc:`installation` for more information.
16
17
18
Starting A Session
19
------------------
20
21
To verify the REST Client package is installed and importable, try executing
22
the following in a Python interpreter:
23
24
.. code-block:: python
25
26
>>> import purestorage
27
28
29
If that succeeds without an ImportError, you are ready to start a REST session
30
using the client.
31
32
REST sessions are automatically established when a FlashArray object is
33
instantiated. To instantiate a FlashArray object, provide the IP address
34
or domain name of the target array as well as a username and password, or
35
API token.
36
37
.. code-block:: python
38
39
>>> array = purestorage.FlashArray("localhost", "pureuser", "pureuser")
40
41
42
.. code-block:: python
43
44
>>> array = purestorage.FlashArray("localhost",
45
api_token="6e1b80a1-cd63-de90-b74a-7fc16d034016")
46
47
48
.. code-block:: python
49
50
from purestorage import FlashArray
51
52
array = FlashArray("localhost", "pureuser", "pureuser")
53
array_info = array.get()
54
print "FlashArray {} (version {}) REST session established!".format(
55
array_info['array_name'], array_info['version'])
56
57
58
To end a session, invalidate your REST cookie:
59
60
.. code-block:: python
61
62
array.invalidate_cookie()
63
64
65
Calling any other methods again creates a new cookie automatically.
66
67
68
Creating Volumes
69
----------------
70
71
When creating a volume, specify the volume name and a size.
72
73
Size can either be an integer or a string with an optional suffix.
74
75
.. code-block:: python
76
77
>>> array.create_volume("vol1", 1024 ** 3)
78
{
79
u'source': None,
80
u'serial': u'DABA29111570F7A4000114C0',
81
u'size': 1073741824,
82
u'name': u'vol1',
83
u'created': u'2014-08-11T17:19:35Z'
84
}
85
>>> array.create_volume("vol2", "5M")
86
{
87
u'source': None,
88
u'serial': u'DABA29111570F7A4000114C1',
89
u'size': 524288000,
90
u'name': u'vol2',
91
u'created': u'2014-08-11T17:19:51Z'
92
}
93
94
95
Creating Hosts and Hgroups
96
--------------------------
97
98
Host creation requires a name only.
99
100
Optionally IQNs or WWNs can be specified during creation, or they can
101
be set for a particular host after creating.
102
103
Similarly, hgroup creation requires a name only and hosts can be
104
added to the hgroup as part of creation or in a subsequent set call.
105
106
.. code-block:: python
107
108
>>> array.create_host("host1", iqnlist=["iqn.2001-04.com.example:diskarrays-sn-a8675308",
109
"iqn.2001-04.com.example:diskarrays-sn-a8675309"])
110
{
111
u'iqn': [u'iqn.2001-04.com.example:diskarrays-sn-a8675308', u'iqn.2001-04.com.example:diskarrays-sn-a8675309'],
112
u'wwn': [],
113
u'name': u'host1'
114
}
115
>>> array.create_host("host2")
116
{
117
u'iqn': [],
118
u'wwn': [],
119
u'name':
120
u'host2'
121
}
122
>>> array.set_host("host2", wwnlist=["1234567812345678"])
123
{
124
u'iqn': [],
125
u'wwn': [u'1234567812345678'],
126
u'name': u'host2',
127
u'hgroup': None
128
}
129
>>> array.create_hgroup("hgroup1", hostlist=["host1", "host2"])
130
{
131
u'hosts': [u'host1', u'host2'],
132
u'name': u'hgroup1'
133
}
134
135
136
Connecting Volumes
137
------------------
138
139
When connecting volumes to hosts and hgroups, just specify the volume name
140
and the name of the host or hgroup. LUNs may also be specified as optional
141
keyword arguments.
142
143
.. code-block:: python
144
145
>>> array.connect_host("host1", "vol1")
146
{
147
u'vol': u'vol1',
148
u'name': u'host1',
149
u'lun': 1
150
}
151
>>> array.connect_hgroup("hgroup1", "vol2")
152
{
153
u'vol': u'vol2',
154
u'name': u'hgroup1',
155
u'lun': 10
156
}
157
>>> array.list_host_connections("host1")
158
[
159
{
160
u'vol': u'vol1',
161
u'name': u'host1',
162
u'lun': 1,
163
u'hgroup': None
164
},
165
{
166
u'vol': u'vol2',
167
u'name': u'host1',
168
u'lun': 10,
169
u'hgroup': u'hgroup1'
170
}
171
]
172
>>> array.list_hgroup_connections("hgroup1")
173
[{
174
u'vol': u'vol2',
175
u'name': u'hgroup1',
176
u'lun': 10
177
}]
178
179
180
Using Snapshots
181
---------------
182
183
Snapshots can be taken of individual volumes or collections of volumes. Snapshots
184
of more than one volume are guaranteed to be point in time consistent.
185
186
Snapshots (or volumes) can be copied out to new volumes.
187
188
.. code-block:: python
189
190
>>> array.create_snapshot("vol2")
191
{
192
u'source': u'vol2',
193
u'serial': u'DABA29111570F7A4000115A3',
194
u'size': 5242880,
195
u'name': u'vol2.5539',
196
u'created': u'2014-08-15T17:21:22Z'
197
}
198
>>> array.create_snapshots(["vol1", "vol2"], suffix="together")
199
[
200
{
201
u'source': u'vol1',
202
u'serial': u'DABA29111570F7A4000115A4',
203
u'size': 1073741824,
204
u'name': u'vol1.together',
205
u'created': u'2014-08-15T17:21:58Z'
206
},
207
{
208
u'source': u'vol2',
209
u'serial': u'DABA29111570F7A4000115A5',
210
u'size': 5242880,
211
u'name': u'vol2.together',
212
u'created': u'2014-08-15T17:21:58Z'
213
}
214
]
215
>>> array.copy_volume("vol1.together", "vol3")
216
{
217
u'source': u'vol1',
218
u'serial': u'DABA29111570F7A4000115A6',
219
u'size': 1073741824,
220
u'name': u'vol3',
221
u'created': u'2014-08-15T17:21:58Z'
222
}
223
>>> array.list_volumes(snap=True)
224
[
225
{
226
u'source': u'vol1',
227
u'serial': u'DABA29111570F7A4000115A4',
228
u'size': 1073741824,
229
u'name': u'vol1.together',
230
u'created': u'2014-08-15T17:21:58Z'
231
},
232
{
233
u'source': u'vol2',
234
u'serial': u'DABA29111570F7A4000115A5',
235
u'size': 5242880,
236
u'name': u'vol2.together',
237
u'created': u'2014-08-15T17:21:58Z'
238
},
239
{
240
u'source': u'vol2',
241
u'serial': u'DABA29111570F7A4000115A3',
242
u'size': 5242880,
243
u'name': u'vol2.5539',
244
u'created': u'2014-08-15T17:21:22Z'
245
}
246
]
247
248
249
Disconnecting and Destroying Volumes
250
------------------------------------
251
252
Volumes must be disconnected before they can be destroyed, just as hosts must
253
be disconnected before they can be deleted.
254
255
A destroyed volume may be recovered (for up to 24 hours following destruction)
256
or explicitly eradicated.
257
258
.. code-block:: python
259
260
>>> array.disconnect_host("host1", "vol1")
261
{
262
u'vol': u'vol1',
263
u'name': u'host1'
264
}
265
>>> array.destroy_volume("vol1")
266
{
267
u'name': u'vol1'
268
}
269
>>> array.list_volumes(pending_only=True)
270
[
271
{
272
u'name': u'vol1',
273
u'created': u'2014-08-15T17:13:08Z',
274
u'source': None,
275
u'time_remaining': 86400,
276
u'serial': u'DABA29111570F7A4000115A1',
277
u'size': 1073741824
278
}
279
]
280
>>> array.recover_volume("vol1")
281
{
282
u'name': u'vol1'
283
}
284
>>> array.rename_volume("vol1", "renamed")
285
{
286
u'name': u'renamed'
287
}
288
>>> array.destroy_volume("renamed")
289
{
290
u'name': u'renamed'
291
}
292
>>> array.eradicate_volume("renamed")
293
{
294
u'name': u'renamed'
295
}
296
>>> array.list_volumes(pending_only=True)
297
[]
298
299
300
Enable Secure HTTPS Requests
301
----------------------------
302
303
By default the requests being made will not verify the SSL certificate of the
304
target array. Requests made this way will log a InsecureRequestWarning.
305
306
To enable verification use the verify_https flag:
307
308
.. code-block:: python
309
310
>>> array = purestorage.FlashArray("localhost", "pureuser", "pureuser", verify_https=True)
311
312
313
This does require that the target array has a trusted certificate and will
314
be validated correctly by the system making the request.
315
316
If using an 'untrusted' certificate (e.g. self-signed certificate) you can
317
optionally pass in a path to the certificate file:
318
319
.. code-block:: python
320
321
>>> array = purestorage.FlashArray("localhost", "pureuser", "pureuser", verify_https=True,
322
ssl_cert="/etc/ssl/certs/pure-self-signed.crt")
323
Loggerhead is a web-based interface for Breezy
Version: 2.0.1