code.grnet.gr Git - ganeti-local/blob - doc/iallocator.rst

   1 Ganeti automatic instance allocation
   2 ====================================
   3
   4 Documents Ganeti version 2.1
   5
   6 .. contents::
   7
   8 Introduction
   9 ------------
  10
  11 Currently in Ganeti the admin has to specify the exact locations for
  12 an instance's node(s). This prevents a completely automatic node
  13 evacuation, and is in general a nuisance.
  14
  15 The *iallocator* framework will enable automatic placement via
  16 external scripts, which allows customization of the cluster layout per
  17 the site's requirements.
  18
  19 User-visible changes
  20 ~~~~~~~~~~~~~~~~~~~~
  21
  22 There are two parts of the ganeti operation that are impacted by the
  23 auto-allocation: how the cluster knows what the allocator algorithms
  24 are and how the admin uses these in creating instances.
  25
  26 An allocation algorithm is just the filename of a program installed in
  27 a defined list of directories.
  28
  29 Cluster configuration
  30 ~~~~~~~~~~~~~~~~~~~~~
  31
  32 At configure time, the list of the directories can be selected via the
  33 ``--with-iallocator-search-path=LIST`` option, where *LIST* is a
  34 comma-separated list of directories. If not given, this defaults to
  35 ``$libdir/ganeti/iallocators``, i.e. for an installation under
  36 ``/usr``, this will be ``/usr/lib/ganeti/iallocators``.
  37
  38 Ganeti will then search for allocator script in the configured list,
  39 using the first one whose filename matches the one given by the user.
  40
  41 Command line interface changes
  42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  43
  44 The node selection options in instanece add and instance replace disks
  45 can be replace by the new ``--iallocator=NAME`` option (shortened to
  46 ``-I``), which will cause the auto-assignement of nodes with the
  47 passed iallocator. The selected node(s) will be show as part of the
  48 command output.
  49
  50 IAllocator API
  51 --------------
  52
  53 The protocol for communication between Ganeti and an allocator script
  54 will be the following:
  55
  56 #. ganeti launches the program with a single argument, a filename that
  57    contains a JSON-encoded structure (the input message)
  58
  59 #. if the script finishes with exit code different from zero, it is
  60    considered a general failure and the full output will be reported to
  61    the users; this can be the case when the allocator can't parse the
  62    input message
  63
  64 #. if the allocator finishes with exit code zero, it is expected to
  65    output (on its stdout) a JSON-encoded structure (the response)
  66
  67 Input message
  68 ~~~~~~~~~~~~~
  69
  70 The input message will be the JSON encoding of a dictionary containing
  71 the following:
  72
  73 version
  74   the version of the protocol; this document
  75   specifies version 2
  76
  77 cluster_name
  78   the cluster name
  79
  80 cluster_tags
  81   the list of cluster tags
  82
  83 enabled_hypervisors
  84   the list of enabled hypervisors
  85
  86 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   nodes
 172     the names of the nodes to be evacuated
 173
 174 nodegroups
 175   a dictionary with the data for the cluster's node groups; it is keyed
 176   on the group UUID, and the values are a dictionary with the following
 177   keys:
 178
 179   name
 180     the node group name
 181
 182 instances
 183   a dictionary with the data for the current existing instance on the
 184   cluster, indexed by instance name; the contents are similar to the
 185   instance definitions for the allocate mode, with the addition of:
 186
 187   admin_up
 188     if this instance is set to run (but not the actual status of the
 189     instance)
 190
 191   nodes
 192     list of nodes on which this instance is placed; the primary node
 193     of the instance is always the first one
 194
 195 nodes
 196   dictionary with the data for the nodes in the cluster, indexed by
 197   the node name; the dict contains [*]_ :
 198
 199   total_disk
 200     the total disk size of this node (mebibytes)
 201
 202   free_disk
 203     the free disk space on the node
 204
 205   total_memory
 206     the total memory size
 207
 208   free_memory
 209     free memory on the node; note that currently this does not take
 210     into account the instances which are down on the node
 211
 212   total_cpus
 213     the physical number of CPUs present on the machine; depending on
 214     the hypervisor, this might or might not be equal to how many CPUs
 215     the node operating system sees;
 216
 217   primary_ip
 218     the primary IP address of the node
 219
 220   secondary_ip
 221     the secondary IP address of the node (the one used for the DRBD
 222     replication); note that this can be the same as the primary one
 223
 224   tags
 225     list with the tags of the node
 226
 227   master_candidate:
 228     a boolean flag denoting whether this node is a master candidate
 229
 230   drained:
 231     a boolean flag denoting whether this node is being drained
 232
 233   offline:
 234     a boolean flag denoting whether this node is offline
 235
 236   i_pri_memory:
 237     total memory required by primary instances
 238
 239   i_pri_up_memory:
 240     total memory required by running primary instances
 241
 242   group:
 243     the node group that this node belongs to
 244
 245   No allocations should be made on nodes having either the ``drained``
 246   or ``offline`` flags set. More details about these of node status
 247   flags is available in the manpage :manpage:`ganeti(7)`.
 248
 249 .. [*] Note that no run-time data is present for offline or drained
 250    nodes; this means the tags total_memory, reserved_memory,
 251    free_memory, total_disk, free_disk, total_cpus, i_pri_memory and
 252    i_pri_up memory will be absent
 253
 254
 255 Response message
 256 ~~~~~~~~~~~~~~~~
 257
 258 The response message is much more simple than the input one. It is
 259 also a dict having three keys:
 260
 261 success
 262   a boolean value denoting if the allocation was successful or not
 263
 264 info
 265   a string with information from the scripts; if the allocation fails,
 266   this will be shown to the user
 267
 268 result
 269   the output of the algorithm; even if the algorithm failed
 270   (i.e. success is false), this must be returned as an empty list
 271
 272   for allocate/relocate, this is the list of node(s) for the instance;
 273   note that the length of this list must equal the ``requested_nodes``
 274   entry in the input message, otherwise Ganeti will consider the result
 275   as failed
 276
 277   for multi-evacuation mode, this is a list of lists; each element of
 278   the list is a list of instance name and the new secondary node
 279
 280 .. note:: Current Ganeti version accepts either ``result`` or ``nodes``
 281    as a backwards-compatibility measure (older versions only supported
 282    ``nodes``)
 283
 284 Examples
 285 --------
 286
 287 Input messages to scripts
 288 ~~~~~~~~~~~~~~~~~~~~~~~~~
 289
 290 Input message, new instance allocation::
 291
 292   {
 293     "cluster_tags": [],
 294     "request": {
 295       "required_nodes": 2,
 296       "name": "instance3.example.com",
 297       "tags": [
 298         "type:test",
 299         "owner:foo"
 300       ],
 301       "type": "allocate",
 302       "disks": [
 303         {
 304           "mode": "w",
 305           "size": 1024
 306         },
 307         {
 308           "mode": "w",
 309           "size": 2048
 310         }
 311       ],
 312       "nics": [
 313         {
 314           "ip": null,
 315           "mac": "00:11:22:33:44:55",
 316           "bridge": null
 317         }
 318       ],
 319       "vcpus": 1,
 320       "disk_template": "drbd",
 321       "memory": 2048,
 322       "disk_space_total": 3328,
 323       "os": "etch-image"
 324     },
 325     "cluster_name": "cluster1.example.com",
 326     "instances": {
 327       "instance1.example.com": {
 328         "tags": [],
 329         "should_run": false,
 330         "disks": [
 331           {
 332             "mode": "w",
 333             "size": 64
 334           },
 335           {
 336             "mode": "w",
 337             "size": 512
 338           }
 339         ],
 340         "nics": [
 341           {
 342             "ip": null,
 343             "mac": "aa:00:00:00:60:bf",
 344             "bridge": "xen-br0"
 345           }
 346         ],
 347         "vcpus": 1,
 348         "disk_template": "plain",
 349         "memory": 128,
 350         "nodes": [
 351           "nodee1.com"
 352         ],
 353         "os": "etch-image"
 354       },
 355       "instance2.example.com": {
 356         "tags": [],
 357         "should_run": false,
 358         "disks": [
 359           {
 360             "mode": "w",
 361             "size": 512
 362           },
 363           {
 364             "mode": "w",
 365             "size": 256
 366           }
 367         ],
 368         "nics": [
 369           {
 370             "ip": null,
 371             "mac": "aa:00:00:55:f8:38",
 372             "bridge": "xen-br0"
 373           }
 374         ],
 375         "vcpus": 1,
 376         "disk_template": "drbd",
 377         "memory": 512,
 378         "nodes": [
 379           "node2.example.com",
 380           "node3.example.com"
 381         ],
 382         "os": "etch-image"
 383       }
 384     },
 385     "version": 1,
 386     "nodes": {
 387       "node1.example.com": {
 388         "total_disk": 858276,
 389         "primary_ip": "198.51.100.1",
 390         "secondary_ip": "192.0.2.1",
 391         "tags": [],
 392         "free_memory": 3505,
 393         "free_disk": 856740,
 394         "total_memory": 4095
 395       },
 396       "node2.example.com": {
 397         "total_disk": 858240,
 398         "primary_ip": "198.51.100.2",
 399         "secondary_ip": "192.0.2.2",
 400         "tags": ["test"],
 401         "free_memory": 3505,
 402         "free_disk": 848320,
 403         "total_memory": 4095
 404       },
 405       "node3.example.com.com": {
 406         "total_disk": 572184,
 407         "primary_ip": "198.51.100.3",
 408         "secondary_ip": "192.0.2.3",
 409         "tags": [],
 410         "free_memory": 3505,
 411         "free_disk": 570648,
 412         "total_memory": 4095
 413       }
 414     }
 415   }
 416
 417 Input message, reallocation. Since only the request entry in the input
 418 message is changed, we show only this changed entry::
 419
 420   "request": {
 421     "relocate_from": [
 422       "node3.example.com"
 423     ],
 424     "required_nodes": 1,
 425     "type": "relocate",
 426     "name": "instance2.example.com",
 427     "disk_space_total": 832
 428   },
 429
 430
 431 Input message, node evacuation::
 432
 433   "request": {
 434     "evac_nodes": [
 435       "node2"
 436     ],
 437     "type": "multi-evacuate"
 438   },
 439
 440
 441 Response messages
 442 ~~~~~~~~~~~~~~~~~
 443 Successful response message::
 444
 445   {
 446     "info": "Allocation successful",
 447     "result": [
 448       "node2.example.com",
 449       "node1.example.com"
 450     ],
 451     "success": true
 452   }
 453
 454 Failed response message::
 455
 456   {
 457     "info": "Can't find a suitable node for position 2 (already selected: node2.example.com)",
 458     "result": [],
 459     "success": false
 460   }
 461
 462 Successful node evacuation message::
 463
 464   {
 465     "info": "Request successful",
 466     "result": [
 467       [
 468         "instance1",
 469         "node3"
 470       ],
 471       [
 472         "instance2",
 473         "node1"
 474       ]
 475     ],
 476     "success": true
 477   }
 478
 479
 480 Command line messages
 481 ~~~~~~~~~~~~~~~~~~~~~
 482 ::
 483
 484   # gnt-instance add -t plain -m 2g --os-size 1g --swap-size 512m --iallocator dumb-allocator -o etch-image instance3
 485   Selected nodes for the instance: node1.example.com
 486   * creating instance disks...
 487   [...]
 488
 489   # gnt-instance add -t plain -m 3400m --os-size 1g --swap-size 512m --iallocator dumb-allocator -o etch-image instance4
 490   Failure: prerequisites not met for this operation:
 491   Can't compute nodes using iallocator 'dumb-allocator': Can't find a suitable node for position 1 (already selected: )
 492
 493   # gnt-instance add -t drbd -m 1400m --os-size 1g --swap-size 512m --iallocator dumb-allocator -o etch-image instance5
 494   Failure: prerequisites not met for this operation:
 495   Can't compute nodes using iallocator 'dumb-allocator': Can't find a suitable node for position 2 (already selected: node1.example.com)
 496
 497 .. vim: set textwidth=72 :
 498 .. Local Variables:
 499 .. mode: rst
 500 .. fill-column: 72
 501 .. End: