Revision 61791108 doc/iallocator.rst
| 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