Update documentation of --print-jobid
[ganeti-github.git] / man / gnt-group.rst
1 gnt-group(8) Ganeti | Version @GANETI_VERSION@
2 ==============================================
3
4 Name
5 ----
6
7 gnt-group - Ganeti node-group administration
8
9 Synopsis
10 --------
11
12 **gnt-group** {command} [arguments...]
13
14 DESCRIPTION
15 -----------
16
17 The **gnt-group** command is used for node group administration in
18 the Ganeti system.
19
20 COMMANDS
21 --------
22
23 ADD
24 ~~~
25
26 | **add** [\--submit] [\--print-jobid]
27 | [\--node-parameters=*NDPARAMS*]
28 | [\--alloc-policy=*POLICY*]
29 | [{-D|\--disk-parameters} *disk-template*:*disk-param*=*value*[,*disk-param*=*value*...]]
30 | [\--ipolicy-bounds-specs *bound_ispecs*]
31 | [\--ipolicy-disk-templates *template* [,*template*...]]
32 | [\--ipolicy-spindle-ratio *ratio*]
33 | [\--ipolicy-vcpu-ratio *ratio*]
34 | [\--disk-state *diskstate*]
35 | [\--hypervisor-state *hvstate*]
36 | {*group*}
37
38 Creates a new group with the given name. The node group will be
39 initially empty; to add nodes to it, use ``gnt-group assign-nodes``.
40
41 The ``--node-parameters`` option allows you to set default node
42 parameters for nodes in the group. Please see **ganeti**\(7) for more
43 information about supported key=value pairs and their corresponding
44 options.
45
46 The ``--alloc-policy`` option allows you to set an allocation policy for
47 the group at creation time. Possible values are:
48
49 unallocable
50     nodes in the group should not be candidates for instance allocation,
51     and the operation (e.g., instance creation) should fail if only
52     groups in this state could be found to satisfy the requirements.
53
54 last_resort
55     nodes in the group should not be used for instance allocations,
56     unless this would be the only way to have the operation succeed.
57
58 preferred
59     nodes in the group can be used freely for allocation of instances
60     (this is the default). Note that prioritization among groups in this
61     state will be deferred to the iallocator plugin that's being used.
62
63 The ``-D (--disk-parameters)`` option allows you to set the disk
64 parameters for the node group; please see the section about
65 **gnt-cluster add** in **gnt-cluster**\(8) for more information about
66 disk parameters
67
68 The ``--ipolicy-...`` options specify instance policies on the node
69 group, and are documented in the **gnt-cluster**\(8) man page.
70
71 See **ganeti**\(7) for a description of ``--submit`` and other common
72 options.
73
74 ASSIGN-NODES
75 ~~~~~~~~~~~~
76
77 | **assign-nodes**
78 | [\--force] [\--submit] [\--print-jobid]
79 | {*group*} {*node*...}
80
81 Assigns one or more nodes to the specified group, moving them from their
82 original group (or groups).
83
84 By default, this command will refuse to proceed if the move would split
85 between groups any instance that was not previously split (a split
86 instance is an instance with a mirrored disk template, e.g. DRBD, that
87 has the primary and secondary nodes in different node groups). You can
88 force the operation with ``--force``.
89
90 See **ganeti**\(7) for a description of ``--submit`` and other common
91 options.
92
93 MODIFY
94 ~~~~~~
95
96 | **modify** [\--submit] [\--print-jobid]
97 | [\--node-parameters=*NDPARAMS*]
98 | [\--alloc-policy=*POLICY*]
99 | [\--hypervisor-state *hvstate*]
100 | [{-D|\--disk-parameters} *disk-template*:*disk-param*=*value*[,*disk-param*=*value*...]]
101 | [\--disk-state *diskstate*]
102 | [\--ipolicy-bounds-specs *bound_ispecs*]
103 | [\--ipolicy-disk-templates *template* [,*template*...]]
104 | [\--ipolicy-spindle-ratio *ratio*]
105 | [\--ipolicy-vcpu-ratio *ratio*]
106 | {*group*}
107
108 Modifies some parameters from the node group.
109
110 The ``--node-parameters`` and ``--alloc-policy`` options are documented
111 in the **add** command above. ``--hypervisor-state`` as well as
112 ``--disk-state`` are documented in detail in **ganeti**\(7).
113
114 The ``--node-parameters``, ``--alloc-policy``, ``-D
115 (--disk-parameters)`` options are documented in the **add** command
116 above.
117
118 The ``--ipolicy-...`` options specify instance policies on the node
119 group, and are documented in the **gnt-cluster**\(8) man page.
120
121 See **ganeti**\(7) for a description of ``--submit`` and other common
122 options.
123
124 REMOVE
125 ~~~~~~
126
127 | **remove** [\--submit] [\--print-jobid] {*group*}
128
129 Deletes the indicated node group, which must be empty. There must always be at
130 least one group, so the last group cannot be removed.
131
132 See **ganeti**\(7) for a description of ``--submit`` and other common
133 options.
134
135 LIST
136 ~~~~
137
138 | **list** [\--no-headers] [\--separator=*SEPARATOR*] [-v]
139 | [-o *[+]FIELD,...*] [\--filter] [group...]
140
141 Lists all existing node groups in the cluster.
142
143 The ``--no-headers`` option will skip the initial header line. The
144 ``--separator`` option takes an argument which denotes what will be
145 used between the output fields. Both these options are to help
146 scripting.
147
148 The ``-v`` option activates verbose mode, which changes the display of
149 special field states (see **ganeti**\(7)).
150
151 The ``-o`` option takes a comma-separated list of output fields.
152 If the value of the option starts with the character ``+``, the new
153 fields will be added to the default list. This allows one to quickly
154 see the default list plus a few other fields, instead of retyping
155 the entire list of fields.
156
157 The available fields and their meaning are:
158
159 @QUERY_FIELDS_GROUP@
160
161 If exactly one argument is given and it appears to be a query filter
162 (see **ganeti**\(7)), the query result is filtered accordingly. For
163 ambiguous cases (e.g. a single field name as a filter) the ``--filter``
164 (``-F``) option forces the argument to be treated as a filter.
165
166 If no group names are given, then all groups are included. Otherwise,
167 only the named groups will be listed.
168
169 LIST-FIELDS
170 ~~~~~~~~~~~
171
172 **list-fields** [field...]
173
174 List available fields for node groups.
175
176 RENAME
177 ~~~~~~
178
179 | **rename** [\--submit] [\--print-jobid] {*oldname*} {*newname*}
180
181 Renames a given group from *oldname* to *newname*.
182
183 See **ganeti**\(7) for a description of ``--submit`` and other common
184 options.
185
186
187 EVACUATE
188 ~~~~~~~~
189
190 | **evacuate** [\--submit] [\--print-jobid] [\--sequential] [\--force-failover]
191 | [\--iallocator *NAME*] [\--to *GROUP*...] {*group*}
192
193 This command will move all instances out of the given node group.
194 Instances are placed in a new group by an iallocator, either given on
195 the command line or as a cluster default.
196
197 If no specific destination groups are specified using ``--to``, all
198 groups except the evacuated group are considered.
199
200 The moves of the individual instances are handled as separate jobs
201 to allow for maximal parallelism. If the ``--sequential`` option is
202 given, the moves of the individual instances will be executed sequentially.
203 This can be usefull if the link between the groups is vulnerable to
204 congestion. If the ``--force-failover`` option is given, no migrations
205 will be made. This might be necessary if the group being evacuated is
206 too different from the other groups in the cluster.
207
208 See **ganeti**\(7) for a description of ``--submit`` and other common
209 options.
210
211 Example::
212
213     # gnt-group evacuate -I hail --to rack4 rack1
214
215
216 Tags
217 ~~~~
218
219 ADD-TAGS
220 ^^^^^^^^
221
222 **add-tags** [\--from *file*] {*groupname*} {*tag*...}
223
224 Add tags to the given node group. If any of the tags contains invalid
225 characters, the entire operation will abort.
226
227 If the ``--from`` option is given, the list of tags will be extended
228 with the contents of that file (each line becomes a tag). In this case,
229 there is not need to pass tags on the command line (if you do, both
230 sources will be used). A file name of ``-`` will be interpreted as
231 stdin.
232
233 LIST-TAGS
234 ^^^^^^^^^
235
236 **list-tags** {*groupname*}
237
238 List the tags of the given node group.
239
240 REMOVE-TAGS
241 ^^^^^^^^^^^
242
243 **remove-tags** [\--from *file*] {*groupname*} {*tag*...}
244
245 Remove tags from the given node group. If any of the tags are not
246 existing on the node, the entire operation will abort.
247
248 If the ``--from`` option is given, the list of tags to be removed will
249 be extended with the contents of that file (each line becomes a tag). In
250 this case, there is not need to pass tags on the command line (if you
251 do, tags from both sources will be removed). A file name of ``-`` will
252 be interpreted as stdin.
253
254 INFO
255 ~~~~
256
257 **info** [*group*...]
258
259 Shows config information for all (or given) groups.
260
261 SHOW-ISPECS-CMD
262 ~~~~~~~~~~~~~~~
263
264 **show-ispecs-cmd** [\--include-defaults] [*group*...]
265
266 Shows the command line that can be used to recreate the given groups (or
267 all groups, if none is given) with the same options relative to specs in
268 the instance policies.
269
270 If ``--include-defaults`` is specified, include also the default values
271 (i.e. the cluster-level settings), and not only the configuration items
272 that a group overrides.
273
274
275 .. vim: set textwidth=72 :
276 .. Local Variables:
277 .. mode: rst
278 .. fill-column: 72
279 .. End: