X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/b292b986fe6fa1ec43e068ef378de33b16d21a99..1ec34e2636440202e89707cb896545a9e62f63e0:/doc/rapi.rst diff --git a/doc/rapi.rst b/doc/rapi.rst index 5613b83..3bab0f7 100644 --- a/doc/rapi.rst +++ b/doc/rapi.rst @@ -16,6 +16,7 @@ it runs on TCP port 5080, but this can be changed either in which is used by default, can also be disabled by passing command line parameters. +.. _rapi-users: Users and passwords ------------------- @@ -24,12 +25,11 @@ Users and passwords ``/var/lib/ganeti/rapi/users``) on startup. Changes to the file will be read automatically. -Each line consists of two or three fields separated by whitespace. The -first two fields are for username and password. The third field is -optional and can be used to specify per-user options. Currently, -``write`` is the only option supported and enables the user to execute -operations modifying the cluster. Lines starting with the hash sign -(``#``) are treated as comments. +Lines starting with the hash sign (``#``) are treated as comments. Each +line consists of two or three fields separated by whitespace. The first +two fields are for username and password. The third field is optional +and can be used to specify per-user options (separated by comma without +spaces). Passwords can either be written in clear text or as a hash. Clear text passwords may not start with an opening brace (``{``) or they must be @@ -37,7 +37,40 @@ prefixed with ``{cleartext}``. To use the hashed form, get the MD5 hash of the string ``$username:Ganeti Remote API:$password`` (e.g. ``echo -n 'jack:Ganeti Remote API:abc123' | openssl md5``) [#pwhash]_ and prefix it with ``{ha1}``. Using the scheme prefix for all passwords is -recommended. Scheme prefixes are not case sensitive. +recommended. Scheme prefixes are case insensitive. + +Options control a user's access permissions. The section +:ref:`rapi-access-permissions` lists the permissions required for each +resource. If the ``--require-authentication`` command line option is +given to the ``ganeti-rapi`` daemon, all requests require +authentication. Available options: + +.. pyassert:: + + rapi.RAPI_ACCESS_ALL == set([ + rapi.RAPI_ACCESS_WRITE, + rapi.RAPI_ACCESS_READ, + ]) + +.. pyassert:: + + rlib2.R_2_nodes_name_storage.GET_ACCESS == [rapi.RAPI_ACCESS_WRITE] + +.. pyassert:: + + rlib2.R_2_jobs_id_wait.GET_ACCESS == [rapi.RAPI_ACCESS_WRITE] + +:pyeval:`rapi.RAPI_ACCESS_WRITE` + Enables the user to execute operations modifying the cluster. Implies + :pyeval:`rapi.RAPI_ACCESS_READ` access. Resources blocking other + operations for read-only access, such as + :ref:`/2/nodes/[node_name]/storage ` + or blocking server-side processes, such as + :ref:`/2/jobs/[job_id]/wait `, use + :pyeval:`rapi.RAPI_ACCESS_WRITE` to control access to their + :pyeval:`http.HTTP_GET` method. +:pyeval:`rapi.RAPI_ACCESS_READ` + Allow access to operations querying for information. Example:: @@ -51,10 +84,24 @@ Example:: # Hashed password for Jessica jessica {HA1}7046452df2cbb530877058712cf17bd4 write + # Monitoring can query for values + monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read + + # A user who can read and write (the former is implied by granting + # write access) + superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read,write + +When using the RAPI, username and password can be sent to the server +by using the standard HTTP basic access authentication. This means that +for accessing the protected URL ``https://cluster.example.com/resource``, +the address ``https://username:password@cluster.example.com/resource`` should +be used instead. +Alternatively, the appropriate parameter of your HTTP client +(such as ``-u`` for ``curl``) can be used. .. [#pwhash] Using the MD5 hash of username, realm and password is - described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 and - 3.3. The reason for using it over another algorithm is forward + described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2 + and 3.3. The reason for using it over another algorithm is forward compatibility. If ``ganeti-rapi`` were to implement HTTP Digest authentication in the future, the same hash could be used. In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote @@ -70,6 +117,10 @@ HTTP Basic authentication as per :rfc:`2617` is supported. .. _JSON: http://www.json.org/ .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer +HTTP requests with a body (e.g. ``PUT`` or ``POST``) require the request +header ``Content-type`` be set to ``application/json`` (see :rfc:`2616` +(HTTP/1.1), section 7.2.1). + A note on JSON as used by RAPI ++++++++++++++++++++++++++++++ @@ -162,6 +213,74 @@ likely to succeed or at least start executing. Force operation to continue even if it will cause the cluster to become inconsistent (e.g. because there are not enough master candidates). +Parameter details +----------------- + +Some parameters are not straight forward, so we describe them in details +here. + +.. _rapi-ipolicy: + +``ipolicy`` ++++++++++++ + +The instance policy specification is a dict with the following fields: + +.. pyassert:: + + constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MINMAX, + constants.ISPECS_STD, + constants.IPOLICY_DTS, + constants.IPOLICY_VCPU_RATIO, + constants.IPOLICY_SPINDLE_RATIO]) + + +.. pyassert:: + + (set(constants.ISPECS_PARAMETER_TYPES.keys()) == + set([constants.ISPEC_MEM_SIZE, + constants.ISPEC_DISK_SIZE, + constants.ISPEC_DISK_COUNT, + constants.ISPEC_CPU_COUNT, + constants.ISPEC_NIC_COUNT, + constants.ISPEC_SPINDLE_USE])) + +.. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN` +.. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX` +.. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD` + + +:pyeval:`constants.ISPECS_MINMAX` + A list of dictionaries, each with the following two fields: + + |ispec-min|, |ispec-max| + A sub- `dict` with the following fields, which sets the limit of the + instances: + + :pyeval:`constants.ISPEC_MEM_SIZE` + The size in MiB of the memory used + :pyeval:`constants.ISPEC_DISK_SIZE` + The size in MiB of the disk used + :pyeval:`constants.ISPEC_DISK_COUNT` + The numbers of disks used + :pyeval:`constants.ISPEC_CPU_COUNT` + The numbers of cpus used + :pyeval:`constants.ISPEC_NIC_COUNT` + The numbers of nics used + :pyeval:`constants.ISPEC_SPINDLE_USE` + The numbers of virtual disk spindles used by this instance. They + are not real in the sense of actual HDD spindles, but useful for + accounting the spindle usage on the residing node +|ispec-std| + A sub- `dict` with the same fields as |ispec-min| and |ispec-max| above, + which sets the standard values of the instances. +:pyeval:`constants.IPOLICY_DTS` + A `list` of disk templates allowed for instances using this policy +:pyeval:`constants.IPOLICY_VCPU_RATIO` + Maximum ratio of virtual to physical CPUs (`float`) +:pyeval:`constants.IPOLICY_SPINDLE_RATIO` + Maximum ratio of instances to their node's ``spindle_count`` (`float`) + Usage examples -------------- @@ -176,16 +295,21 @@ Ganeti includes a standalone RAPI client, ``lib/rapi/client.py``. Shell +++++ -.. highlight:: sh +.. highlight:: shell-example -Using wget:: +Using ``wget``:: - wget -q -O - https://CLUSTERNAME:5080/2/info + $ wget -q -O - https://%CLUSTERNAME%:5080/2/info -or curl:: +or ``curl``:: - curl https://CLUSTERNAME:5080/2/info + $ curl https://%CLUSTERNAME%:5080/2/info +Note: with ``curl``, the request method (GET, POST, PUT) can be specified +using the ``-X`` command line option, and the username/password can be +specified with the ``-u`` option. In case of POST requests with a body, the +Content-Type can be set to JSON (as per the Protocol_ section) using the +parameter ``-H "Content-Type: application/json"``. Python ++++++ @@ -235,37 +359,25 @@ Resources ``/`` +++++ -The root resource. - -It supports the following commands: ``GET``. - -``GET`` -~~~~~~~ - -Shows the list of mapped resources. - -Returns: a dictionary with 'name' and 'uri' keys for each of them. +The root resource. Has no function, but for legacy reasons the ``GET`` +method is supported. ``/2`` ++++++ -The ``/2`` resource, the root of the version 2 API. - -It supports the following commands: ``GET``. +Has no function, but for legacy reasons the ``GET`` method is supported. -``GET`` -~~~~~~~ - -Show the list of mapped resources. - -Returns: a dictionary with ``name`` and ``uri`` keys for each of them. +.. _rapi-res-info: ``/2/info`` +++++++++++ Cluster information resource. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/info + + +.. _rapi-res-info+get: ``GET`` ~~~~~~~ @@ -300,44 +412,79 @@ Example:: "vcpus": 1, "memory": 128 } - } - } + }, + … + } + +.. _rapi-res-redistribute-config: ``/2/redistribute-config`` ++++++++++++++++++++++++++ Redistribute configuration to all nodes. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/redistribute-config + + +.. _rapi-res-redistribute-config+put: ``PUT`` ~~~~~~~ Redistribute configuration to all nodes. The result will be a job id. +Job result: + +.. opcode_result:: OP_CLUSTER_REDIST_CONF + + +.. _rapi-res-features: ``/2/features`` +++++++++++++++ +.. rapi_resource_details:: /2/features + + +.. _rapi-res-features+get: + ``GET`` ~~~~~~~ Returns a list of features supported by the RAPI server. Available features: -``instance-create-reqv1`` - Instance creation request data version 1 supported. -``instance-reinstall-reqv1`` - Instance reinstall supports body parameters. +.. pyassert:: + + rlib2.ALL_FEATURES == set([rlib2._INST_CREATE_REQV1, + rlib2._INST_REINSTALL_REQV1, + rlib2._NODE_MIGRATE_REQV1, + rlib2._NODE_EVAC_RES1]) + +:pyeval:`rlib2._INST_CREATE_REQV1` + Instance creation request data version 1 supported +:pyeval:`rlib2._INST_REINSTALL_REQV1` + Instance reinstall supports body parameters +:pyeval:`rlib2._NODE_MIGRATE_REQV1` + Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports + request body parameters +:pyeval:`rlib2._NODE_EVAC_RES1` + Whether evacuating a node (``/2/nodes/[node_name]/evacuate``) returns + a new-style result (see resource description) +.. _rapi-res-modify: + ``/2/modify`` ++++++++++++++++++++++++++++++++++++++++ Modifies cluster parameters. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/modify + + +.. _rapi-res-modify+put: ``PUT`` ~~~~~~~ @@ -348,13 +495,22 @@ Body parameters: .. opcode_params:: OP_CLUSTER_SET_PARAMS +Job result: + +.. opcode_result:: OP_CLUSTER_SET_PARAMS + + +.. _rapi-res-groups: ``/2/groups`` +++++++++++++ The groups resource. -It supports the following commands: ``GET``, ``POST``. +.. rapi_resource_details:: /2/groups + + +.. _rapi-res-groups+get: ``GET`` ~~~~~~~ @@ -378,6 +534,8 @@ If the optional bool *bulk* argument is provided and set to a true value (i.e ``?bulk=1``), the output contains detailed information about node groups as a list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`. + Example:: [ @@ -388,7 +546,8 @@ Example:: "node1.example.com", "node2.example.com" ], - "uuid": "0d7d407c-262e-49af-881a-6a430034bf43" + "uuid": "0d7d407c-262e-49af-881a-6a430034bf43", + … }, { "name": "group2", @@ -396,10 +555,15 @@ Example:: "node_list": [ "node3.example.com" ], - "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c" - } + "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c", + … + }, + … ] + +.. _rapi-res-groups+post: + ``POST`` ~~~~~~~~ @@ -412,16 +576,27 @@ Returns: a job ID that can be used later for polling. Body parameters: -``name`` (string, required) - Node group name. +.. opcode_params:: OP_GROUP_ADD + +Earlier versions used a parameter named ``name`` which, while still +supported, has been renamed to ``group_name``. + +Job result: + +.. opcode_result:: OP_GROUP_ADD +.. _rapi-res-groups-group_name: + ``/2/groups/[group_name]`` ++++++++++++++++++++++++++ Returns information about a node group. -It supports the following commands: ``GET``, ``DELETE``. +.. rapi_resource_details:: /2/groups/[group_name] + + +.. _rapi-res-groups-group_name+get: ``GET`` ~~~~~~~ @@ -429,6 +604,10 @@ It supports the following commands: ``GET``, ``DELETE``. Returns information about a node group, similar to the bulk output from the node group list. +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`. + +.. _rapi-res-groups-group_name+delete: + ``DELETE`` ~~~~~~~~~~ @@ -436,13 +615,22 @@ Deletes a node group. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_GROUP_REMOVE + + +.. _rapi-res-groups-group_name-modify: ``/2/groups/[group_name]/modify`` +++++++++++++++++++++++++++++++++ Modifies the parameters of a node group. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/groups/[group_name]/modify + + +.. _rapi-res-groups-group_name-modify+put: ``PUT`` ~~~~~~~ @@ -451,16 +639,25 @@ Returns a job ID. Body parameters: -``alloc_policy`` (string) - If present, the new allocation policy for the node group. +.. opcode_params:: OP_GROUP_SET_PARAMS + :exclude: group_name + +Job result: + +.. opcode_result:: OP_GROUP_SET_PARAMS +.. _rapi-res-groups-group_name-rename: + ``/2/groups/[group_name]/rename`` +++++++++++++++++++++++++++++++++ Renames a node group. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/groups/[group_name]/rename + + +.. _rapi-res-groups-group_name-rename+put: ``PUT`` ~~~~~~~ @@ -469,16 +666,24 @@ Returns a job ID. Body parameters: -``new_name`` (string, required) - New node group name. +.. opcode_params:: OP_GROUP_RENAME + :exclude: group_name + +Job result: +.. opcode_result:: OP_GROUP_RENAME + + +.. _rapi-res-groups-group_name-assign-nodes: ``/2/groups/[group_name]/assign-nodes`` +++++++++++++++++++++++++++++++++++++++ Assigns nodes to a group. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/groups/[group_name]/assign-nodes + +.. _rapi-res-groups-group_name-assign-nodes+put: ``PUT`` ~~~~~~~ @@ -487,321 +692,721 @@ Returns a job ID. It supports the ``dry-run`` and ``force`` arguments. Body parameters: -``nodes`` (list, required) - One or more nodes to assign to the group. +.. opcode_params:: OP_GROUP_ASSIGN_NODES + :exclude: group_name, force, dry_run +Job result: -``/2/instances`` -++++++++++++++++ +.. opcode_result:: OP_GROUP_ASSIGN_NODES -The instances resource. +.. _rapi-res-groups-group_name-tags: + +``/2/groups/[group_name]/tags`` ++++++++++++++++++++++++++++++++ + +Manages per-nodegroup tags. -It supports the following commands: ``GET``, ``POST``. +.. rapi_resource_details:: /2/groups/[group_name]/tags + + +.. _rapi-res-groups-group_name-tags+get: ``GET`` ~~~~~~~ -Returns a list of all available instances. +Returns a list of tags. + +Example:: + + ["tag1", "tag2", "tag3"] + +.. _rapi-res-groups-group_name-tags+put: + +``PUT`` +~~~~~~~ + +Add a set of tags. + +The request as a list of strings should be ``PUT`` to this URI. The +result will be a job id. + +It supports the ``dry-run`` argument. + + +.. _rapi-res-groups-group_name-tags+delete: + +``DELETE`` +~~~~~~~~~~ + +Delete a tag. + +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: + + /tags?tag=[tag]&tag=[tag] + +It supports the ``dry-run`` argument. + + +.. _rapi-res-networks: + +``/2/networks`` ++++++++++++++++ + +The networks resource. + +.. rapi_resource_details:: /2/networks + + +.. _rapi-res-networks+get: + +``GET`` +~~~~~~~ + +Returns a list of all existing networks. Example:: [ { - "name": "web.example.com", - "uri": "\/instances\/web.example.com" + "name": "network1", + "uri": "\/2\/networks\/network1" }, { - "name": "mail.example.com", - "uri": "\/instances\/mail.example.com" + "name": "network2", + "uri": "\/2\/networks\/network2" } ] If the optional bool *bulk* argument is provided and set to a true value -(i.e ``?bulk=1``), the output contains detailed information about -instances as a list. +(i.e ``?bulk=1``), the output contains detailed information about networks +as a list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`. Example:: [ { - "status": "running", - "disk_usage": 20480, - "nic.bridges": [ - "xen-br0" - ], - "name": "web.example.com", - "tags": ["tag1", "tag2"], - "beparams": { - "vcpus": 2, - "memory": 512 - }, - "disk.sizes": [ - 20480 - ], - "pnode": "node1.example.com", - "nic.macs": ["01:23:45:67:89:01"], - "snodes": ["node2.example.com"], - "disk_template": "drbd", - "admin_state": true, - "os": "debian-etch", - "oper_state": true + 'external_reservations': '10.0.0.0, 10.0.0.1, 10.0.0.15', + 'free_count': 13, + 'gateway': '10.0.0.1', + 'gateway6': None, + 'group_list': ['default(bridged, prv0)'], + 'inst_list': [], + 'mac_prefix': None, + 'map': 'XX.............X', + 'name': 'nat', + 'network': '10.0.0.0/28', + 'network6': None, + 'reserved_count': 3, + 'tags': ['nfdhcpd'], + … }, - ... + … ] +.. _rapi-res-networks+post: + ``POST`` ~~~~~~~~ -Creates an instance. +Creates a network. If the optional bool *dry-run* argument is provided, the job will not be -actually executed, only the pre-execution checks will be done. Query-ing -the job result will return, in both dry-run and normal case, the list of -nodes selected for the instance. +actually executed, only the pre-execution checks will be done. Returns: a job ID that can be used later for polling. Body parameters: -``__version__`` (int, required) - Must be ``1`` (older Ganeti versions used a different format for - instance creation requests, version ``0``, but that format is not - documented). -``mode`` (string, required) - Instance creation mode. -``name`` (string, required) - Instance name. -``disk_template`` (string, required) - Disk template for instance. -``disks`` (list, required) - List of disk definitions. Example: ``[{"size": 100}, {"size": 5}]``. - Each disk definition must contain a ``size`` value and can contain an - optional ``mode`` value denoting the disk access mode (``ro`` or - ``rw``). -``nics`` (list, required) - List of NIC (network interface) definitions. Example: ``[{}, {}, - {"ip": "198.51.100.4"}]``. Each NIC definition can contain the - optional values ``ip``, ``mode``, ``link`` and ``bridge``. -``os`` (string, required) - Instance operating system. -``osparams`` (dictionary) - Dictionary with OS parameters. If not valid for the given OS, the job - will fail. -``force_variant`` (bool) - Whether to force an unknown variant. -``no_install`` (bool) - Do not install the OS (will enable no-start) -``pnode`` (string) - Primary node. -``snode`` (string) - Secondary node. -``src_node`` (string) - Source node for import. -``src_path`` (string) - Source directory for import. -``start`` (bool) - Whether to start instance after creation. -``ip_check`` (bool) - Whether to ensure instance's IP address is inactive. -``name_check`` (bool) - Whether to ensure instance's name is resolvable. -``file_storage_dir`` (string) - File storage directory. -``file_driver`` (string) - File storage driver. -``iallocator`` (string) - Instance allocator name. -``source_handshake`` (list) - Signed handshake from source (remote import only). -``source_x509_ca`` (string) - Source X509 CA in PEM format (remote import only). -``source_instance_name`` (string) - Source instance name (remote import only). -``hypervisor`` (string) - Hypervisor name. -``hvparams`` (dict) - Hypervisor parameters, hypervisor-dependent. -``beparams`` (dict) - Backend parameters. +.. opcode_params:: OP_NETWORK_ADD +Job result: -``/2/instances/[instance_name]`` -++++++++++++++++++++++++++++++++ +.. opcode_result:: OP_NETWORK_ADD -Instance-specific resource. -It supports the following commands: ``GET``, ``DELETE``. +.. _rapi-res-networks-network_name: + +``/2/networks/[network_name]`` +++++++++++++++++++++++++++++++ + +Returns information about a network. + +.. rapi_resource_details:: /2/networks/[network_name] + + +.. _rapi-res-networks-network_name+get: ``GET`` ~~~~~~~ -Returns information about an instance, similar to the bulk output from -the instance list. +Returns information about a network, similar to the bulk output from +the network list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`. + + +.. _rapi-res-networks-network_name+delete: ``DELETE`` ~~~~~~~~~~ -Deletes an instance. +Deletes a network. It supports the ``dry-run`` argument. +Job result: -``/2/instances/[instance_name]/info`` -+++++++++++++++++++++++++++++++++++++++ +.. opcode_result:: OP_NETWORK_REMOVE -It supports the following commands: ``GET``. -``GET`` -~~~~~~~ +.. _rapi-res-networks-network_name-modify: -Requests detailed information about the instance. An optional parameter, -``static`` (bool), can be set to return only static information from the -configuration without querying the instance's nodes. The result will be -a job id. +``/2/networks/[network_name]/modify`` ++++++++++++++++++++++++++++++++++++++ +Modifies the parameters of a network. -``/2/instances/[instance_name]/reboot`` -+++++++++++++++++++++++++++++++++++++++ +.. rapi_resource_details:: /2/networks/[network_name]/modify -Reboots URI for an instance. -It supports the following commands: ``POST``. +.. _rapi-res-networks-network_name-modify+put: -``POST`` -~~~~~~~~ +``PUT`` +~~~~~~~ -Reboots the instance. +Returns a job ID. -The URI takes optional ``type=soft|hard|full`` and -``ignore_secondaries=0|1`` parameters. +Body parameters: -``type`` defines the reboot type. ``soft`` is just a normal reboot, -without terminating the hypervisor. ``hard`` means full shutdown -(including terminating the hypervisor process) and startup again. -``full`` is like ``hard`` but also recreates the configuration from -ground up as if you would have done a ``gnt-instance shutdown`` and -``gnt-instance start`` on it. +.. opcode_params:: OP_NETWORK_SET_PARAMS -``ignore_secondaries`` is a bool argument indicating if we start the -instance even if secondary disks are failing. +Job result: -It supports the ``dry-run`` argument. +.. opcode_result:: OP_NETWORK_SET_PARAMS -``/2/instances/[instance_name]/shutdown`` -+++++++++++++++++++++++++++++++++++++++++ +.. _rapi-res-networks-network_name-connect: -Instance shutdown URI. +``/2/networks/[network_name]/connect`` +++++++++++++++++++++++++++++++++++++++ + +Connects a network to a nodegroup. + +.. rapi_resource_details:: /2/networks/[network_name]/connect -It supports the following commands: ``PUT``. + +.. _rapi-res-networks-network_name-connect+put: ``PUT`` ~~~~~~~ -Shutdowns an instance. - -It supports the ``dry-run`` argument. +Returns a job ID. It supports the ``dry-run`` arguments. +Body parameters: -``/2/instances/[instance_name]/startup`` -++++++++++++++++++++++++++++++++++++++++ +.. opcode_params:: OP_NETWORK_CONNECT -Instance startup URI. +Job result: -It supports the following commands: ``PUT``. +.. opcode_result:: OP_NETWORK_CONNECT -``PUT`` -~~~~~~~ -Startup an instance. +.. _rapi-res-networks-network_name-disconnect: -The URI takes an optional ``force=1|0`` parameter to start the -instance even if secondary disks are failing. +``/2/networks/[network_name]/disconnect`` ++++++++++++++++++++++++++++++++++++++++++ -It supports the ``dry-run`` argument. +Disonnects a network from a nodegroup. -``/2/instances/[instance_name]/reinstall`` -++++++++++++++++++++++++++++++++++++++++++++++ +.. rapi_resource_details:: /2/networks/[network_name]/disconnect -Installs the operating system again. -It supports the following commands: ``POST``. +.. _rapi-res-networks-network_name-disconnect+put: -``POST`` -~~~~~~~~ +``PUT`` +~~~~~~~ -Returns a job ID. +Returns a job ID. It supports the ``dry-run`` arguments. Body parameters: -``os`` (string, required) - Instance operating system. -``start`` (bool, defaults to true) - Whether to start instance after reinstallation. -``osparams`` (dict) - Dictionary with (temporary) OS parameters. +.. opcode_params:: OP_NETWORK_DISCONNECT -For backwards compatbility, this resource also takes the query -parameters ``os`` (OS template name) and ``nostartup`` (bool). New -clients should use the body parameters. +Job result: +.. opcode_result:: OP_NETWORK_DISCONNECT -``/2/instances/[instance_name]/replace-disks`` -++++++++++++++++++++++++++++++++++++++++++++++ -Replaces disks on an instance. +.. _rapi-res-networks-network_name-tags: -It supports the following commands: ``POST``. +``/2/networks/[network_name]/tags`` ++++++++++++++++++++++++++++++++++++ -``POST`` -~~~~~~~~ +Manages per-network tags. -Takes the parameters ``mode`` (one of ``replace_on_primary``, -``replace_on_secondary``, ``replace_new_secondary`` or -``replace_auto``), ``disks`` (comma separated list of disk indexes), -``remote_node`` and ``iallocator``. +.. rapi_resource_details:: /2/networks/[network_name]/tags -Either ``remote_node`` or ``iallocator`` needs to be defined when using -``mode=replace_new_secondary``. -``mode`` is a mandatory parameter. ``replace_auto`` tries to determine -the broken disk(s) on its own and replacing it. +.. _rapi-res-networks-network_name-tags+get: +``GET`` +~~~~~~~ -``/2/instances/[instance_name]/activate-disks`` -+++++++++++++++++++++++++++++++++++++++++++++++ +Returns a list of tags. -Activate disks on an instance. +Example:: + + ["tag1", "tag2", "tag3"] -It supports the following commands: ``PUT``. + +.. _rapi-res-networks-network_name-tags+put: ``PUT`` ~~~~~~~ -Takes the bool parameter ``ignore_size``. When set ignore the recorded -size (useful for forcing activation when recorded size is wrong). +Add a set of tags. +The request as a list of strings should be ``PUT`` to this URI. The +result will be a job id. -``/2/instances/[instance_name]/deactivate-disks`` -+++++++++++++++++++++++++++++++++++++++++++++++++ +It supports the ``dry-run`` argument. -Deactivate disks on an instance. -It supports the following commands: ``PUT``. +.. _rapi-res-networks-network_name-tags+delete: -``PUT`` -~~~~~~~ +``DELETE`` +~~~~~~~~~~ + +Delete a tag. + +In order to delete a set of tags, the DELETE request should be addressed +to URI like:: + + /tags?tag=[tag]&tag=[tag] + +It supports the ``dry-run`` argument. + + +.. _rapi-res-instances-multi-alloc: + +``/2/instances-multi-alloc`` +++++++++++++++++++++++++++++ + +Tries to allocate multiple instances. + +.. rapi_resource_details:: /2/instances-multi-alloc + + +.. _rapi-res-instances-multi-alloc+post: + +``POST`` +~~~~~~~~ + +The parameters: + +.. opcode_params:: OP_INSTANCE_MULTI_ALLOC + +Job result: + +.. opcode_result:: OP_INSTANCE_MULTI_ALLOC + + +.. _rapi-res-instances: + +``/2/instances`` +++++++++++++++++ + +The instances resource. + +.. rapi_resource_details:: /2/instances + + +.. _rapi-res-instances+get: + +``GET`` +~~~~~~~ + +Returns a list of all available instances. + +Example:: + + [ + { + "name": "web.example.com", + "uri": "\/instances\/web.example.com" + }, + { + "name": "mail.example.com", + "uri": "\/instances\/mail.example.com" + } + ] + +If the optional bool *bulk* argument is provided and set to a true value +(i.e ``?bulk=1``), the output contains detailed information about +instances as a list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`. + +Example:: + + [ + { + "status": "running", + "disk_usage": 20480, + "nic.bridges": [ + "xen-br0" + ], + "name": "web.example.com", + "tags": ["tag1", "tag2"], + "beparams": { + "vcpus": 2, + "memory": 512 + }, + "disk.sizes": [ + 20480 + ], + "pnode": "node1.example.com", + "nic.macs": ["01:23:45:67:89:01"], + "snodes": ["node2.example.com"], + "disk_template": "drbd", + "admin_state": true, + "os": "debian-etch", + "oper_state": true, + … + }, + … + ] + + +.. _rapi-res-instances+post: + +``POST`` +~~~~~~~~ + +Creates an instance. + +If the optional bool *dry-run* argument is provided, the job will not be +actually executed, only the pre-execution checks will be done. Query-ing +the job result will return, in both dry-run and normal case, the list of +nodes selected for the instance. + +Returns: a job ID that can be used later for polling. + +Body parameters: + +``__version__`` (int, required) + Must be ``1`` (older Ganeti versions used a different format for + instance creation requests, version ``0``, but that format is no + longer supported) + +.. opcode_params:: OP_INSTANCE_CREATE + +Earlier versions used parameters named ``name`` and ``os``. These have +been replaced by ``instance_name`` and ``os_type`` to match the +underlying opcode. The old names can still be used. + +Job result: + +.. opcode_result:: OP_INSTANCE_CREATE + + +.. _rapi-res-instances-instance_name: + +``/2/instances/[instance_name]`` +++++++++++++++++++++++++++++++++ + +Instance-specific resource. + +.. rapi_resource_details:: /2/instances/[instance_name] + + +.. _rapi-res-instances-instance_name+get: + +``GET`` +~~~~~~~ + +Returns information about an instance, similar to the bulk output from +the instance list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`. + + +.. _rapi-res-instances-instance_name+delete: + +``DELETE`` +~~~~~~~~~~ + +Deletes an instance. + +It supports the ``dry-run`` argument. + +Job result: + +.. opcode_result:: OP_INSTANCE_REMOVE + + +.. _rapi-res-instances-instance_name-info: + +``/2/instances/[instance_name]/info`` ++++++++++++++++++++++++++++++++++++++++ + +.. rapi_resource_details:: /2/instances/[instance_name]/info + + +.. _rapi-res-instances-instance_name-info+get: + +``GET`` +~~~~~~~ + +Requests detailed information about the instance. An optional parameter, +``static`` (bool), can be set to return only static information from the +configuration without querying the instance's nodes. The result will be +a job id. + +Job result: + +.. opcode_result:: OP_INSTANCE_QUERY_DATA + + +.. _rapi-res-instances-instance_name-reboot: + +``/2/instances/[instance_name]/reboot`` ++++++++++++++++++++++++++++++++++++++++ + +Reboots URI for an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/reboot + + +.. _rapi-res-instances-instance_name-reboot+post: + +``POST`` +~~~~~~~~ + +Reboots the instance. + +The URI takes optional ``type=soft|hard|full`` and +``ignore_secondaries=0|1`` parameters. + +``type`` defines the reboot type. ``soft`` is just a normal reboot, +without terminating the hypervisor. ``hard`` means full shutdown +(including terminating the hypervisor process) and startup again. +``full`` is like ``hard`` but also recreates the configuration from +ground up as if you would have done a ``gnt-instance shutdown`` and +``gnt-instance start`` on it. + +``ignore_secondaries`` is a bool argument indicating if we start the +instance even if secondary disks are failing. + +It supports the ``dry-run`` argument. + +Job result: + +.. opcode_result:: OP_INSTANCE_REBOOT + + +.. _rapi-res-instances-instance_name-shutdown: + +``/2/instances/[instance_name]/shutdown`` ++++++++++++++++++++++++++++++++++++++++++ + +Instance shutdown URI. + +.. rapi_resource_details:: /2/instances/[instance_name]/shutdown + + +.. _rapi-res-instances-instance_name-shutdown+put: + +``PUT`` +~~~~~~~ + +Shutdowns an instance. + +It supports the ``dry-run`` argument. + +.. opcode_params:: OP_INSTANCE_SHUTDOWN + :exclude: instance_name, dry_run + +Job result: + +.. opcode_result:: OP_INSTANCE_SHUTDOWN + + +.. _rapi-res-instances-instance_name-startup: + +``/2/instances/[instance_name]/startup`` +++++++++++++++++++++++++++++++++++++++++ + +Instance startup URI. + +.. rapi_resource_details:: /2/instances/[instance_name]/startup + + +.. _rapi-res-instances-instance_name-startup+put: + +``PUT`` +~~~~~~~ + +Startup an instance. + +The URI takes an optional ``force=1|0`` parameter to start the +instance even if secondary disks are failing. + +It supports the ``dry-run`` argument. + +Job result: + +.. opcode_result:: OP_INSTANCE_STARTUP + + +.. _rapi-res-instances-instance_name-reinstall: + +``/2/instances/[instance_name]/reinstall`` +++++++++++++++++++++++++++++++++++++++++++++++ + +Installs the operating system again. + +.. rapi_resource_details:: /2/instances/[instance_name]/reinstall + + +.. _rapi-res-instances-instance_name-reinstall+post: + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +``os`` (string, required) + Instance operating system. +``start`` (bool, defaults to true) + Whether to start instance after reinstallation. +``osparams`` (dict) + Dictionary with (temporary) OS parameters. + +For backwards compatbility, this resource also takes the query +parameters ``os`` (OS template name) and ``nostartup`` (bool). New +clients should use the body parameters. + + +.. _rapi-res-instances-instance_name-replace-disks: + +``/2/instances/[instance_name]/replace-disks`` +++++++++++++++++++++++++++++++++++++++++++++++ + +Replaces disks on an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/replace-disks + + +.. _rapi-res-instances-instance_name-replace-disks+post: + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_REPLACE_DISKS + :exclude: instance_name + +Ganeti 2.4 and below used query parameters. Those are deprecated and +should no longer be used. + +Job result: + +.. opcode_result:: OP_INSTANCE_REPLACE_DISKS + + +.. _rapi-res-instances-instance_name-activate-disks: + +``/2/instances/[instance_name]/activate-disks`` ++++++++++++++++++++++++++++++++++++++++++++++++ + +Activate disks on an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/activate-disks + + +.. _rapi-res-instances-instance_name-activate-disks+put: + +``PUT`` +~~~~~~~ + +Takes the bool parameter ``ignore_size``. When set ignore the recorded +size (useful for forcing activation when recorded size is wrong). + +Job result: + +.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS + + +.. _rapi-res-instances-instance_name-deactivate-disks: + +``/2/instances/[instance_name]/deactivate-disks`` ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Deactivate disks on an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/deactivate-disks + + +.. _rapi-res-instances-instance_name-deactivate-disks+put: + +``PUT`` +~~~~~~~ Takes no parameters. +Job result: + +.. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS + + +.. _rapi-res-instances-instance_name-recreate-disks: + +``/2/instances/[instance_name]/recreate-disks`` ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Recreate disks of an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/recreate-disks + + +.. _rapi-res-instances-instance_name-recreate-disks+post: + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_RECREATE_DISKS + :exclude: instance_name + +Job result: + +.. opcode_result:: OP_INSTANCE_RECREATE_DISKS + + +.. _rapi-res-instances-instance_name-disk-disk_index-grow: ``/2/instances/[instance_name]/disk/[disk_index]/grow`` +++++++++++++++++++++++++++++++++++++++++++++++++++++++ Grows one disk of an instance. -Supports the following commands: ``POST``. +.. rapi_resource_details:: /2/instances/[instance_name]/disk/[disk_index]/grow + + +.. _rapi-res-instances-instance_name-disk-disk_index-grow+post: ``POST`` ~~~~~~~~ @@ -813,26 +1418,44 @@ Body parameters: .. opcode_params:: OP_INSTANCE_GROW_DISK :exclude: instance_name, disk +Job result: + +.. opcode_result:: OP_INSTANCE_GROW_DISK + + +.. _rapi-res-instances-instance_name-prepare-export: ``/2/instances/[instance_name]/prepare-export`` +++++++++++++++++++++++++++++++++++++++++++++++++ Prepares an export of an instance. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/prepare-export + + +.. _rapi-res-instances-instance_name-prepare-export+put: ``PUT`` ~~~~~~~ Takes one parameter, ``mode``, for the export mode. Returns a job ID. +Job result: + +.. opcode_result:: OP_BACKUP_PREPARE + + +.. _rapi-res-instances-instance_name-export: ``/2/instances/[instance_name]/export`` +++++++++++++++++++++++++++++++++++++++++++++++++ Exports an instance. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/export + + +.. _rapi-res-instances-instance_name-export+put: ``PUT`` ~~~~~~~ @@ -845,13 +1468,22 @@ Body parameters: :exclude: instance_name :alias: target_node=destination +Job result: + +.. opcode_result:: OP_BACKUP_EXPORT + + +.. _rapi-res-instances-instance_name-migrate: ``/2/instances/[instance_name]/migrate`` ++++++++++++++++++++++++++++++++++++++++ Migrates an instance. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/migrate + + +.. _rapi-res-instances-instance_name-migrate+put: ``PUT`` ~~~~~~~ @@ -863,13 +1495,49 @@ Body parameters: .. opcode_params:: OP_INSTANCE_MIGRATE :exclude: instance_name, live +Job result: + +.. opcode_result:: OP_INSTANCE_MIGRATE + + +.. _rapi-res-instances-instance_name-failover: + +``/2/instances/[instance_name]/failover`` ++++++++++++++++++++++++++++++++++++++++++ + +Does a failover of an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/failover + + +.. _rapi-res-instances-instance_name-failover+put: + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_INSTANCE_FAILOVER + :exclude: instance_name + +Job result: + +.. opcode_result:: OP_INSTANCE_FAILOVER + + +.. _rapi-res-instances-instance_name-rename: ``/2/instances/[instance_name]/rename`` ++++++++++++++++++++++++++++++++++++++++ Renames an instance. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/rename + + +.. _rapi-res-instances-instance_name-rename+put: ``PUT`` ~~~~~~~ @@ -878,20 +1546,25 @@ Returns a job ID. Body parameters: -``new_name`` (string, required) - New instance name. -``ip_check`` (bool) - Whether to ensure instance's IP address is inactive. -``name_check`` (bool) - Whether to ensure instance's name is resolvable. +.. opcode_params:: OP_INSTANCE_RENAME + :exclude: instance_name + +Job result: + +.. opcode_result:: OP_INSTANCE_RENAME +.. _rapi-res-instances-instance_name-modify: + ``/2/instances/[instance_name]/modify`` ++++++++++++++++++++++++++++++++++++++++ Modifies an instance. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/modify + + +.. _rapi-res-instances-instance_name-modify+put: ``PUT`` ~~~~~~~ @@ -903,13 +1576,85 @@ Body parameters: .. opcode_params:: OP_INSTANCE_SET_PARAMS :exclude: instance_name +Job result: + +.. opcode_result:: OP_INSTANCE_SET_PARAMS + + +.. _rapi-res-instances-instance_name-console: + +``/2/instances/[instance_name]/console`` +++++++++++++++++++++++++++++++++++++++++ + +Request information for connecting to instance's console. + +.. rapi_resource_details:: /2/instances/[instance_name]/console + + +.. _rapi-res-instances-instance_name-console+get: + +``GET`` +~~~~~~~ + +Returns a dictionary containing information about the instance's +console. Contained keys: + +.. pyassert:: + + constants.CONS_ALL == frozenset([ + constants.CONS_MESSAGE, + constants.CONS_SSH, + constants.CONS_VNC, + constants.CONS_SPICE, + ]) + +.. pyassert:: + + frozenset(objects.InstanceConsole.GetAllSlots()) == frozenset([ + "command", + "display", + "host", + "instance", + "kind", + "message", + "port", + "user", + ]) + + +``instance`` + Instance name +``kind`` + Console type, one of :pyeval:`constants.CONS_SSH`, + :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE` + or :pyeval:`constants.CONS_MESSAGE` +``message`` + Message to display (:pyeval:`constants.CONS_MESSAGE` type only) +``host`` + Host to connect to (:pyeval:`constants.CONS_SSH`, + :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only) +``port`` + TCP port to connect to (:pyeval:`constants.CONS_VNC` or + :pyeval:`constants.CONS_SPICE` only) +``user`` + Username to use (:pyeval:`constants.CONS_SSH` only) +``command`` + Command to execute on machine (:pyeval:`constants.CONS_SSH` only) +``display`` + VNC display number (:pyeval:`constants.CONS_VNC` only) + + +.. _rapi-res-instances-instance_name-tags: ``/2/instances/[instance_name]/tags`` +++++++++++++++++++++++++++++++++++++ Manages per-instance tags. -It supports the following commands: ``GET``, ``PUT``, ``DELETE``. +.. rapi_resource_details:: /2/instances/[instance_name]/tags + + +.. _rapi-res-instances-instance_name-tags+get: ``GET`` ~~~~~~~ @@ -920,6 +1665,9 @@ Example:: ["tag1", "tag2", "tag3"] + +.. _rapi-res-instances-instance_name-tags+put: + ``PUT`` ~~~~~~~ @@ -931,6 +1679,8 @@ result will be a job id. It supports the ``dry-run`` argument. +.. _rapi-res-instances-instance_name-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -944,12 +1694,17 @@ to URI like:: It supports the ``dry-run`` argument. +.. _rapi-res-jobs: + ``/2/jobs`` +++++++++++ The ``/2/jobs`` resource. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/jobs + + +.. _rapi-res-jobs+get: ``GET`` ~~~~~~~ @@ -958,20 +1713,32 @@ Returns a dictionary of jobs. Returns: a dictionary with jobs id and uri. +If the optional bool *bulk* argument is provided and set to a true value +(i.e. ``?bulk=1``), the output contains detailed information about jobs +as a list. + +Returned fields for bulk requests (unlike other bulk requests, these +fields are not the same as for per-job requests): +:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS_BULK))`. + + +.. _rapi-res-jobs-job_id: + ``/2/jobs/[job_id]`` ++++++++++++++++++++ - Individual job URI. -It supports the following commands: ``GET``, ``DELETE``. +.. rapi_resource_details:: /2/jobs/[job_id] + + +.. _rapi-res-jobs-job_id+get: ``GET`` ~~~~~~~ -Returns a job status. - -Returns: a dictionary with job parameters. +Returns a dictionary with job parameters, containing the fields +:pyeval:`utils.CommaJoin(sorted(rlib2.J_FIELDS))`. The result includes: @@ -999,42 +1766,53 @@ executing, so it's possible to retry the OpCode without side effects. But whether it make sense to retry depends on the error classification: -``resolver_error`` +.. pyassert:: + + errors.ECODE_ALL == set([errors.ECODE_RESOLVER, errors.ECODE_NORES, + errors.ECODE_INVAL, errors.ECODE_STATE, errors.ECODE_NOENT, + errors.ECODE_EXISTS, errors.ECODE_NOTUNIQUE, errors.ECODE_FAULT, + errors.ECODE_ENVIRON, errors.ECODE_TEMP_NORES]) + +:pyeval:`errors.ECODE_RESOLVER` Resolver errors. This usually means that a name doesn't exist in DNS, so if it's a case of slow DNS propagation the operation can be retried later. -``insufficient_resources`` +:pyeval:`errors.ECODE_NORES` Not enough resources (iallocator failure, disk space, memory, etc.). If the resources on the cluster increase, the operation might succeed. -``wrong_input`` +:pyeval:`errors.ECODE_TEMP_NORES` + Simliar to :pyeval:`errors.ECODE_NORES`, but indicating the operation + should be attempted again after some time. + +:pyeval:`errors.ECODE_INVAL` Wrong arguments (at syntax level). The operation will not ever be accepted unless the arguments change. -``wrong_state`` +:pyeval:`errors.ECODE_STATE` Wrong entity state. For example, live migration has been requested for a down instance, or instance creation on an offline node. The operation can be retried once the resource has changed state. -``unknown_entity`` +:pyeval:`errors.ECODE_NOENT` Entity not found. For example, information has been requested for an unknown instance. -``already_exists`` +:pyeval:`errors.ECODE_EXISTS` Entity already exists. For example, instance creation has been requested for an already-existing instance. -``resource_not_unique`` +:pyeval:`errors.ECODE_NOTUNIQUE` Resource not unique (e.g. MAC or IP duplication). -``internal_error`` +:pyeval:`errors.ECODE_FAULT` Internal cluster error. For example, a node is unreachable but not set offline, or the ganeti node daemons are not working, etc. A ``gnt-cluster verify`` should be run. -``environment_error`` +:pyeval:`errors.ECODE_ENVIRON` Environment error (e.g. node disk error). A ``gnt-cluster verify`` should be run. @@ -1042,15 +1820,24 @@ Note that in the above list, by entity we refer to a node or instance, while by a resource we refer to an instance's disk, or NIC, etc. +.. _rapi-res-jobs-job_id+delete: + ``DELETE`` ~~~~~~~~~~ Cancel a not-yet-started job. +.. _rapi-res-jobs-job_id-wait: + ``/2/jobs/[job_id]/wait`` +++++++++++++++++++++++++ +.. rapi_resource_details:: /2/jobs/[job_id]/wait + + +.. _rapi-res-jobs-job_id-wait+get: + ``GET`` ~~~~~~~ @@ -1058,25 +1845,30 @@ Waits for changes on a job. Takes the following body parameters in a dict: ``fields`` - The job fields on which to watch for changes. + The job fields on which to watch for changes ``previous_job_info`` - Previously received field values or None if not yet available. + Previously received field values or None if not yet available ``previous_log_serial`` Highest log serial number received so far or None if not yet - available. + available Returns None if no changes have been detected and a dict with two keys, ``job_info`` and ``log_entries`` otherwise. +.. _rapi-res-nodes: + ``/2/nodes`` ++++++++++++ Nodes resource. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/nodes + + +.. _rapi-res-nodes+get: ``GET`` ~~~~~~~ @@ -1096,9 +1888,11 @@ Example:: } ] -If the optional 'bulk' argument is provided and set to 'true' value (i.e -'?bulk=1'), the output contains detailed information about nodes as a -list. +If the optional bool *bulk* argument is provided and set to a true value +(i.e ``?bulk=1``), the output contains detailed information about nodes +as a list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`. Example:: @@ -1113,84 +1907,139 @@ Example:: "dtotal": 5246208, "sinst_cnt": 2, "dfree": 5171712, - "offline": false + "offline": false, + … }, - ... + … ] + +.. _rapi-res-nodes-node_name: + ``/2/nodes/[node_name]`` +++++++++++++++++++++++++++++++++ Returns information about a node. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/nodes/[node_name] + + +.. _rapi-res-nodes-node_name+get: + +``GET`` +~~~~~~~ + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`. + + + +.. _rapi-res-nodes-node_name-powercycle: + +``/2/nodes/[node_name]/powercycle`` ++++++++++++++++++++++++++++++++++++ + +Powercycles a node. + +.. rapi_resource_details:: /2/nodes/[node_name]/powercycle + + +.. _rapi-res-nodes-node_name-powercycle+post: + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Job result: + +.. opcode_result:: OP_NODE_POWERCYCLE + + +.. _rapi-res-nodes-node_name-evacuate: ``/2/nodes/[node_name]/evacuate`` +++++++++++++++++++++++++++++++++ -Evacuates all secondary instances off a node. +Evacuates instances off a node. + +.. rapi_resource_details:: /2/nodes/[node_name]/evacuate -It supports the following commands: ``POST``. + +.. _rapi-res-nodes-node_name-evacuate+post: ``POST`` ~~~~~~~~ -To evacuate a node, either one of the ``iallocator`` or ``remote_node`` -parameters must be passed:: +Returns a job ID. The result of the job will contain the IDs of the +individual jobs submitted to evacuate the node. + +Body parameters: + +.. opcode_params:: OP_NODE_EVACUATE + :exclude: nodes - evacuate?iallocator=[iallocator] - evacuate?remote_node=[nodeX.example.com] +Up to and including Ganeti 2.4 query arguments were used. Those are no +longer supported. The new request can be detected by the presence of the +:pyeval:`rlib2._NODE_EVAC_RES1` feature string. -The result value will be a list, each element being a triple of the job -id (for this specific evacuation), the instance which is being evacuated -by this job, and the node to which it is being relocated. In case the -node is already empty, the result will be an empty list (without any -jobs being submitted). +Job result: -And additional parameter ``early_release`` signifies whether to try to -parallelize the evacuations, at the risk of increasing I/O contention -and increasing the chances of data loss, if the primary node of any of -the instances being evacuated is not fully healthy. +.. opcode_result:: OP_NODE_EVACUATE -If the dry-run parameter was specified, then the evacuation jobs were -not actually submitted, and the job IDs will be null. +.. _rapi-res-nodes-node_name-migrate: ``/2/nodes/[node_name]/migrate`` +++++++++++++++++++++++++++++++++ Migrates all primary instances from a node. -It supports the following commands: ``POST``. +.. rapi_resource_details:: /2/nodes/[node_name]/migrate + + +.. _rapi-res-nodes-node_name-migrate+post: ``POST`` ~~~~~~~~ If no mode is explicitly specified, each instances' hypervisor default -migration mode will be used. Query parameters: +migration mode will be used. Body parameters: + +.. opcode_params:: OP_NODE_MIGRATE + :exclude: node_name + +The query arguments used up to and including Ganeti 2.4 are deprecated +and should no longer be used. The new request format can be detected by +the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string. -``live`` (bool) - If set, use live migration if available. -``mode`` (string) - Sets migration mode, ``live`` for live migration and ``non-live`` for - non-live migration. Supported by Ganeti 2.2 and above. +Job result: +.. opcode_result:: OP_NODE_MIGRATE + + +.. _rapi-res-nodes-node_name-role: ``/2/nodes/[node_name]/role`` +++++++++++++++++++++++++++++ Manages node role. -It supports the following commands: ``GET``, ``PUT``. +.. rapi_resource_details:: /2/nodes/[node_name]/role The role is always one of the following: - drained - - master - master-candidate - offline - regular +Note that the 'master' role is a special, and currently it can't be +modified via RAPI, only via the command line (``gnt-cluster +master-failover``). + + +.. _rapi-res-nodes-node_name-role+get: + ``GET`` ~~~~~~~ @@ -1200,6 +2049,9 @@ Example:: "master-candidate" + +.. _rapi-res-nodes-node_name-role+put: + ``PUT`` ~~~~~~~ @@ -1210,51 +2062,136 @@ be a job id. It supports the bool ``force`` argument. +Job result: + +.. opcode_result:: OP_NODE_SET_PARAMS + + +.. _rapi-res-nodes-node_name-modify: + +``/2/nodes/[node_name]/modify`` ++++++++++++++++++++++++++++++++ + +Modifies the parameters of a node. + +.. rapi_resource_details:: /2/nodes/[node_name]/modify + + +.. _rapi-res-nodes-node_name-modify+post: + +``POST`` +~~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_NODE_SET_PARAMS + :exclude: node_name + +Job result: + +.. opcode_result:: OP_NODE_SET_PARAMS + + +.. _rapi-res-nodes-node_name-storage: + ``/2/nodes/[node_name]/storage`` ++++++++++++++++++++++++++++++++ Manages storage units on the node. +.. rapi_resource_details:: /2/nodes/[node_name]/storage + + +.. _rapi-res-nodes-node_name-storage+get: + ``GET`` ~~~~~~~ +FIXME: enable ".. pyassert::" again when all storage types are +implemented:: + + constants.STORAGE_TYPES == set([constants.ST_FILE, + constants.ST_LVM_PV, + constants.ST_LVM_VG]) + Requests a list of storage units on a node. Requires the parameters -``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and +``storage_type`` (one of :pyeval:`constants.ST_FILE`, +:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and ``output_fields``. The result will be a job id, using which the result can be retrieved. + +.. _rapi-res-nodes-node_name-storage-modify: + ``/2/nodes/[node_name]/storage/modify`` +++++++++++++++++++++++++++++++++++++++ Modifies storage units on the node. +.. rapi_resource_details:: /2/nodes/[node_name]/storage/modify + + +.. _rapi-res-nodes-node_name-storage-modify+put: + ``PUT`` ~~~~~~~ Modifies parameters of storage units on the node. Requires the -parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) +parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`, +:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and ``name`` (name of the storage unit). Parameters can be passed -additionally. Currently only ``allocatable`` (bool) is supported. The -result will be a job id. +additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool) +is supported. The result will be a job id. + +Job result: + +.. opcode_result:: OP_NODE_MODIFY_STORAGE + + +.. _rapi-res-nodes-node_name-storage-repair: ``/2/nodes/[node_name]/storage/repair`` +++++++++++++++++++++++++++++++++++++++ Repairs a storage unit on the node. +.. rapi_resource_details:: /2/nodes/[node_name]/storage/repair + + +.. _rapi-res-nodes-node_name-storage-repair+put: + ``PUT`` ~~~~~~~ +.. pyassert:: + + constants.VALID_STORAGE_OPERATIONS == { + constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]), + } + Repairs a storage unit on the node. Requires the parameters -``storage_type`` (currently only ``lvm-vg`` can be repaired) and -``name`` (name of the storage unit). The result will be a job id. +``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be +repaired) and ``name`` (name of the storage unit). The result will be a +job id. + +Job result: + +.. opcode_result:: OP_REPAIR_NODE_STORAGE + + +.. _rapi-res-nodes-node_name-tags: ``/2/nodes/[node_name]/tags`` +++++++++++++++++++++++++++++ Manages per-node tags. -It supports the following commands: ``GET``, ``PUT``, ``DELETE``. +.. rapi_resource_details:: /2/nodes/[node_name]/tags + + +.. _rapi-res-nodes-node_name-tags+get: ``GET`` ~~~~~~~ @@ -1265,6 +2202,9 @@ Example:: ["tag1", "tag2", "tag3"] + +.. _rapi-res-nodes-node_name-tags+put: + ``PUT`` ~~~~~~~ @@ -1275,6 +2215,9 @@ will be a job id. It supports the ``dry-run`` argument. + +.. _rapi-res-nodes-node_name-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -1288,12 +2231,74 @@ to URI like:: It supports the ``dry-run`` argument. +.. _rapi-res-query-resource: + +``/2/query/[resource]`` ++++++++++++++++++++++++ + +Requests resource information. Available fields can be found in man +pages and using ``/2/query/[resource]/fields``. The resource is one of +:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2 +design document ` for more details. + +.. rapi_resource_details:: /2/query/[resource] + + +.. _rapi-res-query-resource+get: + +``GET`` +~~~~~~~ + +Returns list of included fields and actual data. Takes a query parameter +named "fields", containing a comma-separated list of field names. Does +not support filtering. + + +.. _rapi-res-query-resource+put: + +``PUT`` +~~~~~~~ + +Returns list of included fields and actual data. The list of requested +fields can either be given as the query parameter "fields" or as a body +parameter with the same name. The optional body parameter "filter" can +be given and must be either ``null`` or a list containing filter +operators. + + +.. _rapi-res-query-resource-fields: + +``/2/query/[resource]/fields`` +++++++++++++++++++++++++++++++ + +Request list of available fields for a resource. The resource is one of +:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the +:doc:`query2 design document ` for more details. + +.. rapi_resource_details:: /2/query/[resource]/fields + + +.. _rapi-res-query-resource-fields+get: + +``GET`` +~~~~~~~ + +Returns a list of field descriptions for available fields. Takes an +optional query parameter named "fields", containing a comma-separated +list of field names. + + +.. _rapi-res-os: + ``/2/os`` +++++++++ OS resource. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/os + + +.. _rapi-res-os+get: ``GET`` ~~~~~~~ @@ -1307,12 +2312,18 @@ Example:: ["debian-etch"] + +.. _rapi-res-tags: + ``/2/tags`` +++++++++++ Manages cluster tags. -It supports the following commands: ``GET``, ``PUT``, ``DELETE``. +.. rapi_resource_details:: /2/tags + + +.. _rapi-res-tags+get: ``GET`` ~~~~~~~ @@ -1323,6 +2334,9 @@ Example:: ["tag1", "tag2", "tag3"] + +.. _rapi-res-tags+put: + ``PUT`` ~~~~~~~ @@ -1334,6 +2348,8 @@ will be a job id. It supports the ``dry-run`` argument. +.. _rapi-res-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -1347,6 +2363,8 @@ to URI like:: It supports the ``dry-run`` argument. +.. _rapi-res-version: + ``/version`` ++++++++++++ @@ -1355,7 +2373,10 @@ The version resource. This resource should be used to determine the remote API version and to adapt clients accordingly. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /version + + +.. _rapi-res-version+get: ``GET`` ~~~~~~~ @@ -1363,6 +2384,18 @@ It supports the following commands: ``GET``. Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0 returns ``2``. + +.. _rapi-access-permissions: + +Access permissions +------------------ + +The following list describes the access permissions required for each +resource. See :ref:`rapi-users` for more details. + +.. rapi_access_table:: + + .. vim: set textwidth=72 : .. Local Variables: .. mode: rst