``/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). Available options:
+
+.. pyassert::
+
+ rapi.RAPI_ACCESS_ALL == set([
+ rapi.RAPI_ACCESS_WRITE,
+ rapi.RAPI_ACCESS_READ,
+ ])
+
+: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`
+ 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
# Hashed password for Jessica
jessica {HA1}7046452df2cbb530877058712cf17bd4 write
+ # Monitoring can query for values
+ monitoring {HA1}ec018ffe72b8e75bb4d508ed5b6d079c query
+
+ # A user who can query and write
+ superuser {HA1}ec018ffe72b8e75bb4d508ed5b6d079c query,write
+
.. [#pwhash] Using the MD5 hash of username, realm and password is
described in :rfc:`2617` ("HTTP Authentication"), sections 3.2.2.2
Force operation to continue even if it will cause the cluster to become
inconsistent (e.g. because there are not enough master candidates).
+Parameter details
+-----------------
+
+Some parameters are not straight forward, so we describe them in details
+here.
+
+.. _rapi-ipolicy:
+
+``ipolicy``
++++++++++++
+
+The instance policy specification is a dict with the following fields:
+
+.. pyassert::
+
+ constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN,
+ constants.ISPECS_MAX,
+ constants.ISPECS_STD,
+ constants.IPOLICY_DTS,
+ constants.IPOLICY_VCPU_RATIO,
+ constants.IPOLICY_SPINDLE_RATIO])
+
+
+.. pyassert::
+
+ (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
+ set([constants.ISPEC_MEM_SIZE,
+ constants.ISPEC_DISK_SIZE,
+ constants.ISPEC_DISK_COUNT,
+ constants.ISPEC_CPU_COUNT,
+ constants.ISPEC_NIC_COUNT,
+ constants.ISPEC_SPINDLE_USE]))
+
+.. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
+.. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
+.. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
+
+
+|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.IPOLICY_DTS`
+ A `list` of disk templates allowed for instances using this policy
+:pyeval:`constants.IPOLICY_VCPU_RATIO`
+ Maximum ratio of virtual to physical CPUs (`float`)
+:pyeval:`constants.IPOLICY_SPINDLE_RATIO`
+ Maximum ratio of instances to their node's ``spindle_count`` (`float`)
+
Usage examples
--------------
Shell
+++++
-.. highlight:: sh
+.. highlight:: shell-example
Using wget::
- wget -q -O - https://CLUSTERNAME:5080/2/info
+ $ wget -q -O - https://%CLUSTERNAME%:5080/2/info
or curl::
- curl https://CLUSTERNAME:5080/2/info
+ $ curl https://%CLUSTERNAME%:5080/2/info
Python
The root resource. Has no function, but for legacy reasons the ``GET``
method is supported.
+``/2``
+++++++
+
+Has no function, but for legacy reasons the ``GET`` method is supported.
+
``/2/info``
+++++++++++
Redistribute configuration to all nodes. The result will be a job id.
+Job result:
+
+.. opcode_result:: OP_CLUSTER_REDIST_CONF
+
``/2/features``
+++++++++++++++
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)
.. opcode_params:: OP_CLUSTER_SET_PARAMS
+Job result:
+
+.. opcode_result:: OP_CLUSTER_SET_PARAMS
+
``/2/groups``
+++++++++++++
(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::
Earlier versions used a parameter named ``name`` which, while still
supported, has been renamed to ``group_name``.
+Job result:
+
+.. opcode_result:: OP_GROUP_ADD
+
``/2/groups/[group_name]``
++++++++++++++++++++++++++
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))`.
``DELETE``
~~~~~~~~~~
It supports the ``dry-run`` argument.
+Job result:
+
+.. opcode_result:: OP_GROUP_REMOVE
+
``/2/groups/[group_name]/modify``
+++++++++++++++++++++++++++++++++
.. opcode_params:: OP_GROUP_ASSIGN_NODES
:exclude: group_name, force, dry_run
+Job result:
+
+.. opcode_result:: OP_GROUP_ASSIGN_NODES
+
``/2/groups/[group_name]/tags``
+++++++++++++++++++++++++++++++
It supports the ``dry-run`` argument.
+``/2/networks``
++++++++++++++++
+
+The networks resource.
+
+It supports the following commands: ``GET``, ``POST``.
+
+``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,
+ 'network_type': 'private',
+ 'reserved_count': 3,
+ 'tags': ['nfdhcpd']
+ },
+ ]
+
+``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
+
+
+``/2/networks/[network_name]``
+++++++++++++++++++++++++++++++
+
+Returns information about a network.
+
+It supports the following commands: ``GET``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns information about a network, similar to the bulk output from
+the network list.
+
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.NET_FIELDS))`.
+
+``DELETE``
+~~~~~~~~~~
+
+Deletes a network.
+
+It supports the ``dry-run`` argument.
+
+Job result:
+
+.. opcode_result:: OP_NETWORK_REMOVE
+
+
+``/2/networks/[network_name]/modify``
++++++++++++++++++++++++++++++++++++++
+
+Modifies the parameters of a network.
+
+Supports the following commands: ``PUT``.
+
+``PUT``
+~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_NETWORK_SET_PARAMS
+
+Job result:
+
+.. opcode_result:: OP_NETWORK_SET_PARAMS
+
+
+``/2/networks/[network_name]/connect``
+++++++++++++++++++++++++++++++++++++++
+
+Connects a network to a nodegroup.
+
+Supports the following commands: ``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
+
+
+``/2/networks/[network_name]/disconnect``
++++++++++++++++++++++++++++++++++++++++++
+
+Disonnects a network from a nodegroup.
+
+Supports the following commands: ``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
+
+
+``/2/networks/[network_name]/tags``
++++++++++++++++++++++++++++++++++++
+
+Manages per-network tags.
+
+Supports the following commands: ``GET``, ``PUT``, ``DELETE``.
+
+``GET``
+~~~~~~~
+
+Returns a list of tags.
+
+Example::
+
+ ["tag1", "tag2", "tag3"]
+
+``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.
+
+
+``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.
+
+
+``/2/instances-multi-alloc``
+++++++++++++++++++++++++++++
+
+Tries to allocate multiple instances.
+
+It supports the following commands: ``POST``
+
+``POST``
+~~~~~~~~
+
+The parameters:
+
+.. opcode_params:: OP_INSTANCE_MULTI_ALLOC
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_MULTI_ALLOC
+
+
``/2/instances``
++++++++++++++++
(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::
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))`.
``DELETE``
~~~~~~~~~~
It supports the ``dry-run`` argument.
+Job result:
+
+.. opcode_result:: OP_INSTANCE_REMOVE
+
``/2/instances/[instance_name]/info``
+++++++++++++++++++++++++++++++++++++++
configuration without querying the instance's nodes. The result will be
a job id.
+Job result:
+
+.. opcode_result:: OP_INSTANCE_QUERY_DATA
+
``/2/instances/[instance_name]/reboot``
+++++++++++++++++++++++++++++++++++++++
It supports the ``dry-run`` argument.
+Job result:
+
+.. opcode_result:: OP_INSTANCE_REBOOT
+
``/2/instances/[instance_name]/shutdown``
+++++++++++++++++++++++++++++++++++++++++
.. opcode_params:: OP_INSTANCE_SHUTDOWN
:exclude: instance_name, dry_run
+Job result:
+
+.. opcode_result:: OP_INSTANCE_SHUTDOWN
+
``/2/instances/[instance_name]/startup``
++++++++++++++++++++++++++++++++++++++++
It supports the ``dry-run`` argument.
+Job result:
+
+.. opcode_result:: OP_INSTANCE_STARTUP
+
+
``/2/instances/[instance_name]/reinstall``
++++++++++++++++++++++++++++++++++++++++++++++
``POST``
~~~~~~~~
-Takes the parameters ``mode`` (one of ``replace_on_primary``,
-``replace_on_secondary``, ``replace_new_secondary`` or
-``replace_auto``), ``disks`` (comma separated list of disk indexes),
-``remote_node`` and ``iallocator``.
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_INSTANCE_REPLACE_DISKS
+ :exclude: instance_name
-Either ``remote_node`` or ``iallocator`` needs to be defined when using
-``mode=replace_new_secondary``.
+Ganeti 2.4 and below used query parameters. Those are deprecated and
+should no longer be used.
+
+Job result:
-``mode`` is a mandatory parameter. ``replace_auto`` tries to determine
-the broken disk(s) on its own and replacing it.
+.. opcode_result:: OP_INSTANCE_REPLACE_DISKS
``/2/instances/[instance_name]/activate-disks``
Takes the bool parameter ``ignore_size``. When set ignore the recorded
size (useful for forcing activation when recorded size is wrong).
+Job result:
+
+.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS
+
``/2/instances/[instance_name]/deactivate-disks``
+++++++++++++++++++++++++++++++++++++++++++++++++
Takes no parameters.
+Job result:
+
+.. opcode_result:: OP_INSTANCE_DEACTIVATE_DISKS
+
+
+``/2/instances/[instance_name]/recreate-disks``
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Recreate disks of an instance. Supports the following commands:
+``POST``.
+
+``POST``
+~~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_INSTANCE_RECREATE_DISKS
+ :exclude: instance_name
+
+Job result:
+
+.. opcode_result:: OP_INSTANCE_RECREATE_DISKS
+
``/2/instances/[instance_name]/disk/[disk_index]/grow``
+++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. opcode_params:: OP_INSTANCE_GROW_DISK
:exclude: instance_name, disk
+Job result:
+
+.. opcode_result:: OP_INSTANCE_GROW_DISK
+
``/2/instances/[instance_name]/prepare-export``
+++++++++++++++++++++++++++++++++++++++++++++++++
Takes one parameter, ``mode``, for the export mode. Returns a job ID.
+Job result:
+
+.. opcode_result:: OP_BACKUP_PREPARE
+
``/2/instances/[instance_name]/export``
+++++++++++++++++++++++++++++++++++++++++++++++++
:exclude: instance_name
:alias: target_node=destination
+Job result:
+
+.. opcode_result:: OP_BACKUP_EXPORT
+
``/2/instances/[instance_name]/migrate``
++++++++++++++++++++++++++++++++++++++++
.. opcode_params:: OP_INSTANCE_MIGRATE
:exclude: instance_name, live
+Job result:
+
+.. opcode_result:: OP_INSTANCE_MIGRATE
+
``/2/instances/[instance_name]/failover``
+++++++++++++++++++++++++++++++++++++++++
.. opcode_params:: OP_INSTANCE_FAILOVER
:exclude: instance_name
+Job result:
+
+.. opcode_result:: OP_INSTANCE_FAILOVER
+
``/2/instances/[instance_name]/rename``
++++++++++++++++++++++++++++++++++++++++
Request information for connecting to instance's console.
-Supports the following commands: ``GET``.
+.. pyassert::
+
+ 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)`.
``GET``
~~~~~~~
constants.CONS_MESSAGE,
constants.CONS_SSH,
constants.CONS_VNC,
+ constants.CONS_SPICE,
])
``instance``
- Instance name.
+ Instance name
``kind``
Console type, one of :pyeval:`constants.CONS_SSH`,
- :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_MESSAGE`.
+ :pyeval:`constants.CONS_VNC`, :pyeval:`constants.CONS_SPICE`
+ 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` and
- :pyeval:`constants.CONS_VNC` only).
+ Host to connect to (:pyeval:`constants.CONS_SSH`,
+ :pyeval:`constants.CONS_VNC` or :pyeval:`constants.CONS_SPICE` only)
``port``
- TCP port to connect to (:pyeval:`constants.CONS_VNC` only).
+ TCP port to connect to (:pyeval:`constants.CONS_VNC` or
+ :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)
``/2/instances/[instance_name]/tags``
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))`.
``/2/jobs/[job_id]``
++++++++++++++++++++
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.
(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::
It supports the following commands: ``GET``.
-Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`
+Returned fields: :pyeval:`utils.CommaJoin(sorted(rlib2.N_FIELDS))`.
+
+``/2/nodes/[node_name]/powercycle``
++++++++++++++++++++++++++++++++++++
+
+Powercycles a node. Supports the following commands: ``POST``.
+
+``POST``
+~~~~~~~~
+
+Returns a job ID.
+
+Job result:
+
+.. opcode_result:: OP_NODE_POWERCYCLE
+
``/2/nodes/[node_name]/evacuate``
+++++++++++++++++++++++++++++++++
and should no longer be used. The new request format can be detected by
the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string.
+Job result:
+
+.. opcode_result:: OP_NODE_MIGRATE
+
``/2/nodes/[node_name]/role``
+++++++++++++++++++++++++++++
It supports the bool ``force`` argument.
+Job result:
+
+.. opcode_result:: OP_NODE_SET_PARAMS
+
+
+``/2/nodes/[node_name]/modify``
++++++++++++++++++++++++++++++++
+
+Modifies the parameters of a node. Supports the following commands:
+``POST``.
+
+``POST``
+~~~~~~~~
+
+Returns a job ID.
+
+Body parameters:
+
+.. opcode_params:: OP_NODE_SET_PARAMS
+ :exclude: node_name
+
+Job result:
+
+.. opcode_result:: OP_NODE_SET_PARAMS
+
+
``/2/nodes/[node_name]/storage``
++++++++++++++++++++++++++++++++
additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
is supported. The result will be a job id.
+Job result:
+
+.. opcode_result:: OP_NODE_MODIFY_STORAGE
+
+
``/2/nodes/[node_name]/storage/repair``
+++++++++++++++++++++++++++++++++++++++
repaired) and ``name`` (name of the storage unit). The result will be a
job id.
+Job result:
+
+.. opcode_result:: OP_REPAIR_NODE_STORAGE
+
+
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++
:pyeval:`utils.CommaJoin(constants.QR_VIA_RAPI)`. See the :doc:`query2
design document <design-query2>` for more details.
-Supports the following commands: ``GET``, ``PUT``.
+.. pyassert::
+
+ (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)`.
``GET``
~~~~~~~
projects / ganeti-local / blobdiff