1heketi-cli(8)                 The heketi Authors                 heketi-cli(8)
2
3
4

NAME

6       heketi-cli - Command line program for Heketi
7

SYNOPSIS

9       heketi-cli [commands] [options]
10

DESCRIPTION

12       Command line program for Heketi
13

COMMANDS

15   Cluster Commands
16       heketi-cli cluster create [--file[=false]] [--block[=false]]
17              Create a cluster
18
19              Options
20
21                     --file[=false]
22                            Optional: Allow the user to control the
23                            possibility of creating regular file volumes on
24                            the cluster to be created.  This is enabled by
25                            default.  Use '--block=false' to disable creation
26                            of block volumes on this cluster.  (default true)
27
28                     --block[=false]
29                            Optional: Allow the user to control the
30                            possibility of creating block volumes on the
31                            cluster to be created.  This is enabled by
32                            default.  Use '--block=false' to disable creation
33                            of block volumes on this cluster.  (default true)
34
35              Example
36                     $ heketi-cli cluster create --block=false
37
38       heketi-cli cluster setflags [--file=true|false] [--block=true|false]
39       <Cluster-ID>
40              Set file and block flags on a cluster.
41
42              Options
43
44                     --file=true|false
45                            Optional: Allow the user to control the
46                            possibility of creating regular file volumes on
47                            the cluster.  Use '--block=true' to enable and
48                            '--block=false' to disable creation of block
49                            volumes on this cluster.
50
51                     --block=true|false
52                            Optional: Allow the user to control the
53                            possibility of creating block volumes on the
54                            cluster.  Use '--block=true' to enable and
55                            '--block=false' to disable creation of block
56                            volumes on this cluster.
57
58              Example
59                     $ heketi-cli cluster setflags --block=false 886a86a868711bef83001
60
61       heketi-cli cluster delete <CLUSTER-ID>
62              Delete a cluster
63
64              Example
65                     $ heketi-cli cluster delete 886a86a868711bef83001
66
67       heketi-cli cluster info  <CLUSTER-ID>
68              Retrieves information about cluster
69
70              Example
71                     $ heketi-cli cluster info 886a86a868711bef83001
72
73       heketi-cli cluster list
74              Lists the clusters managed by Heketi
75
76              Example
77                     $ heketi-cli cluster list
78
79   Device Commands
80       heketi-cli device add --name=<DEVICE-NAME> --node=<NODE-ID>
81              Add new device to node to be managed by Heketi
82
83              Options
84
85                     --name=""
86                            Name of device to add
87
88                     --node=""
89                            Id of the node which has this device
90
91                     --destroy-existing-data
92                            Optional: Destroy existing data on the device
93                            (DANGEROUS).
94
95              Example
96                     $ heketi-cli device add \
97                         --name=/dev/sdb \
98                         --node=3e098cb4407d7109806bb196d9e8f095
99
100       heketi-cli device delete <DEVICE-ID>
101              Deletes a device from Heketi node
102
103              Example
104                     $ heketi-cli device delete 886a86a868711bef83001
105
106       heketi-cli device disable <DEVICE-ID>
107              Disallow usage of a device by placing it offline
108
109              Example
110                     $ heketi-cli device disable 886a86a868711bef83001
111
112       heketi-cli device enable <DEVICE-ID>
113              Allows device to go online
114
115              Example
116                     $ heketi-cli device enable 886a86a868711bef83001
117
118       heketi-cli device info  <DEVICE-ID>
119              Retrieves information about device
120
121              Example
122                     $ heketi-cli device info 886a86a868711bef83001
123
124       heketi-cli device remove  <DEVICE-ID>
125              Moves a device to removed/failed state, replacing all its bricks
126              by bricks on other devices. This requires the device to be
127              brought to disabled/offline state first.
128
129              Example
130                     $ heketi-cli device remove 886a86a868711bef83001
131
132       heketi-cli device resync <DEVICE-ID>
133              Resync storage information about the device with operation
134              system
135
136              Example
137                     $ heketi-cli device resync 886a86a868711bef83001
138
139       heketi-cli device settags <DEVICE-ID> <TAG>:<VALUE> ...
140              Set metadata tags on a given device. Tags are free-form key
141              value pairs that are stored by Heketi and may be used for extra
142              configuration.  One or more <TAG>:<TAG-VALUE> pairs may be
143              provided.
144
145              Options
146
147                     --exact
148                            Optional: Overwrite the existing tags with the
149                            exactly set of tags (and values) specified on this
150                            command line. Without this option, the command
151                            will add or update tags.
152
153              Example
154                     $ heketi-cli device settags 886a86a868711bef83001 arbiter:required flavor:strawberry
155
156       heketi-cli device rmtags <DEVICE-ID> <TAG> ...
157              Remove metadata tags from a given device.
158
159              Options
160
161                     --all  Optional: Remove all tags from the specified
162                            device. May not be combined with specifying tag
163                            names.
164
165              Example
166                     $ heketi-cli device rmtags 886a86a868711bef83001 arbiter
167
168   Node Commands
169       heketi-cli node add --zone=<ZONE-NUMBER> --cluster=<CLUSTER-ID>
170       --management-host-name=<MANAGEMENT-HOSTNAME> --storage-host-
171       name=<STORAGE-HOSTNAME>
172              Add new node to be managed by Heketi
173
174              Options
175
176                     --cluster=""
177                            The cluster in which the node should reside
178
179                     --management-host-name=""
180                            Management host name
181
182                     --storage-host-name=""
183                            Storage host name
184
185                     --zone=-1
186                            The zone in which the node should reside
187
188              Example
189                     $ heketi-cli node add \
190                         --zone=3 \
191                         --cluster=3e098cb4407d7109806bb196d9e8f095 \
192                         --management-host-name=node1-manage.gluster.lab.com \
193                         --storage-host-name=node1-storage.gluster.lab.com
194
195       heketi-cli node delete <NODE-ID>
196              Deletes a node from Heketi management
197
198              Example
199                     $ heketi-cli node delete 886a86a868711bef83001
200
201       heketi-cli node disable <NODE-ID>
202              Disallow usage of a node by placing it offline
203
204              Example
205                     $ heketi-cli node disable 886a86a868711bef83001
206
207       heketi-cli node enable <NODE-ID>
208              Allows node to go online
209
210              Example
211                     $ heketi-cli node enable 886a86a868711bef83001
212
213       heketi-cli node info  <NODE-ID>
214              Retrieves information about node
215
216              Example
217                     $ heketi-cli node info 886a86a868711bef83001
218
219       heketi-cli node list
220              List all nodes in cluster
221
222              Example
223       $ heketi-cli node list
224
225       heketi-cli node settags <NODE-ID> <TAG>:<VALUE> ...
226              Set metadata tags on a given node. Tags are free-form key value
227              pairs that are stored by Heketi and may be used for extra
228              configuration.  One or more <TAG>:<TAG-VALUE> pairs may be
229              provided.
230
231              Options
232
233                     --exact
234                            Optional: Overwrite the existing tags with the
235                            exactly set of tags (and values) specified on this
236                            command line. Without this option, the command
237                            will add or update tags.
238
239              Example
240                     $ heketi-cli node settags 886a86a868711bef83001 arbiter:required flavor:strawberry
241
242       heketi-cli node rmtags <NODE-ID> <TAG> ...
243              Remove metadata tags from a given node.
244
245              Options
246
247                     --all  Optional: Remove all tags from the specified node.
248                            May not be combined with specifying tag names.
249
250              Example
251                     $ heketi-cli node rmtags 886a86a868711bef83001 arbiter
252
253   Setup OpenShift/Kubernetes persistent storage for Heketi
254       heketi-cli setup-openshift-heketi-storage
255              Creates a dedicated GlusterFS volume for Heketi.  Once the
256              volume is created, a Kubernetes/OpenShift list object is created
257              to configure the volume.
258
259              Options
260
261                     --listfile="heketi-storage.json"
262                            Filename to contain list of objects
263
264                     --listfile="heketi-storage.json"
265                            Filename to contain list of objects
266
267                     --durability="replicate"
268                            Optional: Durability type.  Values are:
269
270                            none: No durability, for testing with single
271                            storage server environments.
272
273                            replicate: (Default) Replica volume.
274
275                     --replica=3
276                            Replica value for durability type 'replicate'.
277                            Default is 3
278
279              Example
280                     $ heketi-cli setup-openshift-heketi-storage
281
282   Topology Commands
283       heketi-cli topology load --json=<JSON-FILENAME>
284              Add devices to Heketi from a configuration file
285
286                         Options
287
288                     -j, --json=""
289                            Configuration containing devices, nodes, and
290                            clusters, in JSON format
291
292              Example
293                     $ heketi-cli topology load --json=topo.json
294
295       heketi-cli topology info
296              Retreives information about the current Topology
297
298              Example
299                     $ heketi-cli topology info
300
301   Volume Commands
302       heketi-cli volume create --clusters=<CLUSTER-IDS> --disperse-
303       data=<DISPERSION-VALUE> --durability=<TYPE> --name=<VOLUME-NAME>
304       --redundancy=<REDUNDENCY-VALUE> --replica=<REPLICA-VALUE>
305       --size=<VOLUME-SIZE> --snapshot-factor=<SNAPSHOT-FACTOR-VALUE>
306              Create a GlusterFS volume
307
308              Options
309
310                     --clusters=""
311                            Optional: Comma separated list of cluster ids
312                            where this volume must be allocated.  If omitted,
313                            Heketi will allocate the volume on any of the
314                            configured clusters which have the available
315                            space.  Providing a set of clusters will ensure
316                            Heketi allocates storage for this volume only in
317                            the clusters specified.
318
319                     --disperse-data=4
320                            Optional: Dispersion value for durability type
321                            'disperse'.  Default is 4
322
323                     --durability="replicate"
324                            Optional: Durability type.  Values are:
325
326                            none: No durability. Distributed volume only.
327
328                            replicate: (Default) Distributed-Replica volume.
329
330                            disperse: Distributed-Erasure Coded volume.
331
332                     --gid=0
333                            Optional: Initialize volume with the specified
334                            group id.  Default is 0.
335
336                     --name=""
337                            Optional: Name of volume. Only set if really
338                            necessary
339
340                     --persistent-volume[=false]
341                            Optional: Output to standard out a persistent
342                            volume JSON file for OpenShift or Kubernetes with
343                            the name provided.
344
345                     --persistent-volume-endpoint=""
346                            Optional: Endpoint name for the persistent volume
347
348                     --persistent-volume-file=""
349                            Optional: Create a persistent volume JSON file for
350                            OpenShift or Kubernetes with the name provided.
351
352                     --redundancy=2
353                            Optional: Redundancy value for durability type
354                            'disperse'.  Default is 2.
355
356                     --replica=3
357                            Replica value for durability type 'replicate'.
358                            Default is 3.
359
360                     --size=-1
361                            Size of volume in GiB.
362
363                     --snapshot-factor=1
364                            Optional: Amount of storage to allocate for
365                            snapshot support.  Must be greater 1.0.  For
366                            example if a 10TiB volume requires 5TiB of
367                            snapshot storage, then snapshot-factor would be
368                            set to 1.5.  If the value is set to 1, then
369                            snapshots will not be enabled for this volume.
370
371              Note: The volume size created depends upon the underlying brick
372              size.  For example, for a 2 way/3 way replica volume, the
373              minimum volume size is 1GiB as the underlying minimum brick size
374              is constrained to 1GiB.  So, it is not possible create a volume
375              of size less than 1GiB.
376
377              Examples
378
379                     Create a 100GiB replica 3 volume:
380                            $ heketi-cli volume create --size=100
381
382                     Create a 100GiB replica 3 volume specifying two specific
383                     clusters:
384                            $ heketi-cli volume create --size=100 \
385                                --clusters=0995098e1284ddccb46c7752d142c832,60d46d518074b13a04ce1022c8c7193c
386
387                     Create a 100GiB replica 2 volume with 50GiB of snapshot
388                     storage:
389                            $ heketi-cli volume create --size=100 \
390                                --snapshot-factor=1.5 --replica=2
391
392                     Create a 100GiB distributed volume
393                            $ heketi-cli volume create --size=100 --durability=none
394
395                     Create a 100GiB erasure coded 4+2 volume with 25GiB
396                     snapshot storage:
397                            $ heketi-cli volume create --size=100 --durability=disperse \
398                                --snapshot-factor=1.25
399
400                     Create a 100GiB erasure coded 8+3 volume with 25GiB
401                     snapshot storage:
402                            $ heketi-cli volume create --size=100 --durability=disperse \
403                                --snapshot-factor=1.25 \
404                                --disperse-data=8 --redundancy=3
405
406       heketi-cli volume delete <VOLUME-ID>
407              Deletes the volume
408
409              Example
410                     $ heketi-cli volume delete 886a86a868711bef83001
411
412       heketi-cli volume expand --expand-size=<SIZE> --volume=<VOLUME-ID>
413              Expand a volume
414
415              Options
416
417                     --expand=""
418                            Amount in GiB to add to the volume
419
420                     --volume=""
421                            Id of volume to expand
422
423              Example
424
425                     Add 10GiB to a volume:
426                            $ heketi-cli volume expand --volume=60d46d518074b13a04ce1022c8c7193c
427                                --expand-size=10
428
429       heketi-cli volume info  <VOLUME-ID>
430              Retrieves information about volume
431
432               Example
433                     $ heketi-cli volume info 886a86a868711bef83001
434
435       heketi-cli volume list
436              Lists the volumes managed by Heketi
437
438              Example
439                     $ heketi-cli volume list
440

GLOBAL OPTIONS

442       --json[=false]
443              Print response as JSON
444
445       --secret=""
446              Secret key for specified user.  Can also be set using the
447              environment variable HEKETI_CLI_KEY.
448
449       -s, --server=""
450              Heketi server.  Can also be set using the environment variable
451              HEKETI_CLI_SERVER.
452
453       --user=""
454              Heketi user.  Can also be set using the environment variable
455              HEKETI_CLI_USER.
456
457       -v, --version[=false]
458              Print version.
459

EXAMPLES

461   List Volumes
462       Specify the Heketi server to contact using an environment variable and
463       list the volumes.
464              $ export HEKETI_CLI_SERVER=http://localhost:8080
465              $ heketi-cli volume list
466
467   Create a Volume
468       Create a 4 GiB volume.
469              $ heketi-cli volume create --size 4
470
471   Create an Arbiter Volume
472       Create a 4 GiB volume that uses the arbiter feature.
473              $ heketi-cli volume create --size 4 --gluster-volume-options='user.heketi.arbiter true'
474
476       Copyright (c) 2015-2018 The heketi Authors
477
478
479
480Apr 2016                  Heketi command line program            heketi-cli(8)
Impressum