which is used by default, can also be disabled by passing command line
parameters.
+.. _rapi-users:
Users and passwords
-------------------
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). Available options:
+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
+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 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_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.
+ :pyeval:`rapi.RAPI_ACCESS_READ` access. Resources blocking other
+ operations for read-only access, such as
+ :ref:`/2/nodes/[node_name]/storage <rapi-res-nodes-node_name-storage+get>`
+ or blocking server-side processes, such as
+ :ref:`/2/jobs/[job_id]/wait <rapi-res-jobs-job_id-wait+get>`, 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.
-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
-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.
-
Example::
# Give Jack and Fred read-only access
jessica {HA1}7046452df2cbb530877058712cf17bd4 write
# Monitoring can query for values
- monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c query
+ monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c read
- # A user who can query and write
- superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c query,write
+ # 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.
+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
.. 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,
.. |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`
.. 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
++++++
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``
~~~~~~~
"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``
~~~~~~~
.. opcode_result:: OP_CLUSTER_REDIST_CONF
+.. _rapi-res-features:
+
``/2/features``
+++++++++++++++
+.. rapi_resource_details:: /2/features
+
+
+.. _rapi-res-features+get:
+
``GET``
~~~~~~~
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``
~~~~~~~
.. 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``
~~~~~~~
"node1.example.com",
"node2.example.com"
],
- "uuid": "0d7d407c-262e-49af-881a-6a430034bf43"
+ "uuid": "0d7d407c-262e-49af-881a-6a430034bf43",
+ …
},
{
"name": "group2",
"node_list": [
"node3.example.com"
],
- "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c"
- }
+ "uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c",
+ …
+ },
+ …
]
+
+.. _rapi-res-groups+post:
+
``POST``
~~~~~~~~
.. 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``
~~~~~~~
Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
+.. _rapi-res-groups-group_name+delete:
+
``DELETE``
~~~~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
+~~~~~~~
+
+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": "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``
~~~~~~~
["tag1", "tag2", "tag3"]
+
+.. _rapi-res-networks-network_name-tags+put:
+
``PUT``
~~~~~~~
It supports the ``dry-run`` argument.
+.. _rapi-res-networks-network_name-tags+delete:
+
``DELETE``
~~~~~~~~~~
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``
~~~~~~~~
.. 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``
~~~~~~~
[
{
- "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``
~~~~~~~~
.. 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``
~~~~~~~
Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`.
+
+.. _rapi-res-instances-instance_name+delete:
+
``DELETE``
~~~~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~~
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``
~~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~~
.. 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``
~~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
.. 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.
-.. pyassert::
+.. rapi_resource_details:: /2/instances/[instance_name]/console
- not (hasattr(rlib2.R_2_instances_name_console, "PUT") or
- hasattr(rlib2.R_2_instances_name_console, "POST") or
- hasattr(rlib2.R_2_instances_name_console, "DELETE"))
-Supports the following commands: ``GET``. Requires authentication with
-one of the following options:
-:pyeval:`utils.CommaJoin(rlib2.R_2_instances_name_console.GET_ACCESS)`.
+.. _rapi-res-instances-instance_name-console+get:
``GET``
~~~~~~~
constants.CONS_SPICE,
])
+.. pyassert::
+
+ frozenset(objects.InstanceConsole.GetAllSlots()) == frozenset([
+ "command",
+ "display",
+ "host",
+ "instance",
+ "kind",
+ "message",
+ "port",
+ "user",
+ ])
+
+
``instance``
Instance name
``kind``
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``
~~~~~~~
["tag1", "tag2", "tag3"]
+
+.. _rapi-res-instances-instance_name-tags+put:
+
``PUT``
~~~~~~~
It supports the ``dry-run`` argument.
+.. _rapi-res-instances-instance_name-tags+delete:
+
``DELETE``
~~~~~~~~~~
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``
~~~~~~~
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``
~~~~~~~
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,
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.
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``
~~~~~~~
``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``
~~~~~~~
"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``
~~~~~~~~
.. 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``
~~~~~~~~
.. 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``
~~~~~~~~
.. 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:
modified via RAPI, only via the command line (``gnt-cluster
master-failover``).
+
+.. _rapi-res-nodes-node_name-role+get:
+
``GET``
~~~~~~~
"master-candidate"
+
+.. _rapi-res-nodes-node_name-role+put:
+
``PUT``
~~~~~~~
.. 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``
~~~~~~~~
.. 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,
``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``
~~~~~~~
.. 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``
~~~~~~~
.. 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``
~~~~~~~
["tag1", "tag2", "tag3"]
+
+.. _rapi-res-nodes-node_name-tags+put:
+
``PUT``
~~~~~~~
It supports the ``dry-run`` argument.
+
+.. _rapi-res-nodes-node_name-tags+delete:
+
``DELETE``
~~~~~~~~~~
It supports the ``dry-run`` argument.
+.. _rapi-res-query-resource:
+
``/2/query/[resource]``
+++++++++++++++++++++++
:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
design document <design-query2>` for more details.
-.. pyassert::
+.. rapi_resource_details:: /2/query/[resource]
- (rlib2.R_2_query.GET_ACCESS == rlib2.R_2_query.PUT_ACCESS and
- not (hasattr(rlib2.R_2_query, "POST") or
- hasattr(rlib2.R_2_query, "DELETE")))
-Supports the following commands: ``GET``, ``PUT``. Requires
-authentication with one of the following options:
-:pyeval:`utils.CommaJoin(rlib2.R_2_query.GET_ACCESS)`.
+.. _rapi-res-query-resource+get:
``GET``
~~~~~~~
named "fields", containing a comma-separated list of field names. Does
not support filtering.
+
+.. _rapi-res-query-resource+put:
+
``PUT``
~~~~~~~
operators.
+.. _rapi-res-query-resource-fields:
+
``/2/query/[resource]/fields``
++++++++++++++++++++++++++++++
:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the
:doc:`query2 design document <design-query2>` for more details.
-Supports the following commands: ``GET``.
+.. rapi_resource_details:: /2/query/[resource]/fields
+
+
+.. _rapi-res-query-resource-fields+get:
``GET``
~~~~~~~
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``
~~~~~~~
["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``
~~~~~~~
["tag1", "tag2", "tag3"]
+
+.. _rapi-res-tags+put:
+
``PUT``
~~~~~~~
It supports the ``dry-run`` argument.
+.. _rapi-res-tags+delete:
+
``DELETE``
~~~~~~~~~~
It supports the ``dry-run`` argument.
+.. _rapi-res-version:
+
``/version``
++++++++++++
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``
~~~~~~~
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