4 Documents Ganeti version |version|
11 Ganeti supports a remote API for enable external tools to easily
12 retrieve information about a cluster's state. The remote API daemon,
13 *ganeti-rapi*, is automatically started on the master node. By default
14 it runs on TCP port 5080, but this can be changed either in
15 ``.../constants.py`` or via the command line parameter *-p*. SSL mode,
16 which is used by default, can also be disabled by passing command line
24 ``ganeti-rapi`` reads users and passwords from a file (usually
25 ``/var/lib/ganeti/rapi/users``) on startup. Changes to the file will be
28 Lines starting with the hash sign (``#``) are treated as comments. Each
29 line consists of two or three fields separated by whitespace. The first
30 two fields are for username and password. The third field is optional
31 and can be used to specify per-user options (separated by comma without
32 spaces). Available options:
36 rapi.RAPI_ACCESS_ALL == set([
37 rapi.RAPI_ACCESS_WRITE,
38 rapi.RAPI_ACCESS_READ,
41 :pyeval:`rapi.RAPI_ACCESS_WRITE`
42 Enables the user to execute operations modifying the cluster. Implies
43 :pyeval:`rapi.RAPI_ACCESS_READ` access.
44 :pyeval:`rapi.RAPI_ACCESS_READ`
45 Allow access to operations querying for information.
47 Passwords can either be written in clear text or as a hash. Clear text
48 passwords may not start with an opening brace (``{``) or they must be
49 prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash
50 of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n
51 'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix
52 it with ``{ha1}``. Using the scheme prefix for all passwords is
53 recommended. Scheme prefixes are not case sensitive.
57 # Give Jack and Fred read-only access
59 fred {cleartext}foo555
61 # Give write access to an imaginary instance creation script
62 autocreator xyz789 write
64 # Hashed password for Jessica
65 jessica {HA1}7046452df2cbb530877058712cf17bd4 write
67 # Monitoring can query for values
68 monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read
70 # A user who can read and write (the former is implied by granting
72 superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read,write
75 .. [#pwhash] Using the MD5 hash of username, realm and password is
76 described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
77 and 3.3. The reason for using it over another algorithm is forward
78 compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
79 authentication in the future, the same hash could be used.
80 In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
81 API``, can only be changed by modifying the source code.
87 The protocol used is JSON_ over HTTP designed after the REST_ principle.
88 HTTP Basic authentication as per :rfc:`2617` is supported.
90 .. _JSON: http://www.json.org/
91 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
93 HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
94 header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
95 (HTTP/1.1), section 7.2.1).
98 A note on JSON as used by RAPI
99 ++++++++++++++++++++++++++++++
101 JSON_ as used by Ganeti RAPI does not conform to the specification in
102 :rfc:`4627`. Section 2 defines a JSON text to be either an object
103 (``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
104 of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
105 some requests or responses. Changing this now would likely break
106 existing clients and cause a lot of trouble.
110 Unlike Python's `JSON encoder and decoder
111 <http://docs.python.org/library/json.html>`_, other programming
112 languages or libraries may only provide a strict implementation, not
113 allowing plain values. For those, responses can usually be wrapped in an
114 array whose first element is then used, e.g. the response ``"1234"``
115 becomes ``["1234"]``. This works equally well for more complex values.
120 # Insert code to get response here
121 response = "\"1234\""
123 decoded = JSON.parse("[#{response}]").first
125 Short of modifying the encoder to allow encoding to a less strict
126 format, requests will have to be formatted by hand. Newer RAPI requests
127 already use a dictionary as their input data and shouldn't cause any
134 According to :rfc:`2616` the main difference between PUT and POST is
135 that POST can create new resources but PUT can only create the resource
136 the URI was pointing to on the PUT request.
138 Unfortunately, due to historic reasons, the Ganeti RAPI library is not
139 consistent with this usage, so just use the methods as documented below
142 For more details have a look in the source code at
143 ``lib/rapi/rlib2.py``.
146 Generic parameter types
147 -----------------------
149 A few generic refered parameter types and the values they allow.
154 A boolean option will accept ``1`` or ``0`` as numbers but not
155 i.e. ``True`` or ``False``.
160 A few parameter mean the same thing across all resources which implement
166 Bulk-mode means that for the resources which usually return just a list
167 of child resources (e.g. ``/2/instances`` which returns just instance
168 names), the output will instead contain detailed data for all these
169 subresources. This is more efficient than query-ing the sub-resources
175 The boolean *dry-run* argument, if provided and set, signals to Ganeti
176 that the job should not be executed, only the pre-execution checks will
179 This is useful in trying to determine (without guarantees though, as in
180 the meantime the cluster state could have changed) if the operation is
181 likely to succeed or at least start executing.
186 Force operation to continue even if it will cause the cluster to become
187 inconsistent (e.g. because there are not enough master candidates).
192 Some parameters are not straight forward, so we describe them in details
200 The instance policy specification is a dict with the following fields:
204 constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN,
205 constants.ISPECS_MAX,
206 constants.ISPECS_STD,
207 constants.IPOLICY_DTS,
208 constants.IPOLICY_VCPU_RATIO,
209 constants.IPOLICY_SPINDLE_RATIO])
214 (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
215 set([constants.ISPEC_MEM_SIZE,
216 constants.ISPEC_DISK_SIZE,
217 constants.ISPEC_DISK_COUNT,
218 constants.ISPEC_CPU_COUNT,
219 constants.ISPEC_NIC_COUNT,
220 constants.ISPEC_SPINDLE_USE]))
222 .. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
223 .. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
224 .. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
227 |ispec-min|, |ispec-max|, |ispec-std|
228 A sub- `dict` with the following fields, which sets the limit and standard
229 values of the instances:
231 :pyeval:`constants.ISPEC_MEM_SIZE`
232 The size in MiB of the memory used
233 :pyeval:`constants.ISPEC_DISK_SIZE`
234 The size in MiB of the disk used
235 :pyeval:`constants.ISPEC_DISK_COUNT`
236 The numbers of disks used
237 :pyeval:`constants.ISPEC_CPU_COUNT`
238 The numbers of cpus used
239 :pyeval:`constants.ISPEC_NIC_COUNT`
240 The numbers of nics used
241 :pyeval:`constants.ISPEC_SPINDLE_USE`
242 The numbers of virtual disk spindles used by this instance. They are
243 not real in the sense of actual HDD spindles, but useful for
244 accounting the spindle usage on the residing node
245 :pyeval:`constants.IPOLICY_DTS`
246 A `list` of disk templates allowed for instances using this policy
247 :pyeval:`constants.IPOLICY_VCPU_RATIO`
248 Maximum ratio of virtual to physical CPUs (`float`)
249 :pyeval:`constants.IPOLICY_SPINDLE_RATIO`
250 Maximum ratio of instances to their node's ``spindle_count`` (`float`)
255 You can access the API using your favorite programming language as long
256 as it supports network connections.
261 Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.
266 .. highlight:: shell-example
270 $ wget -q -O - https://%CLUSTERNAME%:5080/2/info
274 $ curl https://%CLUSTERNAME%:5080/2/info
280 .. highlight:: python
285 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
292 .. warning:: While it's possible to use JavaScript, it poses several
293 potential problems, including browser blocking request due to
294 non-standard ports or different domain names. Fetching the data on
295 the webserver is easier.
297 .. highlight:: javascript
301 var url = 'https://CLUSTERNAME:5080/2/info';
303 var xmlreq = new XMLHttpRequest();
304 xmlreq.onreadystatechange = function () {
305 if (xmlreq.readyState != 4) return;
306 if (xmlreq.status == 200) {
307 info = eval("(" + xmlreq.responseText + ")");
310 alert('Error fetching cluster info');
314 xmlreq.open('GET', url, true);
320 .. highlight:: javascript
325 The root resource. Has no function, but for legacy reasons the ``GET``
331 Has no function, but for legacy reasons the ``GET`` method is supported.
336 Cluster information resource.
338 It supports the following commands: ``GET``.
343 Returns cluster information.
348 "config_version": 2000000,
350 "software_version": "2.0.0~beta2",
351 "os_api_version": 10,
353 "candidate_pool_size": 10,
354 "enabled_hypervisors": [
360 "default_hypervisor": "fake",
361 "master": "node1.example.com",
366 "protocol_version": 20,
369 "auto_balance": true,
378 ``/2/redistribute-config``
379 ++++++++++++++++++++++++++
381 Redistribute configuration to all nodes.
383 It supports the following commands: ``PUT``.
388 Redistribute configuration to all nodes. The result will be a job id.
392 .. opcode_result:: OP_CLUSTER_REDIST_CONF
401 Returns a list of features supported by the RAPI server. Available
406 rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
407 rlib2._INST_REINSTALL_REQV1,
408 rlib2._NODE_MIGRATE_REQV1,
409 rlib2._NODE_EVAC_RES1])
411 :pyeval:`rlib2._INST_CREATE_REQV1`
412 Instance creation request data version 1 supported
413 :pyeval:`rlib2._INST_REINSTALL_REQV1`
414 Instance reinstall supports body parameters
415 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
416 Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
417 request body parameters
418 :pyeval:`rlib2._NODE_EVAC_RES1`
419 Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
420 a new-style result (see resource description)
424 ++++++++++++++++++++++++++++++++++++++++
426 Modifies cluster parameters.
428 Supports the following commands: ``PUT``.
437 .. opcode_params:: OP_CLUSTER_SET_PARAMS
441 .. opcode_result:: OP_CLUSTER_SET_PARAMS
449 It supports the following commands: ``GET``, ``POST``.
454 Returns a list of all existing node groups.
461 "uri": "\/2\/groups\/group1"
465 "uri": "\/2\/groups\/group2"
469 If the optional bool *bulk* argument is provided and set to a true value
470 (i.e ``?bulk=1``), the output contains detailed information about node
473 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
485 "uuid": "0d7d407c-262e-49af-881a-6a430034bf43",
494 "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c",
503 Creates a node group.
505 If the optional bool *dry-run* argument is provided, the job will not be
506 actually executed, only the pre-execution checks will be done.
508 Returns: a job ID that can be used later for polling.
512 .. opcode_params:: OP_GROUP_ADD
514 Earlier versions used a parameter named ``name`` which, while still
515 supported, has been renamed to ``group_name``.
519 .. opcode_result:: OP_GROUP_ADD
522 ``/2/groups/[group_name]``
523 ++++++++++++++++++++++++++
525 Returns information about a node group.
527 It supports the following commands: ``GET``, ``DELETE``.
532 Returns information about a node group, similar to the bulk output from
535 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
540 Deletes a node group.
542 It supports the ``dry-run`` argument.
546 .. opcode_result:: OP_GROUP_REMOVE
549 ``/2/groups/[group_name]/modify``
550 +++++++++++++++++++++++++++++++++
552 Modifies the parameters of a node group.
554 Supports the following commands: ``PUT``.
563 .. opcode_params:: OP_GROUP_SET_PARAMS
568 .. opcode_result:: OP_GROUP_SET_PARAMS
571 ``/2/groups/[group_name]/rename``
572 +++++++++++++++++++++++++++++++++
574 Renames a node group.
576 Supports the following commands: ``PUT``.
585 .. opcode_params:: OP_GROUP_RENAME
590 .. opcode_result:: OP_GROUP_RENAME
593 ``/2/groups/[group_name]/assign-nodes``
594 +++++++++++++++++++++++++++++++++++++++
596 Assigns nodes to a group.
598 Supports the following commands: ``PUT``.
603 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
607 .. opcode_params:: OP_GROUP_ASSIGN_NODES
608 :exclude: group_name, force, dry_run
612 .. opcode_result:: OP_GROUP_ASSIGN_NODES
615 ``/2/groups/[group_name]/tags``
616 +++++++++++++++++++++++++++++++
618 Manages per-nodegroup tags.
620 Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
625 Returns a list of tags.
629 ["tag1", "tag2", "tag3"]
636 The request as a list of strings should be ``PUT`` to this URI. The
637 result will be a job id.
639 It supports the ``dry-run`` argument.
647 In order to delete a set of tags, the DELETE request should be addressed
650 /tags?tag=[tag]&tag=[tag]
652 It supports the ``dry-run`` argument.
658 The networks resource.
660 It supports the following commands: ``GET``, ``POST``.
665 Returns a list of all existing networks.
672 "uri": "\/2\/networks\/network1"
676 "uri": "\/2\/networks\/network2"
680 If the optional bool *bulk* argument is provided and set to a true value
681 (i.e ``?bulk=1``), the output contains detailed information about networks
684 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
690 'external_reservations': '10.0.0.0, 10.0.0.1, 10.0.0.15',
692 'gateway': '10.0.0.1',
694 'group_list': ['default(bridged, prv0)'],
697 'map': 'XX.............X',
699 'network': '10.0.0.0/28',
713 If the optional bool *dry-run* argument is provided, the job will not be
714 actually executed, only the pre-execution checks will be done.
716 Returns: a job ID that can be used later for polling.
720 .. opcode_params:: OP_NETWORK_ADD
724 .. opcode_result:: OP_NETWORK_ADD
727 ``/2/networks/[network_name]``
728 ++++++++++++++++++++++++++++++
730 Returns information about a network.
732 It supports the following commands: ``GET``, ``DELETE``.
737 Returns information about a network, similar to the bulk output from
740 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
747 It supports the ``dry-run`` argument.
751 .. opcode_result:: OP_NETWORK_REMOVE
754 ``/2/networks/[network_name]/modify``
755 +++++++++++++++++++++++++++++++++++++
757 Modifies the parameters of a network.
759 Supports the following commands: ``PUT``.
768 .. opcode_params:: OP_NETWORK_SET_PARAMS
772 .. opcode_result:: OP_NETWORK_SET_PARAMS
775 ``/2/networks/[network_name]/connect``
776 ++++++++++++++++++++++++++++++++++++++
778 Connects a network to a nodegroup.
780 Supports the following commands: ``PUT``.
785 Returns a job ID. It supports the ``dry-run`` arguments.
789 .. opcode_params:: OP_NETWORK_CONNECT
793 .. opcode_result:: OP_NETWORK_CONNECT
796 ``/2/networks/[network_name]/disconnect``
797 +++++++++++++++++++++++++++++++++++++++++
799 Disonnects a network from a nodegroup.
801 Supports the following commands: ``PUT``.
806 Returns a job ID. It supports the ``dry-run`` arguments.
810 .. opcode_params:: OP_NETWORK_DISCONNECT
814 .. opcode_result:: OP_NETWORK_DISCONNECT
817 ``/2/networks/[network_name]/tags``
818 +++++++++++++++++++++++++++++++++++
820 Manages per-network tags.
822 Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
827 Returns a list of tags.
831 ["tag1", "tag2", "tag3"]
838 The request as a list of strings should be ``PUT`` to this URI. The
839 result will be a job id.
841 It supports the ``dry-run`` argument.
849 In order to delete a set of tags, the DELETE request should be addressed
852 /tags?tag=[tag]&tag=[tag]
854 It supports the ``dry-run`` argument.
857 ``/2/instances-multi-alloc``
858 ++++++++++++++++++++++++++++
860 Tries to allocate multiple instances.
862 It supports the following commands: ``POST``
869 .. opcode_params:: OP_INSTANCE_MULTI_ALLOC
873 .. opcode_result:: OP_INSTANCE_MULTI_ALLOC
879 The instances resource.
881 It supports the following commands: ``GET``, ``POST``.
886 Returns a list of all available instances.
892 "name": "web.example.com",
893 "uri": "\/instances\/web.example.com"
896 "name": "mail.example.com",
897 "uri": "\/instances\/mail.example.com"
901 If the optional bool *bulk* argument is provided and set to a true value
902 (i.e ``?bulk=1``), the output contains detailed information about
905 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
916 "name": "web.example.com",
917 "tags": ["tag1", "tag2"],
925 "pnode": "node1.example.com",
926 "nic.macs": ["01:23:45:67:89:01"],
927 "snodes": ["node2.example.com"],
928 "disk_template": "drbd",
943 If the optional bool *dry-run* argument is provided, the job will not be
944 actually executed, only the pre-execution checks will be done. Query-ing
945 the job result will return, in both dry-run and normal case, the list of
946 nodes selected for the instance.
948 Returns: a job ID that can be used later for polling.
952 ``__version__`` (int, required)
953 Must be ``1`` (older Ganeti versions used a different format for
954 instance creation requests, version ``0``, but that format is no
957 .. opcode_params:: OP_INSTANCE_CREATE
959 Earlier versions used parameters named ``name`` and ``os``. These have
960 been replaced by ``instance_name`` and ``os_type`` to match the
961 underlying opcode. The old names can still be used.
965 .. opcode_result:: OP_INSTANCE_CREATE
968 ``/2/instances/[instance_name]``
969 ++++++++++++++++++++++++++++++++
971 Instance-specific resource.
973 It supports the following commands: ``GET``, ``DELETE``.
978 Returns information about an instance, similar to the bulk output from
981 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
988 It supports the ``dry-run`` argument.
992 .. opcode_result:: OP_INSTANCE_REMOVE
995 ``/2/instances/[instance_name]/info``
996 +++++++++++++++++++++++++++++++++++++++
998 It supports the following commands: ``GET``.
1003 Requests detailed information about the instance. An optional parameter,
1004 ``static`` (bool), can be set to return only static information from the
1005 configuration without querying the instance's nodes. The result will be
1010 .. opcode_result:: OP_INSTANCE_QUERY_DATA
1013 ``/2/instances/[instance_name]/reboot``
1014 +++++++++++++++++++++++++++++++++++++++
1016 Reboots URI for an instance.
1018 It supports the following commands: ``POST``.
1023 Reboots the instance.
1025 The URI takes optional ``type=soft|hard|full`` and
1026 ``ignore_secondaries=0|1`` parameters.
1028 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
1029 without terminating the hypervisor. ``hard`` means full shutdown
1030 (including terminating the hypervisor process) and startup again.
1031 ``full`` is like ``hard`` but also recreates the configuration from
1032 ground up as if you would have done a ``gnt-instance shutdown`` and
1033 ``gnt-instance start`` on it.
1035 ``ignore_secondaries`` is a bool argument indicating if we start the
1036 instance even if secondary disks are failing.
1038 It supports the ``dry-run`` argument.
1042 .. opcode_result:: OP_INSTANCE_REBOOT
1045 ``/2/instances/[instance_name]/shutdown``
1046 +++++++++++++++++++++++++++++++++++++++++
1048 Instance shutdown URI.
1050 It supports the following commands: ``PUT``.
1055 Shutdowns an instance.
1057 It supports the ``dry-run`` argument.
1059 .. opcode_params:: OP_INSTANCE_SHUTDOWN
1060 :exclude: instance_name, dry_run
1064 .. opcode_result:: OP_INSTANCE_SHUTDOWN
1067 ``/2/instances/[instance_name]/startup``
1068 ++++++++++++++++++++++++++++++++++++++++
1070 Instance startup URI.
1072 It supports the following commands: ``PUT``.
1077 Startup an instance.
1079 The URI takes an optional ``force=1|0`` parameter to start the
1080 instance even if secondary disks are failing.
1082 It supports the ``dry-run`` argument.
1086 .. opcode_result:: OP_INSTANCE_STARTUP
1089 ``/2/instances/[instance_name]/reinstall``
1090 ++++++++++++++++++++++++++++++++++++++++++++++
1092 Installs the operating system again.
1094 It supports the following commands: ``POST``.
1103 ``os`` (string, required)
1104 Instance operating system.
1105 ``start`` (bool, defaults to true)
1106 Whether to start instance after reinstallation.
1108 Dictionary with (temporary) OS parameters.
1110 For backwards compatbility, this resource also takes the query
1111 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
1112 clients should use the body parameters.
1115 ``/2/instances/[instance_name]/replace-disks``
1116 ++++++++++++++++++++++++++++++++++++++++++++++
1118 Replaces disks on an instance.
1120 It supports the following commands: ``POST``.
1129 .. opcode_params:: OP_INSTANCE_REPLACE_DISKS
1130 :exclude: instance_name
1132 Ganeti 2.4 and below used query parameters. Those are deprecated and
1133 should no longer be used.
1137 .. opcode_result:: OP_INSTANCE_REPLACE_DISKS
1140 ``/2/instances/[instance_name]/activate-disks``
1141 +++++++++++++++++++++++++++++++++++++++++++++++
1143 Activate disks on an instance.
1145 It supports the following commands: ``PUT``.
1150 Takes the bool parameter ``ignore_size``. When set ignore the recorded
1151 size (useful for forcing activation when recorded size is wrong).
1155 .. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
1158 ``/2/instances/[instance_name]/deactivate-disks``
1159 +++++++++++++++++++++++++++++++++++++++++++++++++
1161 Deactivate disks on an instance.
1163 It supports the following commands: ``PUT``.
1168 Takes no parameters.
1172 .. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS
1175 ``/2/instances/[instance_name]/recreate-disks``
1176 +++++++++++++++++++++++++++++++++++++++++++++++++
1178 Recreate disks of an instance. Supports the following commands:
1188 .. opcode_params:: OP_INSTANCE_RECREATE_DISKS
1189 :exclude: instance_name
1193 .. opcode_result:: OP_INSTANCE_RECREATE_DISKS
1196 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
1197 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1199 Grows one disk of an instance.
1201 Supports the following commands: ``POST``.
1210 .. opcode_params:: OP_INSTANCE_GROW_DISK
1211 :exclude: instance_name, disk
1215 .. opcode_result:: OP_INSTANCE_GROW_DISK
1218 ``/2/instances/[instance_name]/prepare-export``
1219 +++++++++++++++++++++++++++++++++++++++++++++++++
1221 Prepares an export of an instance.
1223 It supports the following commands: ``PUT``.
1228 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
1232 .. opcode_result:: OP_BACKUP_PREPARE
1235 ``/2/instances/[instance_name]/export``
1236 +++++++++++++++++++++++++++++++++++++++++++++++++
1238 Exports an instance.
1240 It supports the following commands: ``PUT``.
1249 .. opcode_params:: OP_BACKUP_EXPORT
1250 :exclude: instance_name
1251 :alias: target_node=destination
1255 .. opcode_result:: OP_BACKUP_EXPORT
1258 ``/2/instances/[instance_name]/migrate``
1259 ++++++++++++++++++++++++++++++++++++++++
1261 Migrates an instance.
1263 Supports the following commands: ``PUT``.
1272 .. opcode_params:: OP_INSTANCE_MIGRATE
1273 :exclude: instance_name, live
1277 .. opcode_result:: OP_INSTANCE_MIGRATE
1280 ``/2/instances/[instance_name]/failover``
1281 +++++++++++++++++++++++++++++++++++++++++
1283 Does a failover of an instance.
1285 Supports the following commands: ``PUT``.
1294 .. opcode_params:: OP_INSTANCE_FAILOVER
1295 :exclude: instance_name
1299 .. opcode_result:: OP_INSTANCE_FAILOVER
1302 ``/2/instances/[instance_name]/rename``
1303 ++++++++++++++++++++++++++++++++++++++++
1305 Renames an instance.
1307 Supports the following commands: ``PUT``.
1316 .. opcode_params:: OP_INSTANCE_RENAME
1317 :exclude: instance_name
1321 .. opcode_result:: OP_INSTANCE_RENAME
1324 ``/2/instances/[instance_name]/modify``
1325 ++++++++++++++++++++++++++++++++++++++++
1327 Modifies an instance.
1329 Supports the following commands: ``PUT``.
1338 .. opcode_params:: OP_INSTANCE_SET_PARAMS
1339 :exclude: instance_name
1343 .. opcode_result:: OP_INSTANCE_SET_PARAMS
1346 ``/2/instances/[instance_name]/console``
1347 ++++++++++++++++++++++++++++++++++++++++
1349 Request information for connecting to instance's console.
1353 not (hasattr(rlib2.R_2_instances_name_console, "PUT") or
1354 hasattr(rlib2.R_2_instances_name_console, "POST") or
1355 hasattr(rlib2.R_2_instances_name_console, "DELETE"))
1357 Supports the following commands: ``GET``. Requires authentication with
1358 one of the following options:
1359 :pyeval:`utils.CommaJoin(rlib2.R_2_instances_name_console.GET_ACCESS)`.
1364 Returns a dictionary containing information about the instance's
1365 console. Contained keys:
1369 constants.CONS_ALL == frozenset([
1370 constants.CONS_MESSAGE,
1373 constants.CONS_SPICE,
1379 Console type, one of :pyeval:`constants.CONS_SSH`,
1380 :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
1381 or :pyeval:`constants.CONS_MESSAGE`
1383 Message to display (:pyeval:`constants.CONS_MESSAGE` type only)
1385 Host to connect to (:pyeval:`constants.CONS_SSH`,
1386 :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
1388 TCP port to connect to (:pyeval:`constants.CONS_VNC` or
1389 :pyeval:`constants.CONS_SPICE` only)
1391 Username to use (:pyeval:`constants.CONS_SSH` only)
1393 Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
1395 VNC display number (:pyeval:`constants.CONS_VNC` only)
1398 ``/2/instances/[instance_name]/tags``
1399 +++++++++++++++++++++++++++++++++++++
1401 Manages per-instance tags.
1403 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1408 Returns a list of tags.
1412 ["tag1", "tag2", "tag3"]
1419 The request as a list of strings should be ``PUT`` to this URI. The
1420 result will be a job id.
1422 It supports the ``dry-run`` argument.
1430 In order to delete a set of tags, the DELETE request should be addressed
1433 /tags?tag=[tag]&tag=[tag]
1435 It supports the ``dry-run`` argument.
1441 The ``/2/jobs`` resource.
1443 It supports the following commands: ``GET``.
1448 Returns a dictionary of jobs.
1450 Returns: a dictionary with jobs id and uri.
1452 If the optional bool *bulk* argument is provided and set to a true value
1453 (i.e. ``?bulk=1``), the output contains detailed information about jobs
1456 Returned fields for bulk requests (unlike other bulk requests, these
1457 fields are not the same as for per-job requests):
1458 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`.
1460 ``/2/jobs/[job_id]``
1461 ++++++++++++++++++++
1466 It supports the following commands: ``GET``, ``DELETE``.
1471 Returns a dictionary with job parameters, containing the fields
1472 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.
1474 The result includes:
1476 - id: job ID as a number
1477 - status: current job status as a string
1478 - ops: involved OpCodes as a list of dictionaries for each opcodes in
1480 - opstatus: OpCodes status as a list
1481 - opresult: OpCodes results as a list
1483 For a successful opcode, the ``opresult`` field corresponding to it will
1484 contain the raw result from its :term:`LogicalUnit`. In case an opcode
1485 has failed, its element in the opresult list will be a list of two
1488 - first element the error type (the Ganeti internal error name)
1489 - second element a list of either one or two elements:
1491 - the first element is the textual error description
1492 - the second element, if any, will hold an error classification
1494 The error classification is most useful for the ``OpPrereqError``
1495 error type - these errors happen before the OpCode has started
1496 executing, so it's possible to retry the OpCode without side
1497 effects. But whether it make sense to retry depends on the error
1502 errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
1503 errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
1504 errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
1505 errors.ECODE_ENVIRON, errors.ECODE_TEMP_NORES])
1507 :pyeval:`errors.ECODE_RESOLVER`
1508 Resolver errors. This usually means that a name doesn't exist in DNS,
1509 so if it's a case of slow DNS propagation the operation can be retried
1512 :pyeval:`errors.ECODE_NORES`
1513 Not enough resources (iallocator failure, disk space, memory,
1514 etc.). If the resources on the cluster increase, the operation might
1517 :pyeval:`errors.ECODE_TEMP_NORES`
1518 Simliar to :pyeval:`errors.ECODE_NORES`, but indicating the operation
1519 should be attempted again after some time.
1521 :pyeval:`errors.ECODE_INVAL`
1522 Wrong arguments (at syntax level). The operation will not ever be
1523 accepted unless the arguments change.
1525 :pyeval:`errors.ECODE_STATE`
1526 Wrong entity state. For example, live migration has been requested for
1527 a down instance, or instance creation on an offline node. The
1528 operation can be retried once the resource has changed state.
1530 :pyeval:`errors.ECODE_NOENT`
1531 Entity not found. For example, information has been requested for an
1534 :pyeval:`errors.ECODE_EXISTS`
1535 Entity already exists. For example, instance creation has been
1536 requested for an already-existing instance.
1538 :pyeval:`errors.ECODE_NOTUNIQUE`
1539 Resource not unique (e.g. MAC or IP duplication).
1541 :pyeval:`errors.ECODE_FAULT`
1542 Internal cluster error. For example, a node is unreachable but not set
1543 offline, or the ganeti node daemons are not working, etc. A
1544 ``gnt-cluster verify`` should be run.
1546 :pyeval:`errors.ECODE_ENVIRON`
1547 Environment error (e.g. node disk error). A ``gnt-cluster verify``
1550 Note that in the above list, by entity we refer to a node or instance,
1551 while by a resource we refer to an instance's disk, or NIC, etc.
1557 Cancel a not-yet-started job.
1560 ``/2/jobs/[job_id]/wait``
1561 +++++++++++++++++++++++++
1566 Waits for changes on a job. Takes the following body parameters in a
1570 The job fields on which to watch for changes
1572 ``previous_job_info``
1573 Previously received field values or None if not yet available
1575 ``previous_log_serial``
1576 Highest log serial number received so far or None if not yet
1579 Returns None if no changes have been detected and a dict with two keys,
1580 ``job_info`` and ``log_entries`` otherwise.
1588 It supports the following commands: ``GET``.
1593 Returns a list of all nodes.
1599 "id": "node1.example.com",
1600 "uri": "\/nodes\/node1.example.com"
1603 "id": "node2.example.com",
1604 "uri": "\/nodes\/node2.example.com"
1608 If the optional bool *bulk* argument is provided and set to a true value
1609 (i.e ``?bulk=1``), the output contains detailed information about nodes
1612 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1621 "name": "www.example.com",
1633 ``/2/nodes/[node_name]``
1634 +++++++++++++++++++++++++++++++++
1636 Returns information about a node.
1638 It supports the following commands: ``GET``.
1640 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1642 ``/2/nodes/[node_name]/powercycle``
1643 +++++++++++++++++++++++++++++++++++
1645 Powercycles a node. Supports the following commands: ``POST``.
1654 .. opcode_result:: OP_NODE_POWERCYCLE
1657 ``/2/nodes/[node_name]/evacuate``
1658 +++++++++++++++++++++++++++++++++
1660 Evacuates instances off a node.
1662 It supports the following commands: ``POST``.
1667 Returns a job ID. The result of the job will contain the IDs of the
1668 individual jobs submitted to evacuate the node.
1672 .. opcode_params:: OP_NODE_EVACUATE
1675 Up to and including Ganeti 2.4 query arguments were used. Those are no
1676 longer supported. The new request can be detected by the presence of the
1677 :pyeval:`rlib2._NODE_EVAC_RES1` feature string.
1681 .. opcode_result:: OP_NODE_EVACUATE
1684 ``/2/nodes/[node_name]/migrate``
1685 +++++++++++++++++++++++++++++++++
1687 Migrates all primary instances from a node.
1689 It supports the following commands: ``POST``.
1694 If no mode is explicitly specified, each instances' hypervisor default
1695 migration mode will be used. Body parameters:
1697 .. opcode_params:: OP_NODE_MIGRATE
1700 The query arguments used up to and including Ganeti 2.4 are deprecated
1701 and should no longer be used. The new request format can be detected by
1702 the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
1706 .. opcode_result:: OP_NODE_MIGRATE
1709 ``/2/nodes/[node_name]/role``
1710 +++++++++++++++++++++++++++++
1714 It supports the following commands: ``GET``, ``PUT``.
1716 The role is always one of the following:
1723 Note that the 'master' role is a special, and currently it can't be
1724 modified via RAPI, only via the command line (``gnt-cluster
1730 Returns the current node role.
1739 Change the node role.
1741 The request is a string which should be PUT to this URI. The result will
1744 It supports the bool ``force`` argument.
1748 .. opcode_result:: OP_NODE_SET_PARAMS
1751 ``/2/nodes/[node_name]/modify``
1752 +++++++++++++++++++++++++++++++
1754 Modifies the parameters of a node. Supports the following commands:
1764 .. opcode_params:: OP_NODE_SET_PARAMS
1769 .. opcode_result:: OP_NODE_SET_PARAMS
1772 ``/2/nodes/[node_name]/storage``
1773 ++++++++++++++++++++++++++++++++
1775 Manages storage units on the node.
1782 constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
1783 constants.ST_LVM_PV,
1784 constants.ST_LVM_VG])
1786 Requests a list of storage units on a node. Requires the parameters
1787 ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1788 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
1789 ``output_fields``. The result will be a job id, using which the result
1792 ``/2/nodes/[node_name]/storage/modify``
1793 +++++++++++++++++++++++++++++++++++++++
1795 Modifies storage units on the node.
1800 Modifies parameters of storage units on the node. Requires the
1801 parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
1802 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
1803 and ``name`` (name of the storage unit). Parameters can be passed
1804 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
1805 is supported. The result will be a job id.
1809 .. opcode_result:: OP_NODE_MODIFY_STORAGE
1812 ``/2/nodes/[node_name]/storage/repair``
1813 +++++++++++++++++++++++++++++++++++++++
1815 Repairs a storage unit on the node.
1822 constants.VALID_STORAGE_OPERATIONS == {
1823 constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
1826 Repairs a storage unit on the node. Requires the parameters
1827 ``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
1828 repaired) and ``name`` (name of the storage unit). The result will be a
1833 .. opcode_result:: OP_REPAIR_NODE_STORAGE
1836 ``/2/nodes/[node_name]/tags``
1837 +++++++++++++++++++++++++++++
1839 Manages per-node tags.
1841 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1846 Returns a list of tags.
1850 ["tag1", "tag2", "tag3"]
1857 The request as a list of strings should be PUT to this URI. The result
1860 It supports the ``dry-run`` argument.
1867 In order to delete a set of tags, the DELETE request should be addressed
1870 /tags?tag=[tag]&tag=[tag]
1872 It supports the ``dry-run`` argument.
1875 ``/2/query/[resource]``
1876 +++++++++++++++++++++++
1878 Requests resource information. Available fields can be found in man
1879 pages and using ``/2/query/[resource]/fields``. The resource is one of
1880 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
1881 design document <design-query2>` for more details.
1885 (rlib2.R_2_query.GET_ACCESS == rlib2.R_2_query.PUT_ACCESS and
1886 not (hasattr(rlib2.R_2_query, "POST") or
1887 hasattr(rlib2.R_2_query, "DELETE")))
1889 Supports the following commands: ``GET``, ``PUT``. Requires
1890 authentication with one of the following options:
1891 :pyeval:`utils.CommaJoin(rlib2.R_2_query.GET_ACCESS)`.
1896 Returns list of included fields and actual data. Takes a query parameter
1897 named "fields", containing a comma-separated list of field names. Does
1898 not support filtering.
1903 Returns list of included fields and actual data. The list of requested
1904 fields can either be given as the query parameter "fields" or as a body
1905 parameter with the same name. The optional body parameter "filter" can
1906 be given and must be either ``null`` or a list containing filter
1910 ``/2/query/[resource]/fields``
1911 ++++++++++++++++++++++++++++++
1913 Request list of available fields for a resource. The resource is one of
1914 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
1915 :doc:`query2 design document <design-query2>` for more details.
1917 Supports the following commands: ``GET``.
1922 Returns a list of field descriptions for available fields. Takes an
1923 optional query parameter named "fields", containing a comma-separated
1924 list of field names.
1932 It supports the following commands: ``GET``.
1937 Return a list of all OSes.
1939 Can return error 500 in case of a problem. Since this is a costly
1940 operation for Ganeti 2.0, it is not recommended to execute it too often.
1949 Manages cluster tags.
1951 It supports the following commands: ``GET``, ``PUT``, ``DELETE``.
1956 Returns the cluster tags.
1960 ["tag1", "tag2", "tag3"]
1967 The request as a list of strings should be PUT to this URI. The result
1970 It supports the ``dry-run`` argument.
1978 In order to delete a set of tags, the DELETE request should be addressed
1981 /tags?tag=[tag]&tag=[tag]
1983 It supports the ``dry-run`` argument.
1989 The version resource.
1991 This resource should be used to determine the remote API version and to
1992 adapt clients accordingly.
1994 It supports the following commands: ``GET``.
1999 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
2002 .. vim: set textwidth=72 :