which is used by default, can also be disabled by passing command line
parameters.
+.. _rapi-users:
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
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 <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.
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.
+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, but useful for account 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`
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
++++++
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``
~~~~~~~
rlib2._NODE_EVAC_RES1])
:pyeval:`rlib2._INST_CREATE_REQV1`
- Instance creation request data version 1 supported.
+ Instance creation request data version 1 supported
:pyeval:`rlib2._INST_REINSTALL_REQV1`
- Instance reinstall supports body parameters.
+ Instance reinstall supports body parameters
:pyeval:`rlib2._NODE_MIGRATE_REQV1`
Whether migrating a node (``/2/nodes/[node_name]/migrate``) supports
- request body parameters.
+ 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``
~~~~~~~
.. 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``
~~~~~~~
(i.e ``?bulk=1``), the output contains detailed information about node
groups as a list.
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.G_FIELDS))`.
Example::
"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``
~~~~~~~
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))`
+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``
~~~~~~~
["tag1", "tag2", "tag3"]
+.. _rapi-res-groups-group_name-tags+put:
+
``PUT``
~~~~~~~
It supports the ``dry-run`` argument.
+.. _rapi-res-groups-group_name-tags+delete:
+
``DELETE``
~~~~~~~~~~
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.
+
+.. 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.
-It supports the following commands: ``GET``, ``POST``.
+.. rapi_resource_details:: /2/instances
+
+
+.. _rapi-res-instances+get:
``GET``
~~~~~~~
(i.e ``?bulk=1``), the output contains detailed information about
instances as a list.
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
+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
+ "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``
~~~~~~~
Returns information about an instance, similar to the bulk output from
the instance list.
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.I_FIELDS))`
+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.
-Supports the following commands: ``GET``.
+.. rapi_resource_details:: /2/instances/[instance_name]/console
+
+
+.. _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.
+ Instance name
``kind``
Console type, one of :pyeval:`constants.CONS_SSH`,
:pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
- or :pyeval:`constants.CONS_MESSAGE`.
+ or :pyeval:`constants.CONS_MESSAGE`
``message``
- Message to display (:pyeval:`constants.CONS_MESSAGE` type only).
+ 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).
+ :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).
+ :pyeval:`constants.CONS_SPICE` only)
``user``
- Username to use (:pyeval:`constants.CONS_SSH` only).
+ 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).
+ 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``
~~~~~~~
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))`
+: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``
~~~~~~~
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``
~~~~~~~
(i.e ``?bulk=1``), the output contains detailed information about nodes
as a list.
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
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]
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
+
+.. _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.
-Supports the following commands: ``GET``, ``PUT``.
+.. rapi_resource_details:: /2/query/[resource]
+
+
+.. _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