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 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:
  79
  80 version
  81   the version of the protocol; this document
  82   specifies version 2
  83
  84 cluster_name
  85   the cluster name
  86
  87 cluster_tags
  88   the list of cluster tags
  89
  90 enabled_hypervisors
  91   the list of enabled hypervisors
  92
  93 request
  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.
  97
  98 nodegroups
  99   a dictionary with the data for the cluster's node groups; it is keyed
 100   on the group UUID, and the values are a dictionary with the following
 101   keys:
 102
 103   name
 104     the node group name
 105   alloc_policy
 106     the allocation policy of the node group (consult the semantics of
 107     this attribute in the :manpage:`gnt-group(8)` manpage)
 108
 109 instances
 110   a dictionary with the data for the current existing instance on the
 111   cluster, indexed by instance name; the contents are similar to the
 112   instance definitions for the allocate mode, with the addition of:
 113
 114   admin_up
 115     if this instance is set to run (but not the actual status of the
 116     instance)
 117
 118   nodes
 119     list of nodes on which this instance is placed; the primary node
 120     of the instance is always the first one
 121
 122 nodes
 123   dictionary with the data for the nodes in the cluster, indexed by
 124   the node name; the dict contains [*]_ :
 125
 126   total_disk
 127     the total disk size of this node (mebibytes)
 128
 129   free_disk
 130     the free disk space on the node
 131
 132   total_memory
 133     the total memory size
 134
 135   free_memory
 136     free memory on the node; note that currently this does not take
 137     into account the instances which are down on the node
 138
 139   total_cpus
 140     the physical number of CPUs present on the machine; depending on
 141     the hypervisor, this might or might not be equal to how many CPUs
 142     the node operating system sees;
 143
 144   primary_ip
 145     the primary IP address of the node
 146
 147   secondary_ip
 148     the secondary IP address of the node (the one used for the DRBD
 149     replication); note that this can be the same as the primary one
 150
 151   tags
 152     list with the tags of the node
 153
 154   master_candidate:
 155     a boolean flag denoting whether this node is a master candidate
 156
 157   drained:
 158     a boolean flag denoting whether this node is being drained
 159
 160   offline:
 161     a boolean flag denoting whether this node is offline
 162
 163   i_pri_memory:
 164     total memory required by primary instances
 165
 166   i_pri_up_memory:
 167     total memory required by running primary instances
 168
 169   group:
 170     the node group that this node belongs to
 171
 172   No allocations should be made on nodes having either the ``drained``
 173   or ``offline`` flags set. More details about these of node status
 174   flags is available in the manpage :manpage:`ganeti(7)`.
 175
 176 .. [*] Note that no run-time data is present for offline, drained or
 177    non-vm_capable nodes; this means the tags total_memory,
 178    reserved_memory, free_memory, total_disk, free_disk, total_cpus,
 179    i_pri_memory and i_pri_up memory will be absent
 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``,
 193     ``multi-relocate`` or ``multi-evacuate``. The ``allocate`` request
 194     is used when a new instance needs to be placed on the cluster. The
 195     ``relocate`` request is used when an existing instance needs to be
 196     moved within its node group, while the ``multi-relocate`` one is
 197     able to relocate multiple instances across multiple node groups. The
 198     ``multi-evacuate`` protocol requests that the script computes the
 199     optimal relocate solution for all secondary instances of the given
 200     nodes.
 201
 202 For both allocate and relocate mode, the following extra keys are needed
 203 in the ``request`` dictionary:
 204
 205   name
 206     the name of the instance; if the request is a realocation, then this
 207     name will be found in the list of instances (see below), otherwise
 208     is the FQDN of the new instance; type *string*
 209
 210   required_nodes
 211     how many nodes should the algorithm return; while this information
 212     can be deduced from the instace's disk template, it's better if
 213     this computation is left to Ganeti as then allocator scripts are
 214     less sensitive to changes to the disk templates; type *integer*
 215
 216   disk_space_total
 217     the total disk space that will be used by this instance on the
 218     (new) nodes; again, this information can be computed from the list
 219     of instance disks and its template type, but Ganeti is better
 220     suited to compute it; type *integer*
 221
 222 .. pyassert::
 223
 224    constants.DISK_ACCESS_SET == set([constants.DISK_RDONLY,
 225      constants.DISK_RDWR])
 226
 227 Allocation needs, in addition:
 228
 229   disks
 230     list of dictionaries holding the disk definitions for this
 231     instance (in the order they are exported to the hypervisor):
 232
 233     mode
 234       either :pyeval:`constants.DISK_RDONLY` or
 235       :pyeval:`constants.DISK_RDWR` denoting if the disk is read-only or
 236       writable
 237
 238     size
 239       the size of this disk in mebibytes
 240
 241   nics
 242     a list of dictionaries holding the network interfaces for this
 243     instance, containing:
 244
 245     ip
 246       the IP address that Ganeti know for this instance, or null
 247
 248     mac
 249       the MAC address for this interface
 250
 251     bridge
 252       the bridge to which this interface will be connected
 253
 254   vcpus
 255     the number of VCPUs for the instance
 256
 257   disk_template
 258     the disk template for the instance
 259
 260   memory
 261    the memory size for the instance
 262
 263   os
 264    the OS type for the instance
 265
 266   tags
 267     the list of the instance's tags
 268
 269   hypervisor
 270     the hypervisor of this instance
 271
 272 Relocation:
 273
 274   relocate_from
 275      a list of nodes to move the instance away from (note that with
 276      Ganeti 2.0, this list will always contain a single node, the
 277      current secondary of the instance); type *list of strings*
 278
 279 As for ``multi-relocate``, it needs the three following request
 280 arguments:
 281
 282   instances
 283     a list of instance names to relocate; type *list of strings*
 284
 285   reloc_mode
 286     a string indicating the relocation mode; there are three possible
 287     values for this string: *keep_group*, *change_group*, and
 288     *any_group*, the semantics or which are explained in :ref:`the
 289     design document <multi-reloc-detailed-design>`
 290
 291   target_groups
 292     this argument is only accepted when ``reloc_mode``, as explained
 293     above, is *change_group*; if present, it must either be the empty
 294     list, or contain a list of group UUIDs that should be considered for
 295     relocating instances to; type *list of strings*
 296
 297 Finally, in the case of multi-evacuate, there's one single request
 298 argument (in addition to ``type``):
 299
 300   evac_nodes
 301     the names of the nodes to be evacuated; type *list of strings*
 302
 303 Response message
 304 ~~~~~~~~~~~~~~~~
 305
 306 The response message is much more simple than the input one. It is
 307 also a dict having three keys:
 308
 309 success
 310   a boolean value denoting if the allocation was successful or not
 311
 312 info
 313   a string with information from the scripts; if the allocation fails,
 314   this will be shown to the user
 315
 316 result
 317   the output of the algorithm; even if the algorithm failed
 318   (i.e. success is false), this must be returned as an empty list
 319
 320   for allocate/relocate, this is the list of node(s) for the instance;
 321   note that the length of this list must equal the ``requested_nodes``
 322   entry in the input message, otherwise Ganeti will consider the result
 323   as failed
 324
 325   for multi-relocate mode, this is a list of lists of serialized
 326   opcodes. See the :ref:`design document <multi-reloc-result>` for a
 327   detailed dscription.
 328
 329   for multi-evacuation mode, this is a list of lists; each element of
 330   the list is a list of instance name and the new secondary node
 331
 332 .. note:: Current Ganeti version accepts either ``result`` or ``nodes``
 333    as a backwards-compatibility measure (older versions only supported
 334    ``nodes``)
 335
 336 Examples
 337 --------
 338
 339 Input messages to scripts
 340 ~~~~~~~~~~~~~~~~~~~~~~~~~
 341
 342 Input message, new instance allocation (common elements are listed this
 343 time, but not included in further examples below)::
 344
 345   {
 346     "version": 2,
 347     "cluster_name": "cluster1.example.com",
 348     "cluster_tags": [],
 349     "enabled_hypervisors": [
 350       "xen-pvm"
 351     ],
 352     "nodegroups": {
 353       "f4e06e0d-528a-4963-a5ad-10f3e114232d": {
 354         "name": "default",
 355         "alloc_policy": "preferred"
 356       }
 357     },
 358     "instances": {
 359       "instance1.example.com": {
 360         "tags": [],
 361         "should_run": false,
 362         "disks": [
 363           {
 364             "mode": "w",
 365             "size": 64
 366           },
 367           {
 368             "mode": "w",
 369             "size": 512
 370           }
 371         ],
 372         "nics": [
 373           {
 374             "ip": null,
 375             "mac": "aa:00:00:00:60:bf",
 376             "bridge": "xen-br0"
 377           }
 378         ],
 379         "vcpus": 1,
 380         "disk_template": "plain",
 381         "memory": 128,
 382         "nodes": [
 383           "nodee1.com"
 384         ],
 385         "os": "debootstrap+default"
 386       },
 387       "instance2.example.com": {
 388         "tags": [],
 389         "should_run": false,
 390         "disks": [
 391           {
 392             "mode": "w",
 393             "size": 512
 394           },
 395           {
 396             "mode": "w",
 397             "size": 256
 398           }
 399         ],
 400         "nics": [
 401           {
 402             "ip": null,
 403             "mac": "aa:00:00:55:f8:38",
 404             "bridge": "xen-br0"
 405           }
 406         ],
 407         "vcpus": 1,
 408         "disk_template": "drbd",
 409         "memory": 512,
 410         "nodes": [
 411           "node2.example.com",
 412           "node3.example.com"
 413         ],
 414         "os": "debootstrap+default"
 415       }
 416     },
 417     "nodes": {
 418       "node1.example.com": {
 419         "total_disk": 858276,
 420         "primary_ip": "198.51.100.1",
 421         "secondary_ip": "192.0.2.1",
 422         "tags": [],
 423         "group": "f4e06e0d-528a-4963-a5ad-10f3e114232d",
 424         "free_memory": 3505,
 425         "free_disk": 856740,
 426         "total_memory": 4095
 427       },
 428       "node2.example.com": {
 429         "total_disk": 858240,
 430         "primary_ip": "198.51.100.2",
 431         "secondary_ip": "192.0.2.2",
 432         "tags": ["test"],
 433         "group": "f4e06e0d-528a-4963-a5ad-10f3e114232d",
 434         "free_memory": 3505,
 435         "free_disk": 848320,
 436         "total_memory": 4095
 437       },
 438       "node3.example.com.com": {
 439         "total_disk": 572184,
 440         "primary_ip": "198.51.100.3",
 441         "secondary_ip": "192.0.2.3",
 442         "tags": [],
 443         "group": "f4e06e0d-528a-4963-a5ad-10f3e114232d",
 444         "free_memory": 3505,
 445         "free_disk": 570648,
 446         "total_memory": 4095
 447       }
 448     },
 449     "request": {
 450       "type": "allocate",
 451       "name": "instance3.example.com",
 452       "required_nodes": 2,
 453       "disk_space_total": 3328,
 454       "disks": [
 455         {
 456           "mode": "w",
 457           "size": 1024
 458         },
 459         {
 460           "mode": "w",
 461           "size": 2048
 462         }
 463       ],
 464       "nics": [
 465         {
 466           "ip": null,
 467           "mac": "00:11:22:33:44:55",
 468           "bridge": null
 469         }
 470       ],
 471       "vcpus": 1,
 472       "disk_template": "drbd",
 473       "memory": 2048,
 474       "os": "debootstrap+default",
 475       "tags": [
 476         "type:test",
 477         "owner:foo"
 478       ],
 479       hypervisor: "xen-pvm"
 480     }
 481   }
 482
 483 Input message, reallocation::
 484
 485   {
 486     "version": 2,
 487     ...
 488     "request": {
 489       "type": "relocate",
 490       "name": "instance2.example.com",
 491       "required_nodes": 1,
 492       "disk_space_total": 832,
 493       "relocate_from": [
 494         "node3.example.com"
 495       ]
 496     }
 497   }
 498
 499 Input message, node evacuation::
 500
 501   {
 502     "version": 2,
 503     ...
 504     "request": {
 505       "type": "multi-evacuate",
 506       "evac_nodes": [
 507         "node2"
 508       ],
 509     }
 510   }
 511
 512
 513 Response messages
 514 ~~~~~~~~~~~~~~~~~
 515 Successful response message::
 516
 517   {
 518     "success": true,
 519     "info": "Allocation successful",
 520     "result": [
 521       "node2.example.com",
 522       "node1.example.com"
 523     ]
 524   }
 525
 526 Failed response message::
 527
 528   {
 529     "success": false,
 530     "info": "Can't find a suitable node for position 2 (already selected: node2.example.com)",
 531     "result": []
 532   }
 533
 534 Successful node evacuation message::
 535
 536   {
 537     "success": true,
 538     "info": "Request successful",
 539     "result": [
 540       [
 541         "instance1",
 542         "node3"
 543       ],
 544       [
 545         "instance2",
 546         "node1"
 547       ]
 548     ]
 549   }
 550
 551
 552 Command line messages
 553 ~~~~~~~~~~~~~~~~~~~~~
 554 ::
 555
 556   # gnt-instance add -t plain -m 2g --os-size 1g --swap-size 512m --iallocator hail -o debootstrap+default instance3
 557   Selected nodes for the instance: node1.example.com
 558   * creating instance disks...
 559   [...]
 560
 561   # gnt-instance add -t plain -m 3400m --os-size 1g --swap-size 512m --iallocator hail -o debootstrap+default instance4
 562   Failure: prerequisites not met for this operation:
 563   Can't compute nodes using iallocator 'hail': Can't find a suitable node for position 1 (already selected: )
 564
 565   # gnt-instance add -t drbd -m 1400m --os-size 1g --swap-size 512m --iallocator hail -o debootstrap+default instance5
 566   Failure: prerequisites not met for this operation:
 567   Can't compute nodes using iallocator 'hail': Can't find a suitable node for position 2 (already selected: node1.example.com)
 568
 569 Reference implementation
 570 ~~~~~~~~~~~~~~~~~~~~~~~~
 571
 572 Ganeti's default iallocator is "hail" which is available when "htools"
 573 components have been enabled at build time (see :doc:`install-quick` for
 574 more details).
 575
 576 .. vim: set textwidth=72 :
 577 .. Local Variables:
 578 .. mode: rst
 579 .. fill-column: 72
 580 .. End: