Revision 61791108

b/doc/iallocator.rst
68 68
~~~~~~~~~~~~~
69 69

  
70 70
The input message will be the JSON encoding of a dictionary containing
71
the following:
71
all the required information to perform the operation. We explain the
72
contents of this dictionary in two parts: common information that every
73
type of operation requires, and operation-specific information.
74

  
75
Common information
76
++++++++++++++++++
77

  
78
All input dictionaries to the IAllocator must carry the following keys:
72 79

  
73 80
version
74 81
  the version of the protocol; this document
......
84 91
  the list of enabled hypervisors
85 92

  
86 93
request
87
  a dictionary containing the request data:
88

  
89
  type
90
    the request type; this can be either ``allocate``, ``relocate`` or
91
    ``multi-evacuate``; the ``allocate`` request is used when a new
92
    instance needs to be placed on the cluster, while the ``relocate``
93
    request is used when an existing instance needs to be moved within
94
    the cluster; the ``multi-evacuate`` protocol requests that the
95
    script computes the optimal relocate solution for all secondary
96
    instances of the given nodes
97

  
98
  The following keys are needed in allocate/relocate mode:
99

  
100
  name
101
    the name of the instance; if the request is a realocation, then this
102
    name will be found in the list of instances (see below), otherwise
103
    is the FQDN of the new instance
104

  
105
  required_nodes
106
    how many nodes should the algorithm return; while this information
107
    can be deduced from the instace's disk template, it's better if
108
    this computation is left to Ganeti as then allocator scripts are
109
    less sensitive to changes to the disk templates
110

  
111
  disk_space_total
112
    the total disk space that will be used by this instance on the
113
    (new) nodes; again, this information can be computed from the list
114
    of instance disks and its template type, but Ganeti is better
115
    suited to compute it
116

  
117
  If the request is an allocation, then there are extra fields in the
118
  request dictionary:
119

  
120
  disks
121
    list of dictionaries holding the disk definitions for this
122
    instance (in the order they are exported to the hypervisor):
123

  
124
    mode
125
      either ``r`` or ``w`` denoting if the disk is read-only or
126
      writable
127

  
128
    size
129
      the size of this disk in mebibytes
130

  
131
  nics
132
    a list of dictionaries holding the network interfaces for this
133
    instance, containing:
134

  
135
    ip
136
      the IP address that Ganeti know for this instance, or null
137

  
138
    mac
139
      the MAC address for this interface
140

  
141
    bridge
142
      the bridge to which this interface will be connected
143

  
144
  vcpus
145
    the number of VCPUs for the instance
146

  
147
  disk_template
148
    the disk template for the instance
149

  
150
  memory
151
   the memory size for the instance
152

  
153
  os
154
   the OS type for the instance
155

  
156
  tags
157
    the list of the instance's tags
158

  
159
  hypervisor
160
    the hypervisor of this instance
161

  
162

  
163
  If the request is of type relocate, then there is one more entry in
164
  the request dictionary, named ``relocate_from``, and it contains a
165
  list of nodes to move the instance away from; note that with Ganeti
166
  2.0, this list will always contain a single node, the current
167
  secondary of the instance.
168

  
169
  The multi-evacuate mode has instead a single request argument:
170

  
171
  evac_nodes
172
    the names of the nodes to be evacuated
94
  a dictionary containing the details of the request; the keys vary
95
  depending on the type of operation that's being requested, as
96
  explained in `Operation-specific input`_ below.
173 97

  
174 98
nodegroups
175 99
  a dictionary with the data for the cluster's node groups; it is keyed
......
254 178
   reserved_memory, free_memory, total_disk, free_disk, total_cpus,
255 179
   i_pri_memory and i_pri_up memory will be absent
256 180

  
181
Operation-specific input
182
++++++++++++++++++++++++
183

  
184
All input dictionaries to the IAllocator carry, in the ``request``
185
dictionary, detailed information about the operation that's being
186
requested. The required keys vary depending on the type of operation, as
187
follows.
188

  
189
In all cases, it includes:
190

  
191
  type
192
    the request type; this can be either ``allocate``, ``relocate`` or
193
    ``multi-evacuate``; the ``allocate`` request is used when a new
194
    instance needs to be placed on the cluster, while the ``relocate``
195
    request is used when an existing instance needs to be moved within
196
    the cluster; the ``multi-evacuate`` protocol requests that the
197
    script computes the optimal relocate solution for all secondary
198
    instances of the given nodes
199

  
200
For both allocate and relocate mode, the following extra keys are needed
201
in the ``request`` dictionary:
202

  
203
  name
204
    the name of the instance; if the request is a realocation, then this
205
    name will be found in the list of instances (see below), otherwise
206
    is the FQDN of the new instance
207

  
208
  required_nodes
209
    how many nodes should the algorithm return; while this information
210
    can be deduced from the instace's disk template, it's better if
211
    this computation is left to Ganeti as then allocator scripts are
212
    less sensitive to changes to the disk templates
213

  
214
  disk_space_total
215
    the total disk space that will be used by this instance on the
216
    (new) nodes; again, this information can be computed from the list
217
    of instance disks and its template type, but Ganeti is better
218
    suited to compute it
219

  
220
Allocation needs, in addition:
221

  
222
  disks
223
    list of dictionaries holding the disk definitions for this
224
    instance (in the order they are exported to the hypervisor):
225

  
226
    mode
227
      either ``r`` or ``w`` denoting if the disk is read-only or
228
      writable
229

  
230
    size
231
      the size of this disk in mebibytes
232

  
233
  nics
234
    a list of dictionaries holding the network interfaces for this
235
    instance, containing:
236

  
237
    ip
238
      the IP address that Ganeti know for this instance, or null
239

  
240
    mac
241
      the MAC address for this interface
242

  
243
    bridge
244
      the bridge to which this interface will be connected
245

  
246
  vcpus
247
    the number of VCPUs for the instance
248

  
249
  disk_template
250
    the disk template for the instance
251

  
252
  memory
253
   the memory size for the instance
254

  
255
  os
256
   the OS type for the instance
257

  
258
  tags
259
    the list of the instance's tags
260

  
261
  hypervisor
262
    the hypervisor of this instance
263

  
264
Relocation:
265

  
266
  relocate_from
267
     a list of nodes to move the instance away from (note that with
268
     Ganeti 2.0, this list will always contain a single node, the
269
     current secondary of the instance)
270

  
271
In the case of multi-evacuate, there's one single request argument (in
272
addition to ``type``):
273

  
274
  evac_nodes
275
    the names of the nodes to be evacuated
257 276

  
258 277
Response message
259 278
~~~~~~~~~~~~~~~~
......
290 309
Input messages to scripts
291 310
~~~~~~~~~~~~~~~~~~~~~~~~~
292 311

  
293
Input message, new instance allocation::
312
Input message, new instance allocation (common elements are listed this
313
time, but not included in further examples below)::
294 314

  
295 315
  {
316
    "version": 2,
317
    "cluster_name": "cluster1.example.com",
296 318
    "cluster_tags": [],
297
    "request": {
298
      "required_nodes": 2,
299
      "name": "instance3.example.com",
300
      "tags": [
301
        "type:test",
302
        "owner:foo"
303
      ],
304
      "type": "allocate",
305
      "disks": [
306
        {
307
          "mode": "w",
308
          "size": 1024
309
        },
310
        {
311
          "mode": "w",
312
          "size": 2048
313
        }
314
      ],
315
      "nics": [
316
        {
317
          "ip": null,
318
          "mac": "00:11:22:33:44:55",
319
          "bridge": null
320
        }
321
      ],
322
      "vcpus": 1,
323
      "disk_template": "drbd",
324
      "memory": 2048,
325
      "disk_space_total": 3328,
326
      "os": "debootstrap+default"
319
    "enabled_hypervisors": [
320
      "xen-pvm"
321
    ],
322
    "nodegroups": {
323
      "f4e06e0d-528a-4963-a5ad-10f3e114232d": {
324
        "name": "default",
325
        "alloc_policy": "preferred"
326
      }
327 327
    },
328
    "cluster_name": "cluster1.example.com",
329 328
    "instances": {
330 329
      "instance1.example.com": {
331 330
        "tags": [],
......
385 384
        "os": "debootstrap+default"
386 385
      }
387 386
    },
388
    "version": 1,
389 387
    "nodes": {
390 388
      "node1.example.com": {
391 389
        "total_disk": 858276,
392 390
        "primary_ip": "198.51.100.1",
393 391
        "secondary_ip": "192.0.2.1",
394 392
        "tags": [],
393
        "group": "f4e06e0d-528a-4963-a5ad-10f3e114232d",
395 394
        "free_memory": 3505,
396 395
        "free_disk": 856740,
397 396
        "total_memory": 4095
......
401 400
        "primary_ip": "198.51.100.2",
402 401
        "secondary_ip": "192.0.2.2",
403 402
        "tags": ["test"],
403
        "group": "f4e06e0d-528a-4963-a5ad-10f3e114232d",
404 404
        "free_memory": 3505,
405 405
        "free_disk": 848320,
406 406
        "total_memory": 4095
......
410 410
        "primary_ip": "198.51.100.3",
411 411
        "secondary_ip": "192.0.2.3",
412 412
        "tags": [],
413
        "group": "f4e06e0d-528a-4963-a5ad-10f3e114232d",
413 414
        "free_memory": 3505,
414 415
        "free_disk": 570648,
415 416
        "total_memory": 4095
416 417
      }
418
    },
419
    "request": {
420
      "type": "allocate",
421
      "name": "instance3.example.com",
422
      "required_nodes": 2,
423
      "disk_space_total": 3328,
424
      "disks": [
425
        {
426
          "mode": "w",
427
          "size": 1024
428
        },
429
        {
430
          "mode": "w",
431
          "size": 2048
432
        }
433
      ],
434
      "nics": [
435
        {
436
          "ip": null,
437
          "mac": "00:11:22:33:44:55",
438
          "bridge": null
439
        }
440
      ],
441
      "vcpus": 1,
442
      "disk_template": "drbd",
443
      "memory": 2048,
444
      "os": "debootstrap+default",
445
      "tags": [
446
        "type:test",
447
        "owner:foo"
448
      ],
449
      hypervisor: "xen-pvm"
417 450
    }
418 451
  }
419 452

  
420
Input message, reallocation. Since only the request entry in the input
421
message is changed, we show only this changed entry::
422

  
423
  "request": {
424
    "relocate_from": [
425
      "node3.example.com"
426
    ],
427
    "required_nodes": 1,
428
    "type": "relocate",
429
    "name": "instance2.example.com",
430
    "disk_space_total": 832
431
  },
453
Input message, reallocation::
432 454

  
455
  {
456
    "version": 2,
457
    ...
458
    "request": {
459
      "type": "relocate",
460
      "name": "instance2.example.com",
461
      "required_nodes": 1,
462
      "disk_space_total": 832,
463
      "relocate_from": [
464
        "node3.example.com"
465
      ]
466
    }
467
  }
433 468

  
434 469
Input message, node evacuation::
435 470

  
436
  "request": {
437
    "evac_nodes": [
438
      "node2"
439
    ],
440
    "type": "multi-evacuate"
441
  },
471
  {
472
    "version": 2,
473
    ...
474
    "request": {
475
      "type": "multi-evacuate",
476
      "evac_nodes": [
477
        "node2"
478
      ],
479
    }
480
  }
442 481

  
443 482

  
444 483
Response messages
......
446 485
Successful response message::
447 486

  
448 487
  {
488
    "success": true,
449 489
    "info": "Allocation successful",
450 490
    "result": [
451 491
      "node2.example.com",
452 492
      "node1.example.com"
453
    ],
454
    "success": true
493
    ]
455 494
  }
456 495

  
457 496
Failed response message::
458 497

  
459 498
  {
499
    "success": false,
460 500
    "info": "Can't find a suitable node for position 2 (already selected: node2.example.com)",
461
    "result": [],
462
    "success": false
501
    "result": []
463 502
  }
464 503

  
465 504
Successful node evacuation message::
466 505

  
467 506
  {
507
    "success": true,
468 508
    "info": "Request successful",
469 509
    "result": [
470 510
      [
......
475 515
        "instance2",
476 516
        "node1"
477 517
      ]
478
    ],
479
    "success": true
518
    ]
480 519
  }
481 520

  
482 521

  

Also available in: Unified diff