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
34 Passwords can either be written in clear text or as a hash. Clear text
35 passwords may not start with an opening brace (``{``) or they must be
36 prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash
37 of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n
38 'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix
39 it with ``{ha1}``. Using the scheme prefix for all passwords is
40 recommended. Scheme prefixes are case insensitive.
42 Options control a user's access permissions. The section
43 :ref:`rapi-access-permissions` lists the permissions required for each
44 resource. If the ``--require-authentication`` command line option is
45 given to the ``ganeti-rapi`` daemon, all requests require
46 authentication. Available options:
50 rapi.RAPI_ACCESS_ALL == set([
51 rapi.RAPI_ACCESS_WRITE,
52 rapi.RAPI_ACCESS_READ,
57 rlib2.R_2_nodes_name_storage.GET_ACCESS == [rapi.RAPI_ACCESS_WRITE]
61 rlib2.R_2_jobs_id_wait.GET_ACCESS == [rapi.RAPI_ACCESS_WRITE]
63 :pyeval:`rapi.RAPI_ACCESS_WRITE`
64 Enables the user to execute operations modifying the cluster. Implies
65 :pyeval:`rapi.RAPI_ACCESS_READ` access. Resources blocking other
66 operations for read-only access, such as
67 :ref:`/2/nodes/[node_name]/storage <rapi-res-nodes-node_name-storage+get>`
68 or blocking server-side processes, such as
69 :ref:`/2/jobs/[job_id]/wait <rapi-res-jobs-job_id-wait+get>`, use
70 :pyeval:`rapi.RAPI_ACCESS_WRITE` to control access to their
71 :pyeval:`http.HTTP_GET` method.
72 :pyeval:`rapi.RAPI_ACCESS_READ`
73 Allow access to operations querying for information.
77 # Give Jack and Fred read-only access
79 fred {cleartext}foo555
81 # Give write access to an imaginary instance creation script
82 autocreator xyz789 write
84 # Hashed password for Jessica
85 jessica {HA1}7046452df2cbb530877058712cf17bd4 write
87 # Monitoring can query for values
88 monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read
90 # A user who can read and write (the former is implied by granting
92 superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read,write
94 When using the RAPI, username and password can be sent to the server
95 by using the standard HTTP basic access authentication. This means that
96 for accessing the protected URL ``https://cluster.example.com/resource``,
97 the address ``https://username:password@cluster.example.com/resource`` should
99 Alternatively, the appropriate parameter of your HTTP client
100 (such as ``-u`` for ``curl``) can be used.
102 .. [#pwhash] Using the MD5 hash of username, realm and password is
103 described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
104 and 3.3. The reason for using it over another algorithm is forward
105 compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
106 authentication in the future, the same hash could be used.
107 In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
108 API``, can only be changed by modifying the source code.
114 The protocol used is JSON_ over HTTP designed after the REST_ principle.
115 HTTP Basic authentication as per :rfc:`2617` is supported.
117 .. _JSON: http://www.json.org/
118 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
120 HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
121 header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
122 (HTTP/1.1), section 7.2.1).
125 A note on JSON as used by RAPI
126 ++++++++++++++++++++++++++++++
128 JSON_ as used by Ganeti RAPI does not conform to the specification in
129 :rfc:`4627`. Section 2 defines a JSON text to be either an object
130 (``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
131 of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
132 some requests or responses. Changing this now would likely break
133 existing clients and cause a lot of trouble.
137 Unlike Python's `JSON encoder and decoder
138 <http://docs.python.org/library/json.html>`_, other programming
139 languages or libraries may only provide a strict implementation, not
140 allowing plain values. For those, responses can usually be wrapped in an
141 array whose first element is then used, e.g. the response ``"1234"``
142 becomes ``["1234"]``. This works equally well for more complex values.
147 # Insert code to get response here
148 response = "\"1234\""
150 decoded = JSON.parse("[#{response}]").first
152 Short of modifying the encoder to allow encoding to a less strict
153 format, requests will have to be formatted by hand. Newer RAPI requests
154 already use a dictionary as their input data and shouldn't cause any
161 According to :rfc:`2616` the main difference between PUT and POST is
162 that POST can create new resources but PUT can only create the resource
163 the URI was pointing to on the PUT request.
165 Unfortunately, due to historic reasons, the Ganeti RAPI library is not
166 consistent with this usage, so just use the methods as documented below
169 For more details have a look in the source code at
170 ``lib/rapi/rlib2.py``.
173 Generic parameter types
174 -----------------------
176 A few generic refered parameter types and the values they allow.
181 A boolean option will accept ``1`` or ``0`` as numbers but not
182 i.e. ``True`` or ``False``.
187 A few parameter mean the same thing across all resources which implement
193 Bulk-mode means that for the resources which usually return just a list
194 of child resources (e.g. ``/2/instances`` which returns just instance
195 names), the output will instead contain detailed data for all these
196 subresources. This is more efficient than query-ing the sub-resources
202 The boolean *dry-run* argument, if provided and set, signals to Ganeti
203 that the job should not be executed, only the pre-execution checks will
206 This is useful in trying to determine (without guarantees though, as in
207 the meantime the cluster state could have changed) if the operation is
208 likely to succeed or at least start executing.
213 Force operation to continue even if it will cause the cluster to become
214 inconsistent (e.g. because there are not enough master candidates).
219 Some parameters are not straight forward, so we describe them in details
227 The instance policy specification is a dict with the following fields:
231 constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MINMAX,
232 constants.ISPECS_STD,
233 constants.IPOLICY_DTS,
234 constants.IPOLICY_VCPU_RATIO,
235 constants.IPOLICY_SPINDLE_RATIO])
240 (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
241 set([constants.ISPEC_MEM_SIZE,
242 constants.ISPEC_DISK_SIZE,
243 constants.ISPEC_DISK_COUNT,
244 constants.ISPEC_CPU_COUNT,
245 constants.ISPEC_NIC_COUNT,
246 constants.ISPEC_SPINDLE_USE]))
248 .. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
249 .. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
250 .. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
253 :pyeval:`constants.ISPECS_MINMAX`
254 A list of dictionaries, each with the following two fields:
256 |ispec-min|, |ispec-max|
257 A sub- `dict` with the following fields, which sets the limit of the
260 :pyeval:`constants.ISPEC_MEM_SIZE`
261 The size in MiB of the memory used
262 :pyeval:`constants.ISPEC_DISK_SIZE`
263 The size in MiB of the disk used
264 :pyeval:`constants.ISPEC_DISK_COUNT`
265 The numbers of disks used
266 :pyeval:`constants.ISPEC_CPU_COUNT`
267 The numbers of cpus used
268 :pyeval:`constants.ISPEC_NIC_COUNT`
269 The numbers of nics used
270 :pyeval:`constants.ISPEC_SPINDLE_USE`
271 The numbers of virtual disk spindles used by this instance. They
272 are not real in the sense of actual HDD spindles, but useful for
273 accounting the spindle usage on the residing node
275 A sub- `dict` with the same fields as |ispec-min| and |ispec-max| above,
276 which sets the standard values of the instances.
277 :pyeval:`constants.IPOLICY_DTS`
278 A `list` of disk templates allowed for instances using this policy
279 :pyeval:`constants.IPOLICY_VCPU_RATIO`
280 Maximum ratio of virtual to physical CPUs (`float`)
281 :pyeval:`constants.IPOLICY_SPINDLE_RATIO`
282 Maximum ratio of instances to their node's ``spindle_count`` (`float`)
287 You can access the API using your favorite programming language as long
288 as it supports network connections.
293 Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.
298 .. highlight:: shell-example
302 $ wget -q -O - https://%CLUSTERNAME%:5080/2/info
306 $ curl https://%CLUSTERNAME%:5080/2/info
308 Note: with ``curl``, the request method (GET, POST, PUT) can be specified
309 using the ``-X`` command line option, and the username/password can be
310 specified with the ``-u`` option. In case of POST requests with a body, the
311 Content-Type can be set to JSON (as per the Protocol_ section) using the
312 parameter ``-H "Content-Type: application/json"``.
317 .. highlight:: python
322 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
329 .. warning:: While it's possible to use JavaScript, it poses several
330 potential problems, including browser blocking request due to
331 non-standard ports or different domain names. Fetching the data on
332 the webserver is easier.
334 .. highlight:: javascript
338 var url = 'https://CLUSTERNAME:5080/2/info';
340 var xmlreq = new XMLHttpRequest();
341 xmlreq.onreadystatechange = function () {
342 if (xmlreq.readyState != 4) return;
343 if (xmlreq.status == 200) {
344 info = eval("(" + xmlreq.responseText + ")");
347 alert('Error fetching cluster info');
351 xmlreq.open('GET', url, true);
357 .. highlight:: javascript
362 The root resource. Has no function, but for legacy reasons the ``GET``
368 Has no function, but for legacy reasons the ``GET`` method is supported.
375 Cluster information resource.
377 .. rapi_resource_details:: /2/info
380 .. _rapi-res-info+get:
385 Returns cluster information.
390 "config_version": 2000000,
392 "software_version": "2.0.0~beta2",
393 "os_api_version": 10,
395 "candidate_pool_size": 10,
396 "enabled_hypervisors": [
402 "default_hypervisor": "fake",
403 "master": "node1.example.com",
408 "protocol_version": 20,
411 "auto_balance": true,
420 .. _rapi-res-redistribute-config:
422 ``/2/redistribute-config``
423 ++++++++++++++++++++++++++
425 Redistribute configuration to all nodes.
427 .. rapi_resource_details:: /2/redistribute-config
430 .. _rapi-res-redistribute-config+put:
435 Redistribute configuration to all nodes. The result will be a job id.
439 .. opcode_result:: OP_CLUSTER_REDIST_CONF
442 .. _rapi-res-features:
447 .. rapi_resource_details:: /2/features
450 .. _rapi-res-features+get:
455 Returns a list of features supported by the RAPI server. Available
460 rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
461 rlib2._INST_REINSTALL_REQV1,
462 rlib2._NODE_MIGRATE_REQV1,
463 rlib2._NODE_EVAC_RES1])
465 :pyeval:`rlib2._INST_CREATE_REQV1`
466 Instance creation request data version 1 supported
467 :pyeval:`rlib2._INST_REINSTALL_REQV1`
468 Instance reinstall supports body parameters
469 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
470 Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
471 request body parameters
472 :pyeval:`rlib2._NODE_EVAC_RES1`
473 Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
474 a new-style result (see resource description)
480 ++++++++++++++++++++++++++++++++++++++++
482 Modifies cluster parameters.
484 .. rapi_resource_details:: /2/modify
487 .. _rapi-res-modify+put:
496 .. opcode_params:: OP_CLUSTER_SET_PARAMS
500 .. opcode_result:: OP_CLUSTER_SET_PARAMS
510 .. rapi_resource_details:: /2/groups
513 .. _rapi-res-groups+get:
518 Returns a list of all existing node groups.
525 "uri": "\/2\/groups\/group1"
529 "uri": "\/2\/groups\/group2"
533 If the optional bool *bulk* argument is provided and set to a true value
534 (i.e ``?bulk=1``), the output contains detailed information about node
537 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
549 "uuid": "0d7d407c-262e-49af-881a-6a430034bf43",
558 "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c",
565 .. _rapi-res-groups+post:
570 Creates a node group.
572 If the optional bool *dry-run* argument is provided, the job will not be
573 actually executed, only the pre-execution checks will be done.
575 Returns: a job ID that can be used later for polling.
579 .. opcode_params:: OP_GROUP_ADD
581 Earlier versions used a parameter named ``name`` which, while still
582 supported, has been renamed to ``group_name``.
586 .. opcode_result:: OP_GROUP_ADD
589 .. _rapi-res-groups-group_name:
591 ``/2/groups/[group_name]``
592 ++++++++++++++++++++++++++
594 Returns information about a node group.
596 .. rapi_resource_details:: /2/groups/[group_name]
599 .. _rapi-res-groups-group_name+get:
604 Returns information about a node group, similar to the bulk output from
607 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
609 .. _rapi-res-groups-group_name+delete:
614 Deletes a node group.
616 It supports the ``dry-run`` argument.
620 .. opcode_result:: OP_GROUP_REMOVE
623 .. _rapi-res-groups-group_name-modify:
625 ``/2/groups/[group_name]/modify``
626 +++++++++++++++++++++++++++++++++
628 Modifies the parameters of a node group.
630 .. rapi_resource_details:: /2/groups/[group_name]/modify
633 .. _rapi-res-groups-group_name-modify+put:
642 .. opcode_params:: OP_GROUP_SET_PARAMS
647 .. opcode_result:: OP_GROUP_SET_PARAMS
650 .. _rapi-res-groups-group_name-rename:
652 ``/2/groups/[group_name]/rename``
653 +++++++++++++++++++++++++++++++++
655 Renames a node group.
657 .. rapi_resource_details:: /2/groups/[group_name]/rename
660 .. _rapi-res-groups-group_name-rename+put:
669 .. opcode_params:: OP_GROUP_RENAME
674 .. opcode_result:: OP_GROUP_RENAME
677 .. _rapi-res-groups-group_name-assign-nodes:
679 ``/2/groups/[group_name]/assign-nodes``
680 +++++++++++++++++++++++++++++++++++++++
682 Assigns nodes to a group.
684 .. rapi_resource_details:: /2/groups/[group_name]/assign-nodes
686 .. _rapi-res-groups-group_name-assign-nodes+put:
691 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
695 .. opcode_params:: OP_GROUP_ASSIGN_NODES
696 :exclude: group_name, force, dry_run
700 .. opcode_result:: OP_GROUP_ASSIGN_NODES
702 .. _rapi-res-groups-group_name-tags:
704 ``/2/groups/[group_name]/tags``
705 +++++++++++++++++++++++++++++++
707 Manages per-nodegroup tags.
709 .. rapi_resource_details:: /2/groups/[group_name]/tags
712 .. _rapi-res-groups-group_name-tags+get:
717 Returns a list of tags.
721 ["tag1", "tag2", "tag3"]
723 .. _rapi-res-groups-group_name-tags+put:
730 The request as a list of strings should be ``PUT`` to this URI. The
731 result will be a job id.
733 It supports the ``dry-run`` argument.
736 .. _rapi-res-groups-group_name-tags+delete:
743 In order to delete a set of tags, the DELETE request should be addressed
746 /tags?tag=[tag]&tag=[tag]
748 It supports the ``dry-run`` argument.
751 .. _rapi-res-networks:
756 The networks resource.
758 .. rapi_resource_details:: /2/networks
761 .. _rapi-res-networks+get:
766 Returns a list of all existing networks.
773 "uri": "\/2\/networks\/network1"
777 "uri": "\/2\/networks\/network2"
781 If the optional bool *bulk* argument is provided and set to a true value
782 (i.e ``?bulk=1``), the output contains detailed information about networks
785 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
791 'external_reservations': '10.0.0.0, 10.0.0.1, 10.0.0.15',
793 'gateway': '10.0.0.1',
795 'group_list': ['default(bridged, prv0)'],
798 'map': 'XX.............X',
800 'network': '10.0.0.0/28',
810 .. _rapi-res-networks+post:
817 If the optional bool *dry-run* argument is provided, the job will not be
818 actually executed, only the pre-execution checks will be done.
820 Returns: a job ID that can be used later for polling.
824 .. opcode_params:: OP_NETWORK_ADD
828 .. opcode_result:: OP_NETWORK_ADD
831 .. _rapi-res-networks-network_name:
833 ``/2/networks/[network_name]``
834 ++++++++++++++++++++++++++++++
836 Returns information about a network.
838 .. rapi_resource_details:: /2/networks/[network_name]
841 .. _rapi-res-networks-network_name+get:
846 Returns information about a network, similar to the bulk output from
849 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
852 .. _rapi-res-networks-network_name+delete:
859 It supports the ``dry-run`` argument.
863 .. opcode_result:: OP_NETWORK_REMOVE
866 .. _rapi-res-networks-network_name-modify:
868 ``/2/networks/[network_name]/modify``
869 +++++++++++++++++++++++++++++++++++++
871 Modifies the parameters of a network.
873 .. rapi_resource_details:: /2/networks/[network_name]/modify
876 .. _rapi-res-networks-network_name-modify+put:
885 .. opcode_params:: OP_NETWORK_SET_PARAMS
889 .. opcode_result:: OP_NETWORK_SET_PARAMS
892 .. _rapi-res-networks-network_name-connect:
894 ``/2/networks/[network_name]/connect``
895 ++++++++++++++++++++++++++++++++++++++
897 Connects a network to a nodegroup.
899 .. rapi_resource_details:: /2/networks/[network_name]/connect
902 .. _rapi-res-networks-network_name-connect+put:
907 Returns a job ID. It supports the ``dry-run`` arguments.
911 .. opcode_params:: OP_NETWORK_CONNECT
915 .. opcode_result:: OP_NETWORK_CONNECT
918 .. _rapi-res-networks-network_name-disconnect:
920 ``/2/networks/[network_name]/disconnect``
921 +++++++++++++++++++++++++++++++++++++++++
923 Disonnects a network from a nodegroup.
925 .. rapi_resource_details:: /2/networks/[network_name]/disconnect
928 .. _rapi-res-networks-network_name-disconnect+put:
933 Returns a job ID. It supports the ``dry-run`` arguments.
937 .. opcode_params:: OP_NETWORK_DISCONNECT
941 .. opcode_result:: OP_NETWORK_DISCONNECT
944 .. _rapi-res-networks-network_name-tags:
946 ``/2/networks/[network_name]/tags``
947 +++++++++++++++++++++++++++++++++++
949 Manages per-network tags.
951 .. rapi_resource_details:: /2/networks/[network_name]/tags
954 .. _rapi-res-networks-network_name-tags+get:
959 Returns a list of tags.
963 ["tag1", "tag2", "tag3"]
966 .. _rapi-res-networks-network_name-tags+put:
973 The request as a list of strings should be ``PUT`` to this URI. The
974 result will be a job id.
976 It supports the ``dry-run`` argument.
979 .. _rapi-res-networks-network_name-tags+delete:
986 In order to delete a set of tags, the DELETE request should be addressed
989 /tags?tag=[tag]&tag=[tag]
991 It supports the ``dry-run`` argument.
994 .. _rapi-res-instances-multi-alloc:
996 ``/2/instances-multi-alloc``
997 ++++++++++++++++++++++++++++
999 Tries to allocate multiple instances.
1001 .. rapi_resource_details:: /2/instances-multi-alloc
1004 .. _rapi-res-instances-multi-alloc+post:
1011 .. opcode_params:: OP_INSTANCE_MULTI_ALLOC
1015 .. opcode_result:: OP_INSTANCE_MULTI_ALLOC
1018 .. _rapi-res-instances:
1023 The instances resource.
1025 .. rapi_resource_details:: /2/instances
1028 .. _rapi-res-instances+get:
1033 Returns a list of all available instances.
1039 "name": "web.example.com",
1040 "uri": "\/instances\/web.example.com"
1043 "name": "mail.example.com",
1044 "uri": "\/instances\/mail.example.com"
1048 If the optional bool *bulk* argument is provided and set to a true value
1049 (i.e ``?bulk=1``), the output contains detailed information about
1050 instances as a list.
1052 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
1058 "status": "running",
1059 "disk_usage": 20480,
1063 "name": "web.example.com",
1064 "tags": ["tag1", "tag2"],
1072 "pnode": "node1.example.com",
1073 "nic.macs": ["01:23:45:67:89:01"],
1074 "snodes": ["node2.example.com"],
1075 "disk_template": "drbd",
1076 "admin_state": true,
1077 "os": "debian-etch",
1085 .. _rapi-res-instances+post:
1090 Creates an instance.
1092 If the optional bool *dry-run* argument is provided, the job will not be
1093 actually executed, only the pre-execution checks will be done. Query-ing
1094 the job result will return, in both dry-run and normal case, the list of
1095 nodes selected for the instance.
1097 Returns: a job ID that can be used later for polling.
1101 ``__version__`` (int, required)
1102 Must be ``1`` (older Ganeti versions used a different format for
1103 instance creation requests, version ``0``, but that format is no
1106 .. opcode_params:: OP_INSTANCE_CREATE
1108 Earlier versions used parameters named ``name`` and ``os``. These have
1109 been replaced by ``instance_name`` and ``os_type`` to match the
1110 underlying opcode. The old names can still be used.
1114 .. opcode_result:: OP_INSTANCE_CREATE
1117 .. _rapi-res-instances-instance_name:
1119 ``/2/instances/[instance_name]``
1120 ++++++++++++++++++++++++++++++++
1122 Instance-specific resource.
1124 .. rapi_resource_details:: /2/instances/[instance_name]
1127 .. _rapi-res-instances-instance_name+get:
1132 Returns information about an instance, similar to the bulk output from
1135 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
1138 .. _rapi-res-instances-instance_name+delete:
1143 Deletes an instance.
1145 It supports the ``dry-run`` argument.
1149 .. opcode_result:: OP_INSTANCE_REMOVE
1152 .. _rapi-res-instances-instance_name-info:
1154 ``/2/instances/[instance_name]/info``
1155 +++++++++++++++++++++++++++++++++++++++
1157 .. rapi_resource_details:: /2/instances/[instance_name]/info
1160 .. _rapi-res-instances-instance_name-info+get:
1165 Requests detailed information about the instance. An optional parameter,
1166 ``static`` (bool), can be set to return only static information from the
1167 configuration without querying the instance's nodes. The result will be
1172 .. opcode_result:: OP_INSTANCE_QUERY_DATA
1175 .. _rapi-res-instances-instance_name-reboot:
1177 ``/2/instances/[instance_name]/reboot``
1178 +++++++++++++++++++++++++++++++++++++++
1180 Reboots URI for an instance.
1182 .. rapi_resource_details:: /2/instances/[instance_name]/reboot
1185 .. _rapi-res-instances-instance_name-reboot+post:
1190 Reboots the instance.
1192 The URI takes optional ``type=soft|hard|full`` and
1193 ``ignore_secondaries=0|1`` parameters.
1195 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
1196 without terminating the hypervisor. ``hard`` means full shutdown
1197 (including terminating the hypervisor process) and startup again.
1198 ``full`` is like ``hard`` but also recreates the configuration from
1199 ground up as if you would have done a ``gnt-instance shutdown`` and
1200 ``gnt-instance start`` on it.
1202 ``ignore_secondaries`` is a bool argument indicating if we start the
1203 instance even if secondary disks are failing.
1205 It supports the ``dry-run`` argument.
1209 .. opcode_result:: OP_INSTANCE_REBOOT
1212 .. _rapi-res-instances-instance_name-shutdown:
1214 ``/2/instances/[instance_name]/shutdown``
1215 +++++++++++++++++++++++++++++++++++++++++
1217 Instance shutdown URI.
1219 .. rapi_resource_details:: /2/instances/[instance_name]/shutdown
1222 .. _rapi-res-instances-instance_name-shutdown+put:
1227 Shutdowns an instance.
1229 It supports the ``dry-run`` argument.
1231 .. opcode_params:: OP_INSTANCE_SHUTDOWN
1232 :exclude: instance_name, dry_run
1236 .. opcode_result:: OP_INSTANCE_SHUTDOWN
1239 .. _rapi-res-instances-instance_name-startup:
1241 ``/2/instances/[instance_name]/startup``
1242 ++++++++++++++++++++++++++++++++++++++++
1244 Instance startup URI.
1246 .. rapi_resource_details:: /2/instances/[instance_name]/startup
1249 .. _rapi-res-instances-instance_name-startup+put:
1254 Startup an instance.
1256 The URI takes an optional ``force=1|0`` parameter to start the
1257 instance even if secondary disks are failing.
1259 It supports the ``dry-run`` argument.
1263 .. opcode_result:: OP_INSTANCE_STARTUP
1266 .. _rapi-res-instances-instance_name-reinstall:
1268 ``/2/instances/[instance_name]/reinstall``
1269 ++++++++++++++++++++++++++++++++++++++++++++++
1271 Installs the operating system again.
1273 .. rapi_resource_details:: /2/instances/[instance_name]/reinstall
1276 .. _rapi-res-instances-instance_name-reinstall+post:
1285 ``os`` (string, required)
1286 Instance operating system.
1287 ``start`` (bool, defaults to true)
1288 Whether to start instance after reinstallation.
1290 Dictionary with (temporary) OS parameters.
1292 For backwards compatbility, this resource also takes the query
1293 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
1294 clients should use the body parameters.
1297 .. _rapi-res-instances-instance_name-replace-disks:
1299 ``/2/instances/[instance_name]/replace-disks``
1300 ++++++++++++++++++++++++++++++++++++++++++++++
1302 Replaces disks on an instance.
1304 .. rapi_resource_details:: /2/instances/[instance_name]/replace-disks
1307 .. _rapi-res-instances-instance_name-replace-disks+post:
1316 .. opcode_params:: OP_INSTANCE_REPLACE_DISKS
1317 :exclude: instance_name
1319 Ganeti 2.4 and below used query parameters. Those are deprecated and
1320 should no longer be used.
1324 .. opcode_result:: OP_INSTANCE_REPLACE_DISKS
1327 .. _rapi-res-instances-instance_name-activate-disks:
1329 ``/2/instances/[instance_name]/activate-disks``
1330 +++++++++++++++++++++++++++++++++++++++++++++++
1332 Activate disks on an instance.
1334 .. rapi_resource_details:: /2/instances/[instance_name]/activate-disks
1337 .. _rapi-res-instances-instance_name-activate-disks+put:
1342 Takes the bool parameter ``ignore_size``. When set ignore the recorded
1343 size (useful for forcing activation when recorded size is wrong).
1347 .. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
1350 .. _rapi-res-instances-instance_name-deactivate-disks:
1352 ``/2/instances/[instance_name]/deactivate-disks``
1353 +++++++++++++++++++++++++++++++++++++++++++++++++
1355 Deactivate disks on an instance.
1357 .. rapi_resource_details:: /2/instances/[instance_name]/deactivate-disks
1360 .. _rapi-res-instances-instance_name-deactivate-disks+put:
1365 Takes no parameters.
1369 .. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS
1372 .. _rapi-res-instances-instance_name-recreate-disks:
1374 ``/2/instances/[instance_name]/recreate-disks``
1375 +++++++++++++++++++++++++++++++++++++++++++++++++
1377 Recreate disks of an instance.
1379 .. rapi_resource_details:: /2/instances/[instance_name]/recreate-disks
1382 .. _rapi-res-instances-instance_name-recreate-disks+post:
1391 .. opcode_params:: OP_INSTANCE_RECREATE_DISKS
1392 :exclude: instance_name
1396 .. opcode_result:: OP_INSTANCE_RECREATE_DISKS
1399 .. _rapi-res-instances-instance_name-disk-disk_index-grow:
1401 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
1402 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1404 Grows one disk of an instance.
1406 .. rapi_resource_details:: /2/instances/[instance_name]/disk/[disk_index]/grow
1409 .. _rapi-res-instances-instance_name-disk-disk_index-grow+post:
1418 .. opcode_params:: OP_INSTANCE_GROW_DISK
1419 :exclude: instance_name, disk
1423 .. opcode_result:: OP_INSTANCE_GROW_DISK
1426 .. _rapi-res-instances-instance_name-prepare-export:
1428 ``/2/instances/[instance_name]/prepare-export``
1429 +++++++++++++++++++++++++++++++++++++++++++++++++
1431 Prepares an export of an instance.
1433 .. rapi_resource_details:: /2/instances/[instance_name]/prepare-export
1436 .. _rapi-res-instances-instance_name-prepare-export+put:
1441 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
1445 .. opcode_result:: OP_BACKUP_PREPARE
1448 .. _rapi-res-instances-instance_name-export:
1450 ``/2/instances/[instance_name]/export``
1451 +++++++++++++++++++++++++++++++++++++++++++++++++
1453 Exports an instance.
1455 .. rapi_resource_details:: /2/instances/[instance_name]/export
1458 .. _rapi-res-instances-instance_name-export+put:
1467 .. opcode_params:: OP_BACKUP_EXPORT
1468 :exclude: instance_name
1469 :alias: target_node=destination
1473 .. opcode_result:: OP_BACKUP_EXPORT
1476 .. _rapi-res-instances-instance_name-migrate:
1478 ``/2/instances/[instance_name]/migrate``
1479 ++++++++++++++++++++++++++++++++++++++++
1481 Migrates an instance.
1483 .. rapi_resource_details:: /2/instances/[instance_name]/migrate
1486 .. _rapi-res-instances-instance_name-migrate+put:
1495 .. opcode_params:: OP_INSTANCE_MIGRATE
1496 :exclude: instance_name, live
1500 .. opcode_result:: OP_INSTANCE_MIGRATE
1503 .. _rapi-res-instances-instance_name-failover:
1505 ``/2/instances/[instance_name]/failover``
1506 +++++++++++++++++++++++++++++++++++++++++
1508 Does a failover of an instance.
1510 .. rapi_resource_details:: /2/instances/[instance_name]/failover
1513 .. _rapi-res-instances-instance_name-failover+put:
1522 .. opcode_params:: OP_INSTANCE_FAILOVER
1523 :exclude: instance_name
1527 .. opcode_result:: OP_INSTANCE_FAILOVER
1530 .. _rapi-res-instances-instance_name-rename:
1532 ``/2/instances/[instance_name]/rename``
1533 ++++++++++++++++++++++++++++++++++++++++
1535 Renames an instance.
1537 .. rapi_resource_details:: /2/instances/[instance_name]/rename
1540 .. _rapi-res-instances-instance_name-rename+put:
1549 .. opcode_params:: OP_INSTANCE_RENAME
1550 :exclude: instance_name
1554 .. opcode_result:: OP_INSTANCE_RENAME
1557 .. _rapi-res-instances-instance_name-modify:
1559 ``/2/instances/[instance_name]/modify``
1560 ++++++++++++++++++++++++++++++++++++++++
1562 Modifies an instance.
1564 .. rapi_resource_details:: /2/instances/[instance_name]/modify
1567 .. _rapi-res-instances-instance_name-modify+put:
1576 .. opcode_params:: OP_INSTANCE_SET_PARAMS
1577 :exclude: instance_name
1581 .. opcode_result:: OP_INSTANCE_SET_PARAMS
1584 .. _rapi-res-instances-instance_name-console:
1586 ``/2/instances/[instance_name]/console``
1587 ++++++++++++++++++++++++++++++++++++++++
1589 Request information for connecting to instance's console.
1591 .. rapi_resource_details:: /2/instances/[instance_name]/console
1594 .. _rapi-res-instances-instance_name-console+get:
1599 Returns a dictionary containing information about the instance's
1600 console. Contained keys:
1604 constants.CONS_ALL == frozenset([
1605 constants.CONS_MESSAGE,
1608 constants.CONS_SPICE,
1613 frozenset(objects.InstanceConsole.GetAllSlots()) == frozenset([
1628 Console type, one of :pyeval:`constants.CONS_SSH`,
1629 :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
1630 or :pyeval:`constants.CONS_MESSAGE`
1632 Message to display (:pyeval:`constants.CONS_MESSAGE` type only)
1634 Host to connect to (:pyeval:`constants.CONS_SSH`,
1635 :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
1637 TCP port to connect to (:pyeval:`constants.CONS_VNC` or
1638 :pyeval:`constants.CONS_SPICE` only)
1640 Username to use (:pyeval:`constants.CONS_SSH` only)
1642 Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
1644 VNC display number (:pyeval:`constants.CONS_VNC` only)
1647 .. _rapi-res-instances-instance_name-tags:
1649 ``/2/instances/[instance_name]/tags``
1650 +++++++++++++++++++++++++++++++++++++
1652 Manages per-instance tags.
1654 .. rapi_resource_details:: /2/instances/[instance_name]/tags
1657 .. _rapi-res-instances-instance_name-tags+get:
1662 Returns a list of tags.
1666 ["tag1", "tag2", "tag3"]
1669 .. _rapi-res-instances-instance_name-tags+put:
1676 The request as a list of strings should be ``PUT`` to this URI. The
1677 result will be a job id.
1679 It supports the ``dry-run`` argument.
1682 .. _rapi-res-instances-instance_name-tags+delete:
1689 In order to delete a set of tags, the DELETE request should be addressed
1692 /tags?tag=[tag]&tag=[tag]
1694 It supports the ``dry-run`` argument.
1702 The ``/2/jobs`` resource.
1704 .. rapi_resource_details:: /2/jobs
1707 .. _rapi-res-jobs+get:
1712 Returns a dictionary of jobs.
1714 Returns: a dictionary with jobs id and uri.
1716 If the optional bool *bulk* argument is provided and set to a true value
1717 (i.e. ``?bulk=1``), the output contains detailed information about jobs
1720 Returned fields for bulk requests (unlike other bulk requests, these
1721 fields are not the same as for per-job requests):
1722 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`.
1725 .. _rapi-res-jobs-job_id:
1727 ``/2/jobs/[job_id]``
1728 ++++++++++++++++++++
1732 .. rapi_resource_details:: /2/jobs/[job_id]
1735 .. _rapi-res-jobs-job_id+get:
1740 Returns a dictionary with job parameters, containing the fields
1741 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.
1743 The result includes:
1745 - id: job ID as a number
1746 - status: current job status as a string
1747 - ops: involved OpCodes as a list of dictionaries for each opcodes in
1749 - opstatus: OpCodes status as a list
1750 - opresult: OpCodes results as a list
1752 For a successful opcode, the ``opresult`` field corresponding to it will
1753 contain the raw result from its :term:`LogicalUnit`. In case an opcode
1754 has failed, its element in the opresult list will be a list of two
1757 - first element the error type (the Ganeti internal error name)
1758 - second element a list of either one or two elements:
1760 - the first element is the textual error description
1761 - the second element, if any, will hold an error classification
1763 The error classification is most useful for the ``OpPrereqError``
1764 error type - these errors happen before the OpCode has started
1765 executing, so it's possible to retry the OpCode without side
1766 effects. But whether it make sense to retry depends on the error
1771 errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
1772 errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
1773 errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
1774 errors.ECODE_ENVIRON, errors.ECODE_TEMP_NORES])
1776 :pyeval:`errors.ECODE_RESOLVER`
1777 Resolver errors. This usually means that a name doesn't exist in DNS,
1778 so if it's a case of slow DNS propagation the operation can be retried
1781 :pyeval:`errors.ECODE_NORES`
1782 Not enough resources (iallocator failure, disk space, memory,
1783 etc.). If the resources on the cluster increase, the operation might
1786 :pyeval:`errors.ECODE_TEMP_NORES`
1787 Simliar to :pyeval:`errors.ECODE_NORES`, but indicating the operation
1788 should be attempted again after some time.
1790 :pyeval:`errors.ECODE_INVAL`
1791 Wrong arguments (at syntax level). The operation will not ever be
1792 accepted unless the arguments change.
1794 :pyeval:`errors.ECODE_STATE`
1795 Wrong entity state. For example, live migration has been requested for
1796 a down instance, or instance creation on an offline node. The
1797 operation can be retried once the resource has changed state.
1799 :pyeval:`errors.ECODE_NOENT`
1800 Entity not found. For example, information has been requested for an
1803 :pyeval:`errors.ECODE_EXISTS`
1804 Entity already exists. For example, instance creation has been
1805 requested for an already-existing instance.
1807 :pyeval:`errors.ECODE_NOTUNIQUE`
1808 Resource not unique (e.g. MAC or IP duplication).
1810 :pyeval:`errors.ECODE_FAULT`
1811 Internal cluster error. For example, a node is unreachable but not set
1812 offline, or the ganeti node daemons are not working, etc. A
1813 ``gnt-cluster verify`` should be run.
1815 :pyeval:`errors.ECODE_ENVIRON`
1816 Environment error (e.g. node disk error). A ``gnt-cluster verify``
1819 Note that in the above list, by entity we refer to a node or instance,
1820 while by a resource we refer to an instance's disk, or NIC, etc.
1823 .. _rapi-res-jobs-job_id+delete:
1828 Cancel a not-yet-started job.
1831 .. _rapi-res-jobs-job_id-wait:
1833 ``/2/jobs/[job_id]/wait``
1834 +++++++++++++++++++++++++
1836 .. rapi_resource_details:: /2/jobs/[job_id]/wait
1839 .. _rapi-res-jobs-job_id-wait+get:
1844 Waits for changes on a job. Takes the following body parameters in a
1848 The job fields on which to watch for changes
1850 ``previous_job_info``
1851 Previously received field values or None if not yet available
1853 ``previous_log_serial``
1854 Highest log serial number received so far or None if not yet
1857 Returns None if no changes have been detected and a dict with two keys,
1858 ``job_info`` and ``log_entries`` otherwise.
1868 .. rapi_resource_details:: /2/nodes
1871 .. _rapi-res-nodes+get:
1876 Returns a list of all nodes.
1882 "id": "node1.example.com",
1883 "uri": "\/nodes\/node1.example.com"
1886 "id": "node2.example.com",
1887 "uri": "\/nodes\/node2.example.com"
1891 If the optional bool *bulk* argument is provided and set to a true value
1892 (i.e ``?bulk=1``), the output contains detailed information about nodes
1895 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1904 "name": "www.example.com",
1917 .. _rapi-res-nodes-node_name:
1919 ``/2/nodes/[node_name]``
1920 +++++++++++++++++++++++++++++++++
1922 Returns information about a node.
1924 .. rapi_resource_details:: /2/nodes/[node_name]
1927 .. _rapi-res-nodes-node_name+get:
1932 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1936 .. _rapi-res-nodes-node_name-powercycle:
1938 ``/2/nodes/[node_name]/powercycle``
1939 +++++++++++++++++++++++++++++++++++
1943 .. rapi_resource_details:: /2/nodes/[node_name]/powercycle
1946 .. _rapi-res-nodes-node_name-powercycle+post:
1955 .. opcode_result:: OP_NODE_POWERCYCLE
1958 .. _rapi-res-nodes-node_name-evacuate:
1960 ``/2/nodes/[node_name]/evacuate``
1961 +++++++++++++++++++++++++++++++++
1963 Evacuates instances off a node.
1965 .. rapi_resource_details:: /2/nodes/[node_name]/evacuate
1968 .. _rapi-res-nodes-node_name-evacuate+post:
1973 Returns a job ID. The result of the job will contain the IDs of the
1974 individual jobs submitted to evacuate the node.
1978 .. opcode_params:: OP_NODE_EVACUATE
1981 Up to and including Ganeti 2.4 query arguments were used. Those are no
1982 longer supported. The new request can be detected by the presence of the
1983 :pyeval:`rlib2._NODE_EVAC_RES1` feature string.
1987 .. opcode_result:: OP_NODE_EVACUATE
1990 .. _rapi-res-nodes-node_name-migrate:
1992 ``/2/nodes/[node_name]/migrate``
1993 +++++++++++++++++++++++++++++++++
1995 Migrates all primary instances from a node.
1997 .. rapi_resource_details:: /2/nodes/[node_name]/migrate
2000 .. _rapi-res-nodes-node_name-migrate+post:
2005 If no mode is explicitly specified, each instances' hypervisor default
2006 migration mode will be used. Body parameters:
2008 .. opcode_params:: OP_NODE_MIGRATE
2011 The query arguments used up to and including Ganeti 2.4 are deprecated
2012 and should no longer be used. The new request format can be detected by
2013 the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
2017 .. opcode_result:: OP_NODE_MIGRATE
2020 .. _rapi-res-nodes-node_name-role:
2022 ``/2/nodes/[node_name]/role``
2023 +++++++++++++++++++++++++++++
2027 .. rapi_resource_details:: /2/nodes/[node_name]/role
2029 The role is always one of the following:
2036 Note that the 'master' role is a special, and currently it can't be
2037 modified via RAPI, only via the command line (``gnt-cluster
2041 .. _rapi-res-nodes-node_name-role+get:
2046 Returns the current node role.
2053 .. _rapi-res-nodes-node_name-role+put:
2058 Change the node role.
2060 The request is a string which should be PUT to this URI. The result will
2063 It supports the bool ``force`` argument.
2067 .. opcode_result:: OP_NODE_SET_PARAMS
2070 .. _rapi-res-nodes-node_name-modify:
2072 ``/2/nodes/[node_name]/modify``
2073 +++++++++++++++++++++++++++++++
2075 Modifies the parameters of a node.
2077 .. rapi_resource_details:: /2/nodes/[node_name]/modify
2080 .. _rapi-res-nodes-node_name-modify+post:
2089 .. opcode_params:: OP_NODE_SET_PARAMS
2094 .. opcode_result:: OP_NODE_SET_PARAMS
2097 .. _rapi-res-nodes-node_name-storage:
2099 ``/2/nodes/[node_name]/storage``
2100 ++++++++++++++++++++++++++++++++
2102 Manages storage units on the node.
2104 .. rapi_resource_details:: /2/nodes/[node_name]/storage
2107 .. _rapi-res-nodes-node_name-storage+get:
2112 FIXME: enable ".. pyassert::" again when all storage types are
2115 constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
2116 constants.ST_LVM_PV,
2117 constants.ST_LVM_VG])
2119 Requests a list of storage units on a node. Requires the parameters
2120 ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
2121 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
2122 ``output_fields``. The result will be a job id, using which the result
2126 .. _rapi-res-nodes-node_name-storage-modify:
2128 ``/2/nodes/[node_name]/storage/modify``
2129 +++++++++++++++++++++++++++++++++++++++
2131 Modifies storage units on the node.
2133 .. rapi_resource_details:: /2/nodes/[node_name]/storage/modify
2136 .. _rapi-res-nodes-node_name-storage-modify+put:
2141 Modifies parameters of storage units on the node. Requires the
2142 parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
2143 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
2144 and ``name`` (name of the storage unit). Parameters can be passed
2145 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
2146 is supported. The result will be a job id.
2150 .. opcode_result:: OP_NODE_MODIFY_STORAGE
2153 .. _rapi-res-nodes-node_name-storage-repair:
2155 ``/2/nodes/[node_name]/storage/repair``
2156 +++++++++++++++++++++++++++++++++++++++
2158 Repairs a storage unit on the node.
2160 .. rapi_resource_details:: /2/nodes/[node_name]/storage/repair
2163 .. _rapi-res-nodes-node_name-storage-repair+put:
2170 constants.VALID_STORAGE_OPERATIONS == {
2171 constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
2174 Repairs a storage unit on the node. Requires the parameters
2175 ``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
2176 repaired) and ``name`` (name of the storage unit). The result will be a
2181 .. opcode_result:: OP_REPAIR_NODE_STORAGE
2184 .. _rapi-res-nodes-node_name-tags:
2186 ``/2/nodes/[node_name]/tags``
2187 +++++++++++++++++++++++++++++
2189 Manages per-node tags.
2191 .. rapi_resource_details:: /2/nodes/[node_name]/tags
2194 .. _rapi-res-nodes-node_name-tags+get:
2199 Returns a list of tags.
2203 ["tag1", "tag2", "tag3"]
2206 .. _rapi-res-nodes-node_name-tags+put:
2213 The request as a list of strings should be PUT to this URI. The result
2216 It supports the ``dry-run`` argument.
2219 .. _rapi-res-nodes-node_name-tags+delete:
2226 In order to delete a set of tags, the DELETE request should be addressed
2229 /tags?tag=[tag]&tag=[tag]
2231 It supports the ``dry-run`` argument.
2234 .. _rapi-res-query-resource:
2236 ``/2/query/[resource]``
2237 +++++++++++++++++++++++
2239 Requests resource information. Available fields can be found in man
2240 pages and using ``/2/query/[resource]/fields``. The resource is one of
2241 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
2242 design document <design-query2>` for more details.
2244 .. rapi_resource_details:: /2/query/[resource]
2247 .. _rapi-res-query-resource+get:
2252 Returns list of included fields and actual data. Takes a query parameter
2253 named "fields", containing a comma-separated list of field names. Does
2254 not support filtering.
2257 .. _rapi-res-query-resource+put:
2262 Returns list of included fields and actual data. The list of requested
2263 fields can either be given as the query parameter "fields" or as a body
2264 parameter with the same name. The optional body parameter "filter" can
2265 be given and must be either ``null`` or a list containing filter
2269 .. _rapi-res-query-resource-fields:
2271 ``/2/query/[resource]/fields``
2272 ++++++++++++++++++++++++++++++
2274 Request list of available fields for a resource. The resource is one of
2275 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
2276 :doc:`query2 design document <design-query2>` for more details.
2278 .. rapi_resource_details:: /2/query/[resource]/fields
2281 .. _rapi-res-query-resource-fields+get:
2286 Returns a list of field descriptions for available fields. Takes an
2287 optional query parameter named "fields", containing a comma-separated
2288 list of field names.
2298 .. rapi_resource_details:: /2/os
2301 .. _rapi-res-os+get:
2306 Return a list of all OSes.
2308 Can return error 500 in case of a problem. Since this is a costly
2309 operation for Ganeti 2.0, it is not recommended to execute it too often.
2321 Manages cluster tags.
2323 .. rapi_resource_details:: /2/tags
2326 .. _rapi-res-tags+get:
2331 Returns the cluster tags.
2335 ["tag1", "tag2", "tag3"]
2338 .. _rapi-res-tags+put:
2345 The request as a list of strings should be PUT to this URI. The result
2348 It supports the ``dry-run`` argument.
2351 .. _rapi-res-tags+delete:
2358 In order to delete a set of tags, the DELETE request should be addressed
2361 /tags?tag=[tag]&tag=[tag]
2363 It supports the ``dry-run`` argument.
2366 .. _rapi-res-version:
2371 The version resource.
2373 This resource should be used to determine the remote API version and to
2374 adapt clients accordingly.
2376 .. rapi_resource_details:: /version
2379 .. _rapi-res-version+get:
2384 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
2388 .. _rapi-access-permissions:
2393 The following list describes the access permissions required for each
2394 resource. See :ref:`rapi-users` for more details.
2396 .. rapi_access_table::
2399 .. vim: set textwidth=72 :