Add constants for storage types to constants.py
[ganeti-github.git] / doc / rapi.rst
1 Ganeti remote API
2 =================
3
4 Documents Ganeti version |version|
5
6 .. contents::
7
8 Introduction
9 ------------
10
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
17 parameters.
18
19 .. _rapi-users:
20
21 Users and passwords
22 -------------------
23
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
26 read automatically.
27
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).
33
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.
41
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:
47
48 .. pyassert::
49
50   rapi.RAPI_ACCESS_ALL == set([
51     rapi.RAPI_ACCESS_WRITE,
52     rapi.RAPI_ACCESS_READ,
53     ])
54
55 .. pyassert::
56
57   rlib2.R_2_nodes_name_storage.GET_ACCESS == [rapi.RAPI_ACCESS_WRITE]
58
59 .. pyassert::
60
61   rlib2.R_2_jobs_id_wait.GET_ACCESS == [rapi.RAPI_ACCESS_WRITE]
62
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.
74
75 Example::
76
77   # Give Jack and Fred read-only access
78   jack abc123
79   fred {cleartext}foo555
80
81   # Give write access to an imaginary instance creation script
82   autocreator xyz789 write
83
84   # Hashed password for Jessica
85   jessica {HA1}7046452df2cbb530877058712cf17bd4 write
86
87   # Monitoring can query for values
88   monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read
89
90   # A user who can read and write (the former is implied by granting
91   # write access)
92   superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read,write
93
94
95 .. [#pwhash] Using the MD5 hash of username, realm and password is
96    described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
97    and 3.3. The reason for using it over another algorithm is forward
98    compatibility. If ``ganeti-rapi`` were to implement HTTP Digest
99    authentication in the future, the same hash could be used.
100    In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
101    API``, can only be changed by modifying the source code.
102
103
104 Protocol
105 --------
106
107 The protocol used is JSON_ over HTTP designed after the REST_ principle.
108 HTTP Basic authentication as per :rfc:`2617` is supported.
109
110 .. _JSON: http://www.json.org/
111 .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
112
113 HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request
114 header ``Content-type`` be set to ``application/json`` (see :rfc:`2616`
115 (HTTP/1.1), section 7.2.1).
116
117
118 A note on JSON as used by RAPI
119 ++++++++++++++++++++++++++++++
120
121 JSON_ as used by Ganeti RAPI does not conform to the specification in
122 :rfc:`4627`. Section 2 defines a JSON text to be either an object
123 (``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
124 of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
125 some requests or responses. Changing this now would likely break
126 existing clients and cause a lot of trouble.
127
128 .. highlight:: ruby
129
130 Unlike Python's `JSON encoder and decoder
131 <http://docs.python.org/library/json.html>`_, other programming
132 languages or libraries may only provide a strict implementation, not
133 allowing plain values. For those, responses can usually be wrapped in an
134 array whose first element is then used, e.g. the response ``"1234"``
135 becomes ``["1234"]``. This works equally well for more complex values.
136 Example in Ruby::
137
138   require "json"
139
140   # Insert code to get response here
141   response = "\"1234\""
142
143   decoded = JSON.parse("[#{response}]").first
144
145 Short of modifying the encoder to allow encoding to a less strict
146 format, requests will have to be formatted by hand. Newer RAPI requests
147 already use a dictionary as their input data and shouldn't cause any
148 problems.
149
150
151 PUT or POST?
152 ------------
153
154 According to :rfc:`2616` the main difference between PUT and POST is
155 that POST can create new resources but PUT can only create the resource
156 the URI was pointing to on the PUT request.
157
158 Unfortunately, due to historic reasons, the Ganeti RAPI library is not
159 consistent with this usage, so just use the methods as documented below
160 for each resource.
161
162 For more details have a look in the source code at
163 ``lib/rapi/rlib2.py``.
164
165
166 Generic parameter types
167 -----------------------
168
169 A few generic refered parameter types and the values they allow.
170
171 ``bool``
172 ++++++++
173
174 A boolean option will accept ``1`` or ``0`` as numbers but not
175 i.e. ``True`` or ``False``.
176
177 Generic parameters
178 ------------------
179
180 A few parameter mean the same thing across all resources which implement
181 it.
182
183 ``bulk``
184 ++++++++
185
186 Bulk-mode means that for the resources which usually return just a list
187 of child resources (e.g. ``/2/instances`` which returns just instance
188 names), the output will instead contain detailed data for all these
189 subresources. This is more efficient than query-ing the sub-resources
190 themselves.
191
192 ``dry-run``
193 +++++++++++
194
195 The boolean *dry-run* argument, if provided and set, signals to Ganeti
196 that the job should not be executed, only the pre-execution checks will
197 be done.
198
199 This is useful in trying to determine (without guarantees though, as in
200 the meantime the cluster state could have changed) if the operation is
201 likely to succeed or at least start executing.
202
203 ``force``
204 +++++++++++
205
206 Force operation to continue even if it will cause the cluster to become
207 inconsistent (e.g. because there are not enough master candidates).
208
209 Parameter details
210 -----------------
211
212 Some parameters are not straight forward, so we describe them in details
213 here.
214
215 .. _rapi-ipolicy:
216
217 ``ipolicy``
218 +++++++++++
219
220 The instance policy specification is a dict with the following fields:
221
222 .. pyassert::
223
224   constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN,
225                                      constants.ISPECS_MAX,
226                                      constants.ISPECS_STD,
227                                      constants.IPOLICY_DTS,
228                                      constants.IPOLICY_VCPU_RATIO,
229                                      constants.IPOLICY_SPINDLE_RATIO])
230
231
232 .. pyassert::
233
234   (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
235    set([constants.ISPEC_MEM_SIZE,
236         constants.ISPEC_DISK_SIZE,
237         constants.ISPEC_DISK_COUNT,
238         constants.ISPEC_CPU_COUNT,
239         constants.ISPEC_NIC_COUNT,
240         constants.ISPEC_SPINDLE_USE]))
241
242 .. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
243 .. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
244 .. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
245
246
247 |ispec-min|, |ispec-max|, |ispec-std|
248   A sub- `dict` with the following fields, which sets the limit and standard
249   values of the instances:
250
251   :pyeval:`constants.ISPEC_MEM_SIZE`
252     The size in MiB of the memory used
253   :pyeval:`constants.ISPEC_DISK_SIZE`
254     The size in MiB of the disk used
255   :pyeval:`constants.ISPEC_DISK_COUNT`
256     The numbers of disks used
257   :pyeval:`constants.ISPEC_CPU_COUNT`
258     The numbers of cpus used
259   :pyeval:`constants.ISPEC_NIC_COUNT`
260     The numbers of nics used
261   :pyeval:`constants.ISPEC_SPINDLE_USE`
262     The numbers of virtual disk spindles used by this instance. They are
263     not real in the sense of actual HDD spindles, but useful for
264     accounting the spindle usage on the residing node
265 :pyeval:`constants.IPOLICY_DTS`
266   A `list` of disk templates allowed for instances using this policy
267 :pyeval:`constants.IPOLICY_VCPU_RATIO`
268   Maximum ratio of virtual to physical CPUs (`float`)
269 :pyeval:`constants.IPOLICY_SPINDLE_RATIO`
270   Maximum ratio of instances to their node's ``spindle_count`` (`float`)
271
272 Usage examples
273 --------------
274
275 You can access the API using your favorite programming language as long
276 as it supports network connections.
277
278 Ganeti RAPI client
279 ++++++++++++++++++
280
281 Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``.
282
283 Shell
284 +++++
285
286 .. highlight:: shell-example
287
288 Using wget::
289
290    $ wget -q -O - https://%CLUSTERNAME%:5080/2/info
291
292 or curl::
293
294   $ curl https://%CLUSTERNAME%:5080/2/info
295
296
297 Python
298 ++++++
299
300 .. highlight:: python
301
302 ::
303
304   import urllib2
305   f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info')
306   print f.read()
307
308
309 JavaScript
310 ++++++++++
311
312 .. warning:: While it's possible to use JavaScript, it poses several
313    potential problems, including browser blocking request due to
314    non-standard ports or different domain names. Fetching the data on
315    the webserver is easier.
316
317 .. highlight:: javascript
318
319 ::
320
321   var url = 'https://CLUSTERNAME:5080/2/info';
322   var info;
323   var xmlreq = new XMLHttpRequest();
324   xmlreq.onreadystatechange = function () {
325     if (xmlreq.readyState != 4) return;
326     if (xmlreq.status == 200) {
327       info = eval("(" + xmlreq.responseText + ")");
328       alert(info);
329     } else {
330       alert('Error fetching cluster info');
331     }
332     xmlreq = null;
333   };
334   xmlreq.open('GET', url, true);
335   xmlreq.send(null);
336
337 Resources
338 ---------
339
340 .. highlight:: javascript
341
342 ``/``
343 +++++
344
345 The root resource. Has no function, but for legacy reasons the ``GET``
346 method is supported.
347
348 ``/2``
349 ++++++
350
351 Has no function, but for legacy reasons the ``GET`` method is supported.
352
353 .. _rapi-res-info:
354
355 ``/2/info``
356 +++++++++++
357
358 Cluster information resource.
359
360 .. rapi_resource_details:: /2/info
361
362
363 .. _rapi-res-info+get:
364
365 ``GET``
366 ~~~~~~~
367
368 Returns cluster information.
369
370 Example::
371
372   {
373     "config_version": 2000000,
374     "name": "cluster",
375     "software_version": "2.0.0~beta2",
376     "os_api_version": 10,
377     "export_version": 0,
378     "candidate_pool_size": 10,
379     "enabled_hypervisors": [
380       "fake"
381     ],
382     "hvparams": {
383       "fake": {}
384      },
385     "default_hypervisor": "fake",
386     "master": "node1.example.com",
387     "architecture": [
388       "64bit",
389       "x86_64"
390     ],
391     "protocol_version": 20,
392     "beparams": {
393       "default": {
394         "auto_balance": true,
395         "vcpus": 1,
396         "memory": 128
397        }
398       },
399     …
400   }
401
402
403 .. _rapi-res-redistribute-config:
404
405 ``/2/redistribute-config``
406 ++++++++++++++++++++++++++
407
408 Redistribute configuration to all nodes.
409
410 .. rapi_resource_details:: /2/redistribute-config
411
412
413 .. _rapi-res-redistribute-config+put:
414
415 ``PUT``
416 ~~~~~~~
417
418 Redistribute configuration to all nodes. The result will be a job id.
419
420 Job result:
421
422 .. opcode_result:: OP_CLUSTER_REDIST_CONF
423
424
425 .. _rapi-res-features:
426
427 ``/2/features``
428 +++++++++++++++
429
430 .. rapi_resource_details:: /2/features
431
432
433 .. _rapi-res-features+get:
434
435 ``GET``
436 ~~~~~~~
437
438 Returns a list of features supported by the RAPI server. Available
439 features:
440
441 .. pyassert::
442
443   rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1,
444                              rlib2._INST_REINSTALL_REQV1,
445                              rlib2._NODE_MIGRATE_REQV1,
446                              rlib2._NODE_EVAC_RES1])
447
448 :pyeval:`rlib2._INST_CREATE_REQV1`
449   Instance creation request data version 1 supported
450 :pyeval:`rlib2._INST_REINSTALL_REQV1`
451   Instance reinstall supports body parameters
452 :pyeval:`rlib2._NODE_MIGRATE_REQV1`
453   Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
454   request body parameters
455 :pyeval:`rlib2._NODE_EVAC_RES1`
456   Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns
457   a new-style result (see resource description)
458
459
460 .. _rapi-res-modify:
461
462 ``/2/modify``
463 ++++++++++++++++++++++++++++++++++++++++
464
465 Modifies cluster parameters.
466
467 .. rapi_resource_details:: /2/modify
468
469
470 .. _rapi-res-modify+put:
471
472 ``PUT``
473 ~~~~~~~
474
475 Returns a job ID.
476
477 Body parameters:
478
479 .. opcode_params:: OP_CLUSTER_SET_PARAMS
480
481 Job result:
482
483 .. opcode_result:: OP_CLUSTER_SET_PARAMS
484
485
486 .. _rapi-res-groups:
487
488 ``/2/groups``
489 +++++++++++++
490
491 The groups resource.
492
493 .. rapi_resource_details:: /2/groups
494
495
496 .. _rapi-res-groups+get:
497
498 ``GET``
499 ~~~~~~~
500
501 Returns a list of all existing node groups.
502
503 Example::
504
505     [
506       {
507         "name": "group1",
508         "uri": "\/2\/groups\/group1"
509       },
510       {
511         "name": "group2",
512         "uri": "\/2\/groups\/group2"
513       }
514     ]
515
516 If the optional bool *bulk* argument is provided and set to a true value
517 (i.e ``?bulk=1``), the output contains detailed information about node
518 groups as a list.
519
520 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
521
522 Example::
523
524     [
525       {
526         "name": "group1",
527         "node_cnt": 2,
528         "node_list": [
529           "node1.example.com",
530           "node2.example.com"
531         ],
532         "uuid": "0d7d407c-262e-49af-881a-6a430034bf43",
533         …
534       },
535       {
536         "name": "group2",
537         "node_cnt": 1,
538         "node_list": [
539           "node3.example.com"
540         ],
541         "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c",
542         …
543       },
544       …
545     ]
546
547
548 .. _rapi-res-groups+post:
549
550 ``POST``
551 ~~~~~~~~
552
553 Creates a node group.
554
555 If the optional bool *dry-run* argument is provided, the job will not be
556 actually executed, only the pre-execution checks will be done.
557
558 Returns: a job ID that can be used later for polling.
559
560 Body parameters:
561
562 .. opcode_params:: OP_GROUP_ADD
563
564 Earlier versions used a parameter named ``name`` which, while still
565 supported, has been renamed to ``group_name``.
566
567 Job result:
568
569 .. opcode_result:: OP_GROUP_ADD
570
571
572 .. _rapi-res-groups-group_name:
573
574 ``/2/groups/[group_name]``
575 ++++++++++++++++++++++++++
576
577 Returns information about a node group.
578
579 .. rapi_resource_details:: /2/groups/[group_name]
580
581
582 .. _rapi-res-groups-group_name+get:
583
584 ``GET``
585 ~~~~~~~
586
587 Returns information about a node group, similar to the bulk output from
588 the node group list.
589
590 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
591
592 .. _rapi-res-groups-group_name+delete:
593
594 ``DELETE``
595 ~~~~~~~~~~
596
597 Deletes a node group.
598
599 It supports the ``dry-run`` argument.
600
601 Job result:
602
603 .. opcode_result:: OP_GROUP_REMOVE
604
605
606 .. _rapi-res-groups-group_name-modify:
607
608 ``/2/groups/[group_name]/modify``
609 +++++++++++++++++++++++++++++++++
610
611 Modifies the parameters of a node group.
612
613 .. rapi_resource_details:: /2/groups/[group_name]/modify
614
615
616 .. _rapi-res-groups-group_name-modify+put:
617
618 ``PUT``
619 ~~~~~~~
620
621 Returns a job ID.
622
623 Body parameters:
624
625 .. opcode_params:: OP_GROUP_SET_PARAMS
626    :exclude: group_name
627
628 Job result:
629
630 .. opcode_result:: OP_GROUP_SET_PARAMS
631
632
633 .. _rapi-res-groups-group_name-rename:
634
635 ``/2/groups/[group_name]/rename``
636 +++++++++++++++++++++++++++++++++
637
638 Renames a node group.
639
640 .. rapi_resource_details:: /2/groups/[group_name]/rename
641
642
643 .. _rapi-res-groups-group_name-rename+put:
644
645 ``PUT``
646 ~~~~~~~
647
648 Returns a job ID.
649
650 Body parameters:
651
652 .. opcode_params:: OP_GROUP_RENAME
653    :exclude: group_name
654
655 Job result:
656
657 .. opcode_result:: OP_GROUP_RENAME
658
659
660 .. _rapi-res-groups-group_name-assign-nodes:
661
662 ``/2/groups/[group_name]/assign-nodes``
663 +++++++++++++++++++++++++++++++++++++++
664
665 Assigns nodes to a group.
666
667 .. rapi_resource_details:: /2/groups/[group_name]/assign-nodes
668
669 .. _rapi-res-groups-group_name-assign-nodes+put:
670
671 ``PUT``
672 ~~~~~~~
673
674 Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
675
676 Body parameters:
677
678 .. opcode_params:: OP_GROUP_ASSIGN_NODES
679    :exclude: group_name, force, dry_run
680
681 Job result:
682
683 .. opcode_result:: OP_GROUP_ASSIGN_NODES
684
685 .. _rapi-res-groups-group_name-tags:
686
687 ``/2/groups/[group_name]/tags``
688 +++++++++++++++++++++++++++++++
689
690 Manages per-nodegroup tags.
691
692 .. rapi_resource_details:: /2/groups/[group_name]/tags
693
694
695 .. _rapi-res-groups-group_name-tags+get:
696
697 ``GET``
698 ~~~~~~~
699
700 Returns a list of tags.
701
702 Example::
703
704     ["tag1", "tag2", "tag3"]
705
706 .. _rapi-res-groups-group_name-tags+put:
707
708 ``PUT``
709 ~~~~~~~
710
711 Add a set of tags.
712
713 The request as a list of strings should be ``PUT`` to this URI. The
714 result will be a job id.
715
716 It supports the ``dry-run`` argument.
717
718
719 .. _rapi-res-groups-group_name-tags+delete:
720
721 ``DELETE``
722 ~~~~~~~~~~
723
724 Delete a tag.
725
726 In order to delete a set of tags, the DELETE request should be addressed
727 to URI like::
728
729     /tags?tag=[tag]&tag=[tag]
730
731 It supports the ``dry-run`` argument.
732
733
734 .. _rapi-res-networks:
735
736 ``/2/networks``
737 +++++++++++++++
738
739 The networks resource.
740
741 .. rapi_resource_details:: /2/networks
742
743
744 .. _rapi-res-networks+get:
745
746 ``GET``
747 ~~~~~~~
748
749 Returns a list of all existing networks.
750
751 Example::
752
753     [
754       {
755         "name": "network1",
756         "uri": "\/2\/networks\/network1"
757       },
758       {
759         "name": "network2",
760         "uri": "\/2\/networks\/network2"
761       }
762     ]
763
764 If the optional bool *bulk* argument is provided and set to a true value
765 (i.e ``?bulk=1``), the output contains detailed information about networks
766 as a list.
767
768 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
769
770 Example::
771
772     [
773       {
774         'external_reservations': '10.0.0.0, 10.0.0.1, 10.0.0.15',
775         'free_count': 13,
776         'gateway': '10.0.0.1',
777         'gateway6': None,
778         'group_list': ['default(bridged, prv0)'],
779         'inst_list': [],
780         'mac_prefix': None,
781         'map': 'XX.............X',
782         'name': 'nat',
783         'network': '10.0.0.0/28',
784         'network6': None,
785         'reserved_count': 3,
786         'tags': ['nfdhcpd'],
787         …
788       },
789       …
790     ]
791
792
793 .. _rapi-res-networks+post:
794
795 ``POST``
796 ~~~~~~~~
797
798 Creates a network.
799
800 If the optional bool *dry-run* argument is provided, the job will not be
801 actually executed, only the pre-execution checks will be done.
802
803 Returns: a job ID that can be used later for polling.
804
805 Body parameters:
806
807 .. opcode_params:: OP_NETWORK_ADD
808
809 Job result:
810
811 .. opcode_result:: OP_NETWORK_ADD
812
813
814 .. _rapi-res-networks-network_name:
815
816 ``/2/networks/[network_name]``
817 ++++++++++++++++++++++++++++++
818
819 Returns information about a network.
820
821 .. rapi_resource_details:: /2/networks/[network_name]
822
823
824 .. _rapi-res-networks-network_name+get:
825
826 ``GET``
827 ~~~~~~~
828
829 Returns information about a network, similar to the bulk output from
830 the network list.
831
832 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
833
834
835 .. _rapi-res-networks-network_name+delete:
836
837 ``DELETE``
838 ~~~~~~~~~~
839
840 Deletes a network.
841
842 It supports the ``dry-run`` argument.
843
844 Job result:
845
846 .. opcode_result:: OP_NETWORK_REMOVE
847
848
849 .. _rapi-res-networks-network_name-modify:
850
851 ``/2/networks/[network_name]/modify``
852 +++++++++++++++++++++++++++++++++++++
853
854 Modifies the parameters of a network.
855
856 .. rapi_resource_details:: /2/networks/[network_name]/modify
857
858
859 .. _rapi-res-networks-network_name-modify+put:
860
861 ``PUT``
862 ~~~~~~~
863
864 Returns a job ID.
865
866 Body parameters:
867
868 .. opcode_params:: OP_NETWORK_SET_PARAMS
869
870 Job result:
871
872 .. opcode_result:: OP_NETWORK_SET_PARAMS
873
874
875 .. _rapi-res-networks-network_name-connect:
876
877 ``/2/networks/[network_name]/connect``
878 ++++++++++++++++++++++++++++++++++++++
879
880 Connects a network to a nodegroup.
881
882 .. rapi_resource_details:: /2/networks/[network_name]/connect
883
884
885 .. _rapi-res-networks-network_name-connect+put:
886
887 ``PUT``
888 ~~~~~~~
889
890 Returns a job ID. It supports the ``dry-run`` arguments.
891
892 Body parameters:
893
894 .. opcode_params:: OP_NETWORK_CONNECT
895
896 Job result:
897
898 .. opcode_result:: OP_NETWORK_CONNECT
899
900
901 .. _rapi-res-networks-network_name-disconnect:
902
903 ``/2/networks/[network_name]/disconnect``
904 +++++++++++++++++++++++++++++++++++++++++
905
906 Disonnects a network from a nodegroup.
907
908 .. rapi_resource_details:: /2/networks/[network_name]/disconnect
909
910
911 .. _rapi-res-networks-network_name-disconnect+put:
912
913 ``PUT``
914 ~~~~~~~
915
916 Returns a job ID. It supports the ``dry-run`` arguments.
917
918 Body parameters:
919
920 .. opcode_params:: OP_NETWORK_DISCONNECT
921
922 Job result:
923
924 .. opcode_result:: OP_NETWORK_DISCONNECT
925
926
927 .. _rapi-res-networks-network_name-tags:
928
929 ``/2/networks/[network_name]/tags``
930 +++++++++++++++++++++++++++++++++++
931
932 Manages per-network tags.
933
934 .. rapi_resource_details:: /2/networks/[network_name]/tags
935
936
937 .. _rapi-res-networks-network_name-tags+get:
938
939 ``GET``
940 ~~~~~~~
941
942 Returns a list of tags.
943
944 Example::
945
946     ["tag1", "tag2", "tag3"]
947
948
949 .. _rapi-res-networks-network_name-tags+put:
950
951 ``PUT``
952 ~~~~~~~
953
954 Add a set of tags.
955
956 The request as a list of strings should be ``PUT`` to this URI. The
957 result will be a job id.
958
959 It supports the ``dry-run`` argument.
960
961
962 .. _rapi-res-networks-network_name-tags+delete:
963
964 ``DELETE``
965 ~~~~~~~~~~
966
967 Delete a tag.
968
969 In order to delete a set of tags, the DELETE request should be addressed
970 to URI like::
971
972     /tags?tag=[tag]&tag=[tag]
973
974 It supports the ``dry-run`` argument.
975
976
977 .. _rapi-res-instances-multi-alloc:
978
979 ``/2/instances-multi-alloc``
980 ++++++++++++++++++++++++++++
981
982 Tries to allocate multiple instances.
983
984 .. rapi_resource_details:: /2/instances-multi-alloc
985
986
987 .. _rapi-res-instances-multi-alloc+post:
988
989 ``POST``
990 ~~~~~~~~
991
992 The parameters:
993
994 .. opcode_params:: OP_INSTANCE_MULTI_ALLOC
995
996 Job result:
997
998 .. opcode_result:: OP_INSTANCE_MULTI_ALLOC
999
1000
1001 .. _rapi-res-instances:
1002
1003 ``/2/instances``
1004 ++++++++++++++++
1005
1006 The instances resource.
1007
1008 .. rapi_resource_details:: /2/instances
1009
1010
1011 .. _rapi-res-instances+get:
1012
1013 ``GET``
1014 ~~~~~~~
1015
1016 Returns a list of all available instances.
1017
1018 Example::
1019
1020     [
1021       {
1022         "name": "web.example.com",
1023         "uri": "\/instances\/web.example.com"
1024       },
1025       {
1026         "name": "mail.example.com",
1027         "uri": "\/instances\/mail.example.com"
1028       }
1029     ]
1030
1031 If the optional bool *bulk* argument is provided and set to a true value
1032 (i.e ``?bulk=1``), the output contains detailed information about
1033 instances as a list.
1034
1035 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
1036
1037 Example::
1038
1039     [
1040       {
1041         "status": "running",
1042         "disk_usage": 20480,
1043         "nic.bridges": [
1044           "xen-br0"
1045         ],
1046         "name": "web.example.com",
1047         "tags": ["tag1", "tag2"],
1048         "beparams": {
1049           "vcpus": 2,
1050           "memory": 512
1051         },
1052         "disk.sizes": [
1053           20480
1054         ],
1055         "pnode": "node1.example.com",
1056         "nic.macs": ["01:23:45:67:89:01"],
1057         "snodes": ["node2.example.com"],
1058         "disk_template": "drbd",
1059         "admin_state": true,
1060         "os": "debian-etch",
1061         "oper_state": true,
1062         …
1063       },
1064       …
1065     ]
1066
1067
1068 .. _rapi-res-instances+post:
1069
1070 ``POST``
1071 ~~~~~~~~
1072
1073 Creates an instance.
1074
1075 If the optional bool *dry-run* argument is provided, the job will not be
1076 actually executed, only the pre-execution checks will be done. Query-ing
1077 the job result will return, in both dry-run and normal case, the list of
1078 nodes selected for the instance.
1079
1080 Returns: a job ID that can be used later for polling.
1081
1082 Body parameters:
1083
1084 ``__version__`` (int, required)
1085   Must be ``1`` (older Ganeti versions used a different format for
1086   instance creation requests, version ``0``, but that format is no
1087   longer supported)
1088
1089 .. opcode_params:: OP_INSTANCE_CREATE
1090
1091 Earlier versions used parameters named ``name`` and ``os``. These have
1092 been replaced by ``instance_name`` and ``os_type`` to match the
1093 underlying opcode. The old names can still be used.
1094
1095 Job result:
1096
1097 .. opcode_result:: OP_INSTANCE_CREATE
1098
1099
1100 .. _rapi-res-instances-instance_name:
1101
1102 ``/2/instances/[instance_name]``
1103 ++++++++++++++++++++++++++++++++
1104
1105 Instance-specific resource.
1106
1107 .. rapi_resource_details:: /2/instances/[instance_name]
1108
1109
1110 .. _rapi-res-instances-instance_name+get:
1111
1112 ``GET``
1113 ~~~~~~~
1114
1115 Returns information about an instance, similar to the bulk output from
1116 the instance list.
1117
1118 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
1119
1120
1121 .. _rapi-res-instances-instance_name+delete:
1122
1123 ``DELETE``
1124 ~~~~~~~~~~
1125
1126 Deletes an instance.
1127
1128 It supports the ``dry-run`` argument.
1129
1130 Job result:
1131
1132 .. opcode_result:: OP_INSTANCE_REMOVE
1133
1134
1135 .. _rapi-res-instances-instance_name-info:
1136
1137 ``/2/instances/[instance_name]/info``
1138 +++++++++++++++++++++++++++++++++++++++
1139
1140 .. rapi_resource_details:: /2/instances/[instance_name]/info
1141
1142
1143 .. _rapi-res-instances-instance_name-info+get:
1144
1145 ``GET``
1146 ~~~~~~~
1147
1148 Requests detailed information about the instance. An optional parameter,
1149 ``static`` (bool), can be set to return only static information from the
1150 configuration without querying the instance's nodes. The result will be
1151 a job id.
1152
1153 Job result:
1154
1155 .. opcode_result:: OP_INSTANCE_QUERY_DATA
1156
1157
1158 .. _rapi-res-instances-instance_name-reboot:
1159
1160 ``/2/instances/[instance_name]/reboot``
1161 +++++++++++++++++++++++++++++++++++++++
1162
1163 Reboots URI for an instance.
1164
1165 .. rapi_resource_details:: /2/instances/[instance_name]/reboot
1166
1167
1168 .. _rapi-res-instances-instance_name-reboot+post:
1169
1170 ``POST``
1171 ~~~~~~~~
1172
1173 Reboots the instance.
1174
1175 The URI takes optional ``type=soft|hard|full`` and
1176 ``ignore_secondaries=0|1`` parameters.
1177
1178 ``type`` defines the reboot type. ``soft`` is just a normal reboot,
1179 without terminating the hypervisor. ``hard`` means full shutdown
1180 (including terminating the hypervisor process) and startup again.
1181 ``full`` is like ``hard`` but also recreates the configuration from
1182 ground up as if you would have done a ``gnt-instance shutdown`` and
1183 ``gnt-instance start`` on it.
1184
1185 ``ignore_secondaries`` is a bool argument indicating if we start the
1186 instance even if secondary disks are failing.
1187
1188 It supports the ``dry-run`` argument.
1189
1190 Job result:
1191
1192 .. opcode_result:: OP_INSTANCE_REBOOT
1193
1194
1195 .. _rapi-res-instances-instance_name-shutdown:
1196
1197 ``/2/instances/[instance_name]/shutdown``
1198 +++++++++++++++++++++++++++++++++++++++++
1199
1200 Instance shutdown URI.
1201
1202 .. rapi_resource_details:: /2/instances/[instance_name]/shutdown
1203
1204
1205 .. _rapi-res-instances-instance_name-shutdown+put:
1206
1207 ``PUT``
1208 ~~~~~~~
1209
1210 Shutdowns an instance.
1211
1212 It supports the ``dry-run`` argument.
1213
1214 .. opcode_params:: OP_INSTANCE_SHUTDOWN
1215    :exclude: instance_name, dry_run
1216
1217 Job result:
1218
1219 .. opcode_result:: OP_INSTANCE_SHUTDOWN
1220
1221
1222 .. _rapi-res-instances-instance_name-startup:
1223
1224 ``/2/instances/[instance_name]/startup``
1225 ++++++++++++++++++++++++++++++++++++++++
1226
1227 Instance startup URI.
1228
1229 .. rapi_resource_details:: /2/instances/[instance_name]/startup
1230
1231
1232 .. _rapi-res-instances-instance_name-startup+put:
1233
1234 ``PUT``
1235 ~~~~~~~
1236
1237 Startup an instance.
1238
1239 The URI takes an optional ``force=1|0`` parameter to start the
1240 instance even if secondary disks are failing.
1241
1242 It supports the ``dry-run`` argument.
1243
1244 Job result:
1245
1246 .. opcode_result:: OP_INSTANCE_STARTUP
1247
1248
1249 .. _rapi-res-instances-instance_name-reinstall:
1250
1251 ``/2/instances/[instance_name]/reinstall``
1252 ++++++++++++++++++++++++++++++++++++++++++++++
1253
1254 Installs the operating system again.
1255
1256 .. rapi_resource_details:: /2/instances/[instance_name]/reinstall
1257
1258
1259 .. _rapi-res-instances-instance_name-reinstall+post:
1260
1261 ``POST``
1262 ~~~~~~~~
1263
1264 Returns a job ID.
1265
1266 Body parameters:
1267
1268 ``os`` (string, required)
1269   Instance operating system.
1270 ``start`` (bool, defaults to true)
1271   Whether to start instance after reinstallation.
1272 ``osparams`` (dict)
1273   Dictionary with (temporary) OS parameters.
1274
1275 For backwards compatbility, this resource also takes the query
1276 parameters ``os`` (OS template name) and ``nostartup`` (bool). New
1277 clients should use the body parameters.
1278
1279
1280 .. _rapi-res-instances-instance_name-replace-disks:
1281
1282 ``/2/instances/[instance_name]/replace-disks``
1283 ++++++++++++++++++++++++++++++++++++++++++++++
1284
1285 Replaces disks on an instance.
1286
1287 .. rapi_resource_details:: /2/instances/[instance_name]/replace-disks
1288
1289
1290 .. _rapi-res-instances-instance_name-replace-disks+post:
1291
1292 ``POST``
1293 ~~~~~~~~
1294
1295 Returns a job ID.
1296
1297 Body parameters:
1298
1299 .. opcode_params:: OP_INSTANCE_REPLACE_DISKS
1300    :exclude: instance_name
1301
1302 Ganeti 2.4 and below used query parameters. Those are deprecated and
1303 should no longer be used.
1304
1305 Job result:
1306
1307 .. opcode_result:: OP_INSTANCE_REPLACE_DISKS
1308
1309
1310 .. _rapi-res-instances-instance_name-activate-disks:
1311
1312 ``/2/instances/[instance_name]/activate-disks``
1313 +++++++++++++++++++++++++++++++++++++++++++++++
1314
1315 Activate disks on an instance.
1316
1317 .. rapi_resource_details:: /2/instances/[instance_name]/activate-disks
1318
1319
1320 .. _rapi-res-instances-instance_name-activate-disks+put:
1321
1322 ``PUT``
1323 ~~~~~~~
1324
1325 Takes the bool parameter ``ignore_size``. When set ignore the recorded
1326 size (useful for forcing activation when recorded size is wrong).
1327
1328 Job result:
1329
1330 .. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
1331
1332
1333 .. _rapi-res-instances-instance_name-deactivate-disks:
1334
1335 ``/2/instances/[instance_name]/deactivate-disks``
1336 +++++++++++++++++++++++++++++++++++++++++++++++++
1337
1338 Deactivate disks on an instance.
1339
1340 .. rapi_resource_details:: /2/instances/[instance_name]/deactivate-disks
1341
1342
1343 .. _rapi-res-instances-instance_name-deactivate-disks+put:
1344
1345 ``PUT``
1346 ~~~~~~~
1347
1348 Takes no parameters.
1349
1350 Job result:
1351
1352 .. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS
1353
1354
1355 .. _rapi-res-instances-instance_name-recreate-disks:
1356
1357 ``/2/instances/[instance_name]/recreate-disks``
1358 +++++++++++++++++++++++++++++++++++++++++++++++++
1359
1360 Recreate disks of an instance.
1361
1362 .. rapi_resource_details:: /2/instances/[instance_name]/recreate-disks
1363
1364
1365 .. _rapi-res-instances-instance_name-recreate-disks+post:
1366
1367 ``POST``
1368 ~~~~~~~~
1369
1370 Returns a job ID.
1371
1372 Body parameters:
1373
1374 .. opcode_params:: OP_INSTANCE_RECREATE_DISKS
1375    :exclude: instance_name
1376
1377 Job result:
1378
1379 .. opcode_result:: OP_INSTANCE_RECREATE_DISKS
1380
1381
1382 .. _rapi-res-instances-instance_name-disk-disk_index-grow:
1383
1384 ``/2/instances/[instance_name]/disk/[disk_index]/grow``
1385 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1386
1387 Grows one disk of an instance.
1388
1389 .. rapi_resource_details:: /2/instances/[instance_name]/disk/[disk_index]/grow
1390
1391
1392 .. _rapi-res-instances-instance_name-disk-disk_index-grow+post:
1393
1394 ``POST``
1395 ~~~~~~~~
1396
1397 Returns a job ID.
1398
1399 Body parameters:
1400
1401 .. opcode_params:: OP_INSTANCE_GROW_DISK
1402    :exclude: instance_name, disk
1403
1404 Job result:
1405
1406 .. opcode_result:: OP_INSTANCE_GROW_DISK
1407
1408
1409 .. _rapi-res-instances-instance_name-prepare-export:
1410
1411 ``/2/instances/[instance_name]/prepare-export``
1412 +++++++++++++++++++++++++++++++++++++++++++++++++
1413
1414 Prepares an export of an instance.
1415
1416 .. rapi_resource_details:: /2/instances/[instance_name]/prepare-export
1417
1418
1419 .. _rapi-res-instances-instance_name-prepare-export+put:
1420
1421 ``PUT``
1422 ~~~~~~~
1423
1424 Takes one parameter, ``mode``, for the export mode. Returns a job ID.
1425
1426 Job result:
1427
1428 .. opcode_result:: OP_BACKUP_PREPARE
1429
1430
1431 .. _rapi-res-instances-instance_name-export:
1432
1433 ``/2/instances/[instance_name]/export``
1434 +++++++++++++++++++++++++++++++++++++++++++++++++
1435
1436 Exports an instance.
1437
1438 .. rapi_resource_details:: /2/instances/[instance_name]/export
1439
1440
1441 .. _rapi-res-instances-instance_name-export+put:
1442
1443 ``PUT``
1444 ~~~~~~~
1445
1446 Returns a job ID.
1447
1448 Body parameters:
1449
1450 .. opcode_params:: OP_BACKUP_EXPORT
1451    :exclude: instance_name
1452    :alias: target_node=destination
1453
1454 Job result:
1455
1456 .. opcode_result:: OP_BACKUP_EXPORT
1457
1458
1459 .. _rapi-res-instances-instance_name-migrate:
1460
1461 ``/2/instances/[instance_name]/migrate``
1462 ++++++++++++++++++++++++++++++++++++++++
1463
1464 Migrates an instance.
1465
1466 .. rapi_resource_details:: /2/instances/[instance_name]/migrate
1467
1468
1469 .. _rapi-res-instances-instance_name-migrate+put:
1470
1471 ``PUT``
1472 ~~~~~~~
1473
1474 Returns a job ID.
1475
1476 Body parameters:
1477
1478 .. opcode_params:: OP_INSTANCE_MIGRATE
1479    :exclude: instance_name, live
1480
1481 Job result:
1482
1483 .. opcode_result:: OP_INSTANCE_MIGRATE
1484
1485
1486 .. _rapi-res-instances-instance_name-failover:
1487
1488 ``/2/instances/[instance_name]/failover``
1489 +++++++++++++++++++++++++++++++++++++++++
1490
1491 Does a failover of an instance.
1492
1493 .. rapi_resource_details:: /2/instances/[instance_name]/failover
1494
1495
1496 .. _rapi-res-instances-instance_name-failover+put:
1497
1498 ``PUT``
1499 ~~~~~~~
1500
1501 Returns a job ID.
1502
1503 Body parameters:
1504
1505 .. opcode_params:: OP_INSTANCE_FAILOVER
1506    :exclude: instance_name
1507
1508 Job result:
1509
1510 .. opcode_result:: OP_INSTANCE_FAILOVER
1511
1512
1513 .. _rapi-res-instances-instance_name-rename:
1514
1515 ``/2/instances/[instance_name]/rename``
1516 ++++++++++++++++++++++++++++++++++++++++
1517
1518 Renames an instance.
1519
1520 .. rapi_resource_details:: /2/instances/[instance_name]/rename
1521
1522
1523 .. _rapi-res-instances-instance_name-rename+put:
1524
1525 ``PUT``
1526 ~~~~~~~
1527
1528 Returns a job ID.
1529
1530 Body parameters:
1531
1532 .. opcode_params:: OP_INSTANCE_RENAME
1533    :exclude: instance_name
1534
1535 Job result:
1536
1537 .. opcode_result:: OP_INSTANCE_RENAME
1538
1539
1540 .. _rapi-res-instances-instance_name-modify:
1541
1542 ``/2/instances/[instance_name]/modify``
1543 ++++++++++++++++++++++++++++++++++++++++
1544
1545 Modifies an instance.
1546
1547 .. rapi_resource_details:: /2/instances/[instance_name]/modify
1548
1549
1550 .. _rapi-res-instances-instance_name-modify+put:
1551
1552 ``PUT``
1553 ~~~~~~~
1554
1555 Returns a job ID.
1556
1557 Body parameters:
1558
1559 .. opcode_params:: OP_INSTANCE_SET_PARAMS
1560    :exclude: instance_name
1561
1562 Job result:
1563
1564 .. opcode_result:: OP_INSTANCE_SET_PARAMS
1565
1566
1567 .. _rapi-res-instances-instance_name-console:
1568
1569 ``/2/instances/[instance_name]/console``
1570 ++++++++++++++++++++++++++++++++++++++++
1571
1572 Request information for connecting to instance's console.
1573
1574 .. rapi_resource_details:: /2/instances/[instance_name]/console
1575
1576
1577 .. _rapi-res-instances-instance_name-console+get:
1578
1579 ``GET``
1580 ~~~~~~~
1581
1582 Returns a dictionary containing information about the instance's
1583 console. Contained keys:
1584
1585 .. pyassert::
1586
1587    constants.CONS_ALL == frozenset([
1588      constants.CONS_MESSAGE,
1589      constants.CONS_SSH,
1590      constants.CONS_VNC,
1591      constants.CONS_SPICE,
1592      ])
1593
1594 .. pyassert::
1595
1596   frozenset(objects.InstanceConsole.GetAllSlots()) == frozenset([
1597     "command",
1598     "display",
1599     "host",
1600     "instance",
1601     "kind",
1602     "message",
1603     "port",
1604     "user",
1605     ])
1606
1607
1608 ``instance``
1609   Instance name
1610 ``kind``
1611   Console type, one of :pyeval:`constants.CONS_SSH`,
1612   :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
1613   or :pyeval:`constants.CONS_MESSAGE`
1614 ``message``
1615   Message to display (:pyeval:`constants.CONS_MESSAGE` type only)
1616 ``host``
1617   Host to connect to (:pyeval:`constants.CONS_SSH`,
1618   :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
1619 ``port``
1620   TCP port to connect to (:pyeval:`constants.CONS_VNC` or
1621   :pyeval:`constants.CONS_SPICE` only)
1622 ``user``
1623   Username to use (:pyeval:`constants.CONS_SSH` only)
1624 ``command``
1625   Command to execute on machine (:pyeval:`constants.CONS_SSH` only)
1626 ``display``
1627   VNC display number (:pyeval:`constants.CONS_VNC` only)
1628
1629
1630 .. _rapi-res-instances-instance_name-tags:
1631
1632 ``/2/instances/[instance_name]/tags``
1633 +++++++++++++++++++++++++++++++++++++
1634
1635 Manages per-instance tags.
1636
1637 .. rapi_resource_details:: /2/instances/[instance_name]/tags
1638
1639
1640 .. _rapi-res-instances-instance_name-tags+get:
1641
1642 ``GET``
1643 ~~~~~~~
1644
1645 Returns a list of tags.
1646
1647 Example::
1648
1649     ["tag1", "tag2", "tag3"]
1650
1651
1652 .. _rapi-res-instances-instance_name-tags+put:
1653
1654 ``PUT``
1655 ~~~~~~~
1656
1657 Add a set of tags.
1658
1659 The request as a list of strings should be ``PUT`` to this URI. The
1660 result will be a job id.
1661
1662 It supports the ``dry-run`` argument.
1663
1664
1665 .. _rapi-res-instances-instance_name-tags+delete:
1666
1667 ``DELETE``
1668 ~~~~~~~~~~
1669
1670 Delete a tag.
1671
1672 In order to delete a set of tags, the DELETE request should be addressed
1673 to URI like::
1674
1675     /tags?tag=[tag]&tag=[tag]
1676
1677 It supports the ``dry-run`` argument.
1678
1679
1680 .. _rapi-res-jobs:
1681
1682 ``/2/jobs``
1683 +++++++++++
1684
1685 The ``/2/jobs`` resource.
1686
1687 .. rapi_resource_details:: /2/jobs
1688
1689
1690 .. _rapi-res-jobs+get:
1691
1692 ``GET``
1693 ~~~~~~~
1694
1695 Returns a dictionary of jobs.
1696
1697 Returns: a dictionary with jobs id and uri.
1698
1699 If the optional bool *bulk* argument is provided and set to a true value
1700 (i.e. ``?bulk=1``), the output contains detailed information about jobs
1701 as a list.
1702
1703 Returned fields for bulk requests (unlike other bulk requests, these
1704 fields are not the same as for per-job requests):
1705 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`.
1706
1707
1708 .. _rapi-res-jobs-job_id:
1709
1710 ``/2/jobs/[job_id]``
1711 ++++++++++++++++++++
1712
1713 Individual job URI.
1714
1715 .. rapi_resource_details:: /2/jobs/[job_id]
1716
1717
1718 .. _rapi-res-jobs-job_id+get:
1719
1720 ``GET``
1721 ~~~~~~~
1722
1723 Returns a dictionary with job parameters, containing the fields
1724 :pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`.
1725
1726 The result includes:
1727
1728 - id: job ID as a number
1729 - status: current job status as a string
1730 - ops: involved OpCodes as a list of dictionaries for each opcodes in
1731   the job
1732 - opstatus: OpCodes status as a list
1733 - opresult: OpCodes results as a list
1734
1735 For a successful opcode, the ``opresult`` field corresponding to it will
1736 contain the raw result from its :term:`LogicalUnit`. In case an opcode
1737 has failed, its element in the opresult list will be a list of two
1738 elements:
1739
1740 - first element the error type (the Ganeti internal error name)
1741 - second element a list of either one or two elements:
1742
1743   - the first element is the textual error description
1744   - the second element, if any, will hold an error classification
1745
1746 The error classification is most useful for the ``OpPrereqError``
1747 error type - these errors happen before the OpCode has started
1748 executing, so it's possible to retry the OpCode without side
1749 effects. But whether it make sense to retry depends on the error
1750 classification:
1751
1752 .. pyassert::
1753
1754    errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES,
1755      errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT,
1756      errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT,
1757      errors.ECODE_ENVIRON, errors.ECODE_TEMP_NORES])
1758
1759 :pyeval:`errors.ECODE_RESOLVER`
1760   Resolver errors. This usually means that a name doesn't exist in DNS,
1761   so if it's a case of slow DNS propagation the operation can be retried
1762   later.
1763
1764 :pyeval:`errors.ECODE_NORES`
1765   Not enough resources (iallocator failure, disk space, memory,
1766   etc.). If the resources on the cluster increase, the operation might
1767   succeed.
1768
1769 :pyeval:`errors.ECODE_TEMP_NORES`
1770   Simliar to :pyeval:`errors.ECODE_NORES`, but indicating the operation
1771   should be attempted again after some time.
1772
1773 :pyeval:`errors.ECODE_INVAL`
1774   Wrong arguments (at syntax level). The operation will not ever be
1775   accepted unless the arguments change.
1776
1777 :pyeval:`errors.ECODE_STATE`
1778   Wrong entity state. For example, live migration has been requested for
1779   a down instance, or instance creation on an offline node. The
1780   operation can be retried once the resource has changed state.
1781
1782 :pyeval:`errors.ECODE_NOENT`
1783   Entity not found. For example, information has been requested for an
1784   unknown instance.
1785
1786 :pyeval:`errors.ECODE_EXISTS`
1787   Entity already exists. For example, instance creation has been
1788   requested for an already-existing instance.
1789
1790 :pyeval:`errors.ECODE_NOTUNIQUE`
1791   Resource not unique (e.g. MAC or IP duplication).
1792
1793 :pyeval:`errors.ECODE_FAULT`
1794   Internal cluster error. For example, a node is unreachable but not set
1795   offline, or the ganeti node daemons are not working, etc. A
1796   ``gnt-cluster verify`` should be run.
1797
1798 :pyeval:`errors.ECODE_ENVIRON`
1799   Environment error (e.g. node disk error). A ``gnt-cluster verify``
1800   should be run.
1801
1802 Note that in the above list, by entity we refer to a node or instance,
1803 while by a resource we refer to an instance's disk, or NIC, etc.
1804
1805
1806 .. _rapi-res-jobs-job_id+delete:
1807
1808 ``DELETE``
1809 ~~~~~~~~~~
1810
1811 Cancel a not-yet-started job.
1812
1813
1814 .. _rapi-res-jobs-job_id-wait:
1815
1816 ``/2/jobs/[job_id]/wait``
1817 +++++++++++++++++++++++++
1818
1819 .. rapi_resource_details:: /2/jobs/[job_id]/wait
1820
1821
1822 .. _rapi-res-jobs-job_id-wait+get:
1823
1824 ``GET``
1825 ~~~~~~~
1826
1827 Waits for changes on a job. Takes the following body parameters in a
1828 dict:
1829
1830 ``fields``
1831   The job fields on which to watch for changes
1832
1833 ``previous_job_info``
1834   Previously received field values or None if not yet available
1835
1836 ``previous_log_serial``
1837   Highest log serial number received so far or None if not yet
1838   available
1839
1840 Returns None if no changes have been detected and a dict with two keys,
1841 ``job_info`` and ``log_entries`` otherwise.
1842
1843
1844 .. _rapi-res-nodes:
1845
1846 ``/2/nodes``
1847 ++++++++++++
1848
1849 Nodes resource.
1850
1851 .. rapi_resource_details:: /2/nodes
1852
1853
1854 .. _rapi-res-nodes+get:
1855
1856 ``GET``
1857 ~~~~~~~
1858
1859 Returns a list of all nodes.
1860
1861 Example::
1862
1863     [
1864       {
1865         "id": "node1.example.com",
1866         "uri": "\/nodes\/node1.example.com"
1867       },
1868       {
1869         "id": "node2.example.com",
1870         "uri": "\/nodes\/node2.example.com"
1871       }
1872     ]
1873
1874 If the optional bool *bulk* argument is provided and set to a true value
1875 (i.e ``?bulk=1``), the output contains detailed information about nodes
1876 as a list.
1877
1878 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1879
1880 Example::
1881
1882     [
1883       {
1884         "pinst_cnt": 1,
1885         "mfree": 31280,
1886         "mtotal": 32763,
1887         "name": "www.example.com",
1888         "tags": [],
1889         "mnode": 512,
1890         "dtotal": 5246208,
1891         "sinst_cnt": 2,
1892         "dfree": 5171712,
1893         "offline": false,
1894         …
1895       },
1896       …
1897     ]
1898
1899
1900 .. _rapi-res-nodes-node_name:
1901
1902 ``/2/nodes/[node_name]``
1903 +++++++++++++++++++++++++++++++++
1904
1905 Returns information about a node.
1906
1907 .. rapi_resource_details:: /2/nodes/[node_name]
1908
1909
1910 .. _rapi-res-nodes-node_name+get:
1911
1912 ``GET``
1913 ~~~~~~~
1914
1915 Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
1916
1917
1918
1919 .. _rapi-res-nodes-node_name-powercycle:
1920
1921 ``/2/nodes/[node_name]/powercycle``
1922 +++++++++++++++++++++++++++++++++++
1923
1924 Powercycles a node.
1925
1926 .. rapi_resource_details:: /2/nodes/[node_name]/powercycle
1927
1928
1929 .. _rapi-res-nodes-node_name-powercycle+post:
1930
1931 ``POST``
1932 ~~~~~~~~
1933
1934 Returns a job ID.
1935
1936 Job result:
1937
1938 .. opcode_result:: OP_NODE_POWERCYCLE
1939
1940
1941 .. _rapi-res-nodes-node_name-evacuate:
1942
1943 ``/2/nodes/[node_name]/evacuate``
1944 +++++++++++++++++++++++++++++++++
1945
1946 Evacuates instances off a node.
1947
1948 .. rapi_resource_details:: /2/nodes/[node_name]/evacuate
1949
1950
1951 .. _rapi-res-nodes-node_name-evacuate+post:
1952
1953 ``POST``
1954 ~~~~~~~~
1955
1956 Returns a job ID. The result of the job will contain the IDs of the
1957 individual jobs submitted to evacuate the node.
1958
1959 Body parameters:
1960
1961 .. opcode_params:: OP_NODE_EVACUATE
1962    :exclude: nodes
1963
1964 Up to and including Ganeti 2.4 query arguments were used. Those are no
1965 longer supported. The new request can be detected by the presence of the
1966 :pyeval:`rlib2._NODE_EVAC_RES1` feature string.
1967
1968 Job result:
1969
1970 .. opcode_result:: OP_NODE_EVACUATE
1971
1972
1973 .. _rapi-res-nodes-node_name-migrate:
1974
1975 ``/2/nodes/[node_name]/migrate``
1976 +++++++++++++++++++++++++++++++++
1977
1978 Migrates all primary instances from a node.
1979
1980 .. rapi_resource_details:: /2/nodes/[node_name]/migrate
1981
1982
1983 .. _rapi-res-nodes-node_name-migrate+post:
1984
1985 ``POST``
1986 ~~~~~~~~
1987
1988 If no mode is explicitly specified, each instances' hypervisor default
1989 migration mode will be used. Body parameters:
1990
1991 .. opcode_params:: OP_NODE_MIGRATE
1992    :exclude: node_name
1993
1994 The query arguments used up to and including Ganeti 2.4 are deprecated
1995 and should no longer be used. The new request format can be detected by
1996 the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
1997
1998 Job result:
1999
2000 .. opcode_result:: OP_NODE_MIGRATE
2001
2002
2003 .. _rapi-res-nodes-node_name-role:
2004
2005 ``/2/nodes/[node_name]/role``
2006 +++++++++++++++++++++++++++++
2007
2008 Manages node role.
2009
2010 .. rapi_resource_details:: /2/nodes/[node_name]/role
2011
2012 The role is always one of the following:
2013
2014   - drained
2015   - master-candidate
2016   - offline
2017   - regular
2018
2019 Note that the 'master' role is a special, and currently it can't be
2020 modified via RAPI, only via the command line (``gnt-cluster
2021 master-failover``).
2022
2023
2024 .. _rapi-res-nodes-node_name-role+get:
2025
2026 ``GET``
2027 ~~~~~~~
2028
2029 Returns the current node role.
2030
2031 Example::
2032
2033     "master-candidate"
2034
2035
2036 .. _rapi-res-nodes-node_name-role+put:
2037
2038 ``PUT``
2039 ~~~~~~~
2040
2041 Change the node role.
2042
2043 The request is a string which should be PUT to this URI. The result will
2044 be a job id.
2045
2046 It supports the bool ``force`` argument.
2047
2048 Job result:
2049
2050 .. opcode_result:: OP_NODE_SET_PARAMS
2051
2052
2053 .. _rapi-res-nodes-node_name-modify:
2054
2055 ``/2/nodes/[node_name]/modify``
2056 +++++++++++++++++++++++++++++++
2057
2058 Modifies the parameters of a node.
2059
2060 .. rapi_resource_details:: /2/nodes/[node_name]/modify
2061
2062
2063 .. _rapi-res-nodes-node_name-modify+post:
2064
2065 ``POST``
2066 ~~~~~~~~
2067
2068 Returns a job ID.
2069
2070 Body parameters:
2071
2072 .. opcode_params:: OP_NODE_SET_PARAMS
2073    :exclude: node_name
2074
2075 Job result:
2076
2077 .. opcode_result:: OP_NODE_SET_PARAMS
2078
2079
2080 .. _rapi-res-nodes-node_name-storage:
2081
2082 ``/2/nodes/[node_name]/storage``
2083 ++++++++++++++++++++++++++++++++
2084
2085 Manages storage units on the node.
2086
2087 .. rapi_resource_details:: /2/nodes/[node_name]/storage
2088
2089
2090 .. _rapi-res-nodes-node_name-storage+get:
2091
2092 ``GET``
2093 ~~~~~~~
2094
2095 FIXME: enable ".. pyassert::" again when all storage types are
2096 implemented::
2097
2098    constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
2099                                          constants.ST_LVM_PV,
2100                                          constants.ST_LVM_VG])
2101
2102 Requests a list of storage units on a node. Requires the parameters
2103 ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
2104 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
2105 ``output_fields``. The result will be a job id, using which the result
2106 can be retrieved.
2107
2108
2109 .. _rapi-res-nodes-node_name-storage-modify:
2110
2111 ``/2/nodes/[node_name]/storage/modify``
2112 +++++++++++++++++++++++++++++++++++++++
2113
2114 Modifies storage units on the node.
2115
2116 .. rapi_resource_details:: /2/nodes/[node_name]/storage/modify
2117
2118
2119 .. _rapi-res-nodes-node_name-storage-modify+put:
2120
2121 ``PUT``
2122 ~~~~~~~
2123
2124 Modifies parameters of storage units on the node. Requires the
2125 parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
2126 :pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
2127 and ``name`` (name of the storage unit).  Parameters can be passed
2128 additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
2129 is supported. The result will be a job id.
2130
2131 Job result:
2132
2133 .. opcode_result:: OP_NODE_MODIFY_STORAGE
2134
2135
2136 .. _rapi-res-nodes-node_name-storage-repair:
2137
2138 ``/2/nodes/[node_name]/storage/repair``
2139 +++++++++++++++++++++++++++++++++++++++
2140
2141 Repairs a storage unit on the node.
2142
2143 .. rapi_resource_details:: /2/nodes/[node_name]/storage/repair
2144
2145
2146 .. _rapi-res-nodes-node_name-storage-repair+put:
2147
2148 ``PUT``
2149 ~~~~~~~
2150
2151 .. pyassert::
2152
2153    constants.VALID_STORAGE_OPERATIONS == {
2154     constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
2155     }
2156
2157 Repairs a storage unit on the node. Requires the parameters
2158 ``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
2159 repaired) and ``name`` (name of the storage unit). The result will be a
2160 job id.
2161
2162 Job result:
2163
2164 .. opcode_result:: OP_REPAIR_NODE_STORAGE
2165
2166
2167 .. _rapi-res-nodes-node_name-tags:
2168
2169 ``/2/nodes/[node_name]/tags``
2170 +++++++++++++++++++++++++++++
2171
2172 Manages per-node tags.
2173
2174 .. rapi_resource_details:: /2/nodes/[node_name]/tags
2175
2176
2177 .. _rapi-res-nodes-node_name-tags+get:
2178
2179 ``GET``
2180 ~~~~~~~
2181
2182 Returns a list of tags.
2183
2184 Example::
2185
2186     ["tag1", "tag2", "tag3"]
2187
2188
2189 .. _rapi-res-nodes-node_name-tags+put:
2190
2191 ``PUT``
2192 ~~~~~~~
2193
2194 Add a set of tags.
2195
2196 The request as a list of strings should be PUT to this URI. The result
2197 will be a job id.
2198
2199 It supports the ``dry-run`` argument.
2200
2201
2202 .. _rapi-res-nodes-node_name-tags+delete:
2203
2204 ``DELETE``
2205 ~~~~~~~~~~
2206
2207 Deletes tags.
2208
2209 In order to delete a set of tags, the DELETE request should be addressed
2210 to URI like::
2211
2212     /tags?tag=[tag]&tag=[tag]
2213
2214 It supports the ``dry-run`` argument.
2215
2216
2217 .. _rapi-res-query-resource:
2218
2219 ``/2/query/[resource]``
2220 +++++++++++++++++++++++
2221
2222 Requests resource information. Available fields can be found in man
2223 pages and using ``/2/query/[resource]/fields``. The resource is one of
2224 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
2225 design document <design-query2>` for more details.
2226
2227 .. rapi_resource_details:: /2/query/[resource]
2228
2229
2230 .. _rapi-res-query-resource+get:
2231
2232 ``GET``
2233 ~~~~~~~
2234
2235 Returns list of included fields and actual data. Takes a query parameter
2236 named "fields", containing a comma-separated list of field names. Does
2237 not support filtering.
2238
2239
2240 .. _rapi-res-query-resource+put:
2241
2242 ``PUT``
2243 ~~~~~~~
2244
2245 Returns list of included fields and actual data. The list of requested
2246 fields can either be given as the query parameter "fields" or as a body
2247 parameter with the same name. The optional body parameter "filter" can
2248 be given and must be either ``null`` or a list containing filter
2249 operators.
2250
2251
2252 .. _rapi-res-query-resource-fields:
2253
2254 ``/2/query/[resource]/fields``
2255 ++++++++++++++++++++++++++++++
2256
2257 Request list of available fields for a resource. The resource is one of
2258 :pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
2259 :doc:`query2 design document <design-query2>` for more details.
2260
2261 .. rapi_resource_details:: /2/query/[resource]/fields
2262
2263
2264 .. _rapi-res-query-resource-fields+get:
2265
2266 ``GET``
2267 ~~~~~~~
2268
2269 Returns a list of field descriptions for available fields. Takes an
2270 optional query parameter named "fields", containing a comma-separated
2271 list of field names.
2272
2273
2274 .. _rapi-res-os:
2275
2276 ``/2/os``
2277 +++++++++
2278
2279 OS resource.
2280
2281 .. rapi_resource_details:: /2/os
2282
2283
2284 .. _rapi-res-os+get:
2285
2286 ``GET``
2287 ~~~~~~~
2288
2289 Return a list of all OSes.
2290
2291 Can return error 500 in case of a problem. Since this is a costly
2292 operation for Ganeti 2.0, it is not recommended to execute it too often.
2293
2294 Example::
2295
2296     ["debian-etch"]
2297
2298
2299 .. _rapi-res-tags:
2300
2301 ``/2/tags``
2302 +++++++++++
2303
2304 Manages cluster tags.
2305
2306 .. rapi_resource_details:: /2/tags
2307
2308
2309 .. _rapi-res-tags+get:
2310
2311 ``GET``
2312 ~~~~~~~
2313
2314 Returns the cluster tags.
2315
2316 Example::
2317
2318     ["tag1", "tag2", "tag3"]
2319
2320
2321 .. _rapi-res-tags+put:
2322
2323 ``PUT``
2324 ~~~~~~~
2325
2326 Adds a set of tags.
2327
2328 The request as a list of strings should be PUT to this URI. The result
2329 will be a job id.
2330
2331 It supports the ``dry-run`` argument.
2332
2333
2334 .. _rapi-res-tags+delete:
2335
2336 ``DELETE``
2337 ~~~~~~~~~~
2338
2339 Deletes tags.
2340
2341 In order to delete a set of tags, the DELETE request should be addressed
2342 to URI like::
2343
2344     /tags?tag=[tag]&tag=[tag]
2345
2346 It supports the ``dry-run`` argument.
2347
2348
2349 .. _rapi-res-version:
2350
2351 ``/version``
2352 ++++++++++++
2353
2354 The version resource.
2355
2356 This resource should be used to determine the remote API version and to
2357 adapt clients accordingly.
2358
2359 .. rapi_resource_details:: /version
2360
2361
2362 .. _rapi-res-version+get:
2363
2364 ``GET``
2365 ~~~~~~~
2366
2367 Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0
2368 returns ``2``.
2369
2370
2371 .. _rapi-access-permissions:
2372
2373 Access permissions
2374 ------------------
2375
2376 The following list describes the access permissions required for each
2377 resource. See :ref:`rapi-users` for more details.
2378
2379 .. rapi_access_table::
2380
2381
2382 .. vim: set textwidth=72 :
2383 .. Local Variables:
2384 .. mode: rst
2385 .. fill-column: 72
2386 .. End: