X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/e1ff0de14999f459d5e8d6402806febc29889d10..1ec34e2636440202e89707cb896545a9e62f63e0:/doc/rapi.rst diff --git a/doc/rapi.rst b/doc/rapi.rst index c46051a..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,6 +84,20 @@ 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 @@ -181,8 +228,7 @@ The instance policy specification is a dict with the following fields: .. pyassert:: - constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN, - constants.ISPECS_MAX, + constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MINMAX, constants.ISPECS_STD, constants.IPOLICY_DTS, constants.IPOLICY_VCPU_RATIO, @@ -204,24 +250,30 @@ The instance policy specification is a dict with the following fields: .. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD` -|ispec-min|, |ispec-max|, |ispec-std| - A sub- `dict` with the following fields, which sets the limit and standard - values 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 +: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` @@ -245,14 +297,19 @@ Shell .. highlight:: shell-example -Using wget:: +Using ``wget``:: $ wget -q -O - https://%CLUSTERNAME%:5080/2/info -or curl:: +or ``curl``:: $ 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 ++++++ @@ -310,12 +367,17 @@ method is supported. Has no function, but for legacy reasons the ``GET`` method is supported. +.. _rapi-res-info: + ``/2/info`` +++++++++++ Cluster information resource. -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/info + + +.. _rapi-res-info+get: ``GET`` ~~~~~~~ @@ -350,16 +412,22 @@ 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`` ~~~~~~~ @@ -371,9 +439,16 @@ Job result: .. opcode_result:: OP_CLUSTER_REDIST_CONF +.. _rapi-res-features: + ``/2/features`` +++++++++++++++ +.. rapi_resource_details:: /2/features + + +.. _rapi-res-features+get: + ``GET`` ~~~~~~~ @@ -399,12 +474,17 @@ features: 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`` ~~~~~~~ @@ -420,12 +500,17 @@ 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`` ~~~~~~~ @@ -461,7 +546,8 @@ Example:: "node1.example.com", "node2.example.com" ], - "uuid": "0d7d407c-262e-49af-881a-6a430034bf43" + "uuid": "0d7d407c-262e-49af-881a-6a430034bf43", + … }, { "name": "group2", @@ -469,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`` ~~~~~~~~ @@ -495,12 +586,17 @@ 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`` ~~~~~~~ @@ -510,6 +606,8 @@ the node group list. Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`. +.. _rapi-res-groups-group_name+delete: + ``DELETE`` ~~~~~~~~~~ @@ -522,12 +620,17 @@ 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`` ~~~~~~~ @@ -544,12 +647,17 @@ 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`` ~~~~~~~ @@ -566,12 +674,16 @@ 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`` ~~~~~~~ @@ -587,13 +699,17 @@ Job result: .. opcode_result:: OP_GROUP_ASSIGN_NODES +.. _rapi-res-groups-group_name-tags: ``/2/groups/[group_name]/tags`` +++++++++++++++++++++++++++++++ Manages per-nodegroup tags. -Supports the following commands: ``GET``, ``PUT``, ``DELETE``. +.. rapi_resource_details:: /2/groups/[group_name]/tags + + +.. _rapi-res-groups-group_name-tags+get: ``GET`` ~~~~~~~ @@ -604,6 +720,8 @@ Example:: ["tag1", "tag2", "tag3"] +.. _rapi-res-groups-group_name-tags+put: + ``PUT`` ~~~~~~~ @@ -615,6 +733,8 @@ result will be a job id. It supports the ``dry-run`` argument. +.. _rapi-res-groups-group_name-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -628,12 +748,260 @@ to URI like:: 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": "network1", + "uri": "\/2\/networks\/network1" + }, + { + "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 networks +as a list. + +Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`. + +Example:: + + [ + { + '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 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. + +Returns: a job ID that can be used later for polling. + +Body parameters: + +.. opcode_params:: OP_NETWORK_ADD + +Job result: + +.. opcode_result:: OP_NETWORK_ADD + + +.. _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 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 a network. + +It supports the ``dry-run`` argument. + +Job result: + +.. opcode_result:: OP_NETWORK_REMOVE + + +.. _rapi-res-networks-network_name-modify: + +``/2/networks/[network_name]/modify`` ++++++++++++++++++++++++++++++++++++++ + +Modifies the parameters of a network. + +.. rapi_resource_details:: /2/networks/[network_name]/modify + + +.. _rapi-res-networks-network_name-modify+put: + +``PUT`` +~~~~~~~ + +Returns a job ID. + +Body parameters: + +.. opcode_params:: OP_NETWORK_SET_PARAMS + +Job result: + +.. opcode_result:: OP_NETWORK_SET_PARAMS + + +.. _rapi-res-networks-network_name-connect: + +``/2/networks/[network_name]/connect`` +++++++++++++++++++++++++++++++++++++++ + +Connects a network to a nodegroup. + +.. rapi_resource_details:: /2/networks/[network_name]/connect + + +.. _rapi-res-networks-network_name-connect+put: + +``PUT`` +~~~~~~~ + +Returns a job ID. It supports the ``dry-run`` arguments. + +Body parameters: + +.. opcode_params:: OP_NETWORK_CONNECT + +Job result: + +.. opcode_result:: OP_NETWORK_CONNECT + + +.. _rapi-res-networks-network_name-disconnect: + +``/2/networks/[network_name]/disconnect`` ++++++++++++++++++++++++++++++++++++++++++ + +Disonnects a network from a nodegroup. + +.. rapi_resource_details:: /2/networks/[network_name]/disconnect + + +.. _rapi-res-networks-network_name-disconnect+put: + +``PUT`` +~~~~~~~ + +Returns a job ID. It supports the ``dry-run`` arguments. + +Body parameters: + +.. opcode_params:: OP_NETWORK_DISCONNECT + +Job result: + +.. opcode_result:: OP_NETWORK_DISCONNECT + + +.. _rapi-res-networks-network_name-tags: + +``/2/networks/[network_name]/tags`` ++++++++++++++++++++++++++++++++++++ + +Manages per-network tags. + +.. rapi_resource_details:: /2/networks/[network_name]/tags + + +.. _rapi-res-networks-network_name-tags+get: + +``GET`` +~~~~~~~ + +Returns a list of tags. + +Example:: + + ["tag1", "tag2", "tag3"] + + +.. _rapi-res-networks-network_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-networks-network_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-instances-multi-alloc: + ``/2/instances-multi-alloc`` ++++++++++++++++++++++++++++ Tries to allocate multiple instances. -It supports the following commands: ``POST`` +.. rapi_resource_details:: /2/instances-multi-alloc + + +.. _rapi-res-instances-multi-alloc+post: ``POST`` ~~~~~~~~ @@ -647,12 +1015,17 @@ Job result: .. opcode_result:: OP_INSTANCE_MULTI_ALLOC +.. _rapi-res-instances: + ``/2/instances`` ++++++++++++++++ The instances resource. -It supports the following commands: ``GET``, ``POST``. +.. rapi_resource_details:: /2/instances + + +.. _rapi-res-instances+get: ``GET`` ~~~~~~~ @@ -682,32 +1055,35 @@ 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 + "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`` ~~~~~~~~ @@ -738,12 +1114,17 @@ Job result: .. opcode_result:: OP_INSTANCE_CREATE +.. _rapi-res-instances-instance_name: + ``/2/instances/[instance_name]`` ++++++++++++++++++++++++++++++++ Instance-specific resource. -It supports the following commands: ``GET``, ``DELETE``. +.. rapi_resource_details:: /2/instances/[instance_name] + + +.. _rapi-res-instances-instance_name+get: ``GET`` ~~~~~~~ @@ -753,6 +1134,9 @@ the instance list. Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`. + +.. _rapi-res-instances-instance_name+delete: + ``DELETE`` ~~~~~~~~~~ @@ -765,10 +1149,15 @@ Job result: .. opcode_result:: OP_INSTANCE_REMOVE +.. _rapi-res-instances-instance_name-info: + ``/2/instances/[instance_name]/info`` +++++++++++++++++++++++++++++++++++++++ -It supports the following commands: ``GET``. +.. rapi_resource_details:: /2/instances/[instance_name]/info + + +.. _rapi-res-instances-instance_name-info+get: ``GET`` ~~~~~~~ @@ -783,12 +1172,17 @@ Job result: .. opcode_result:: OP_INSTANCE_QUERY_DATA +.. _rapi-res-instances-instance_name-reboot: + ``/2/instances/[instance_name]/reboot`` +++++++++++++++++++++++++++++++++++++++ Reboots URI for an instance. -It supports the following commands: ``POST``. +.. rapi_resource_details:: /2/instances/[instance_name]/reboot + + +.. _rapi-res-instances-instance_name-reboot+post: ``POST`` ~~~~~~~~ @@ -815,12 +1209,17 @@ Job result: .. opcode_result:: OP_INSTANCE_REBOOT +.. _rapi-res-instances-instance_name-shutdown: + ``/2/instances/[instance_name]/shutdown`` +++++++++++++++++++++++++++++++++++++++++ Instance shutdown URI. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/shutdown + + +.. _rapi-res-instances-instance_name-shutdown+put: ``PUT`` ~~~~~~~ @@ -837,12 +1236,17 @@ Job result: .. opcode_result:: OP_INSTANCE_SHUTDOWN +.. _rapi-res-instances-instance_name-startup: + ``/2/instances/[instance_name]/startup`` ++++++++++++++++++++++++++++++++++++++++ Instance startup URI. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/startup + + +.. _rapi-res-instances-instance_name-startup+put: ``PUT`` ~~~~~~~ @@ -859,12 +1263,17 @@ Job result: .. opcode_result:: OP_INSTANCE_STARTUP +.. _rapi-res-instances-instance_name-reinstall: + ``/2/instances/[instance_name]/reinstall`` ++++++++++++++++++++++++++++++++++++++++++++++ Installs the operating system again. -It supports the following commands: ``POST``. +.. rapi_resource_details:: /2/instances/[instance_name]/reinstall + + +.. _rapi-res-instances-instance_name-reinstall+post: ``POST`` ~~~~~~~~ @@ -885,12 +1294,17 @@ 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. -It supports the following commands: ``POST``. +.. rapi_resource_details:: /2/instances/[instance_name]/replace-disks + + +.. _rapi-res-instances-instance_name-replace-disks+post: ``POST`` ~~~~~~~~ @@ -910,12 +1324,17 @@ 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. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/activate-disks + + +.. _rapi-res-instances-instance_name-activate-disks+put: ``PUT`` ~~~~~~~ @@ -928,12 +1347,17 @@ 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. -It supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/deactivate-disks + + +.. _rapi-res-instances-instance_name-deactivate-disks+put: ``PUT`` ~~~~~~~ @@ -945,11 +1369,17 @@ 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. Supports the following commands: -``POST``. +Recreate disks of an instance. + +.. rapi_resource_details:: /2/instances/[instance_name]/recreate-disks + + +.. _rapi-res-instances-instance_name-recreate-disks+post: ``POST`` ~~~~~~~~ @@ -966,12 +1396,17 @@ 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`` ~~~~~~~~ @@ -988,12 +1423,17 @@ 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`` ~~~~~~~ @@ -1005,12 +1445,17 @@ 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`` ~~~~~~~ @@ -1028,12 +1473,17 @@ 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`` ~~~~~~~ @@ -1050,12 +1500,17 @@ Job result: .. opcode_result:: OP_INSTANCE_MIGRATE +.. _rapi-res-instances-instance_name-failover: + ``/2/instances/[instance_name]/failover`` +++++++++++++++++++++++++++++++++++++++++ Does a failover of an instance. -Supports the following commands: ``PUT``. +.. rapi_resource_details:: /2/instances/[instance_name]/failover + + +.. _rapi-res-instances-instance_name-failover+put: ``PUT`` ~~~~~~~ @@ -1072,12 +1527,17 @@ 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`` ~~~~~~~ @@ -1094,12 +1554,17 @@ 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`` ~~~~~~~ @@ -1116,12 +1581,17 @@ 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. -Supports the following commands: ``GET``. +.. rapi_resource_details:: /2/instances/[instance_name]/console + + +.. _rapi-res-instances-instance_name-console+get: ``GET`` ~~~~~~~ @@ -1138,6 +1608,20 @@ console. Contained keys: constants.CONS_SPICE, ]) +.. pyassert:: + + frozenset(objects.InstanceConsole.GetAllSlots()) == frozenset([ + "command", + "display", + "host", + "instance", + "kind", + "message", + "port", + "user", + ]) + + ``instance`` Instance name ``kind`` @@ -1160,12 +1644,17 @@ console. Contained keys: 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`` ~~~~~~~ @@ -1176,6 +1665,9 @@ Example:: ["tag1", "tag2", "tag3"] + +.. _rapi-res-instances-instance_name-tags+put: + ``PUT`` ~~~~~~~ @@ -1187,6 +1679,8 @@ result will be a job id. It supports the ``dry-run`` argument. +.. _rapi-res-instances-instance_name-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -1200,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`` ~~~~~~~ @@ -1222,13 +1721,18 @@ 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`` ~~~~~~~ @@ -1267,7 +1771,7 @@ classification: 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_ENVIRON, errors.ECODE_TEMP_NORES]) :pyeval:`errors.ECODE_RESOLVER` Resolver errors. This usually means that a name doesn't exist in DNS, @@ -1279,6 +1783,10 @@ classification: etc.). If the resources on the cluster increase, the operation might succeed. +: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. @@ -1312,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`` ~~~~~~~ @@ -1341,12 +1858,17 @@ 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`` ~~~~~~~ @@ -1385,24 +1907,43 @@ 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. Supports the following commands: ``POST``. +Powercycles a node. + +.. rapi_resource_details:: /2/nodes/[node_name]/powercycle + + +.. _rapi-res-nodes-node_name-powercycle+post: ``POST`` ~~~~~~~~ @@ -1414,12 +1955,17 @@ Job result: .. opcode_result:: OP_NODE_POWERCYCLE +.. _rapi-res-nodes-node_name-evacuate: + ``/2/nodes/[node_name]/evacuate`` +++++++++++++++++++++++++++++++++ Evacuates instances off a node. -It supports the following commands: ``POST``. +.. rapi_resource_details:: /2/nodes/[node_name]/evacuate + + +.. _rapi-res-nodes-node_name-evacuate+post: ``POST`` ~~~~~~~~ @@ -1441,12 +1987,17 @@ Job result: .. opcode_result:: OP_NODE_EVACUATE +.. _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`` ~~~~~~~~ @@ -1466,12 +2017,14 @@ 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: @@ -1484,6 +2037,9 @@ 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`` ~~~~~~~ @@ -1493,6 +2049,9 @@ Example:: "master-candidate" + +.. _rapi-res-nodes-node_name-role+put: + ``PUT`` ~~~~~~~ @@ -1508,11 +2067,17 @@ 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. Supports the following commands: -``POST``. +Modifies the parameters of a node. + +.. rapi_resource_details:: /2/nodes/[node_name]/modify + + +.. _rapi-res-nodes-node_name-modify+post: ``POST`` ~~~~~~~~ @@ -1529,19 +2094,27 @@ 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`` ~~~~~~~ -.. pyassert:: +FIXME: enable ".. pyassert::" again when all storage types are +implemented:: - constants.VALID_STORAGE_TYPES == set([constants.ST_FILE, - constants.ST_LVM_PV, - constants.ST_LVM_VG]) + 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 :pyeval:`constants.ST_FILE`, @@ -1549,11 +2122,19 @@ Requests a list of storage units on a node. Requires the parameters ``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`` ~~~~~~~ @@ -1569,11 +2150,18 @@ 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`` ~~~~~~~ @@ -1593,12 +2181,17 @@ 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`` ~~~~~~~ @@ -1609,6 +2202,9 @@ Example:: ["tag1", "tag2", "tag3"] + +.. _rapi-res-nodes-node_name-tags+put: + ``PUT`` ~~~~~~~ @@ -1619,6 +2215,9 @@ will be a job id. It supports the ``dry-run`` argument. + +.. _rapi-res-nodes-node_name-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -1632,6 +2231,8 @@ to URI like:: It supports the ``dry-run`` argument. +.. _rapi-res-query-resource: + ``/2/query/[resource]`` +++++++++++++++++++++++ @@ -1640,7 +2241,10 @@ 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. -Supports the following commands: ``GET``, ``PUT``. +.. rapi_resource_details:: /2/query/[resource] + + +.. _rapi-res-query-resource+get: ``GET`` ~~~~~~~ @@ -1649,6 +2253,9 @@ 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`` ~~~~~~~ @@ -1659,6 +2266,8 @@ be given and must be either ``null`` or a list containing filter operators. +.. _rapi-res-query-resource-fields: + ``/2/query/[resource]/fields`` ++++++++++++++++++++++++++++++ @@ -1666,7 +2275,10 @@ 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. -Supports the following commands: ``GET``. +.. rapi_resource_details:: /2/query/[resource]/fields + + +.. _rapi-res-query-resource-fields+get: ``GET`` ~~~~~~~ @@ -1676,12 +2288,17 @@ 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`` ~~~~~~~ @@ -1695,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`` ~~~~~~~ @@ -1711,6 +2334,9 @@ Example:: ["tag1", "tag2", "tag3"] + +.. _rapi-res-tags+put: + ``PUT`` ~~~~~~~ @@ -1722,6 +2348,8 @@ will be a job id. It supports the ``dry-run`` argument. +.. _rapi-res-tags+delete: + ``DELETE`` ~~~~~~~~~~ @@ -1735,6 +2363,8 @@ to URI like:: It supports the ``dry-run`` argument. +.. _rapi-res-version: + ``/version`` ++++++++++++ @@ -1743,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`` ~~~~~~~ @@ -1751,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