X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/94497dd1cfce6babe08f65603a2619afdc178969..cc67d8eb93b8575d0d71f236a9af411d42780ddf:/doc/rapi.rst?ds=sidebyside diff --git a/doc/rapi.rst b/doc/rapi.rst index 238b849..baed7fe 100644 --- a/doc/rapi.rst +++ b/doc/rapi.rst @@ -166,6 +166,64 @@ likely to succeed or at least start executing. Force operation to continue even if it will cause the cluster to become inconsistent (e.g. because there are not enough master candidates). +Parameter details +----------------- + +Some parameters are not straight forward, so we describe them in details +here. + +.. _rapi-ipolicy: + +``ipolicy`` ++++++++++++ + +The instance policy specification is a dict with the following fields: + +.. pyassert:: + + constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_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])) + +.. |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.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 -------------- @@ -239,30 +297,13 @@ Resources ``/`` +++++ -The root resource. - -It supports the following commands: ``GET``. - -``GET`` -~~~~~~~ - -Shows the list of mapped resources. - -Returns: a dictionary with 'name' and 'uri' keys for each of them. +The root resource. Has no function, but for legacy reasons the ``GET`` +method is supported. ``/2`` ++++++ -The ``/2`` resource, the root of the version 2 API. - -It supports the following commands: ``GET``. - -``GET`` -~~~~~~~ - -Show the list of mapped resources. - -Returns: a dictionary with ``name`` and ``uri`` keys for each of them. +Has no function, but for legacy reasons the ``GET`` method is supported. ``/2/info`` +++++++++++ @@ -320,6 +361,10 @@ It supports the following commands: ``PUT``. Redistribute configuration to all nodes. The result will be a job id. +Job result: + +.. opcode_result:: OP_CLUSTER_REDIST_CONF + ``/2/features`` +++++++++++++++ @@ -365,6 +410,10 @@ Body parameters: .. opcode_params:: OP_CLUSTER_SET_PARAMS +Job result: + +.. opcode_result:: OP_CLUSTER_SET_PARAMS + ``/2/groups`` +++++++++++++ @@ -436,6 +485,10 @@ Body parameters: 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]`` ++++++++++++++++++++++++++ @@ -459,6 +512,10 @@ Deletes a node group. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_GROUP_REMOVE + ``/2/groups/[group_name]/modify`` +++++++++++++++++++++++++++++++++ @@ -521,6 +578,10 @@ Body parameters: .. 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`` +++++++++++++++++++++++++++++++ @@ -675,6 +736,10 @@ Deletes an instance. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_INSTANCE_REMOVE + ``/2/instances/[instance_name]/info`` +++++++++++++++++++++++++++++++++++++++ @@ -689,6 +754,10 @@ Requests detailed information about the instance. An optional parameter, 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`` +++++++++++++++++++++++++++++++++++++++ @@ -717,6 +786,10 @@ instance even if secondary disks are failing. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_INSTANCE_REBOOT + ``/2/instances/[instance_name]/shutdown`` +++++++++++++++++++++++++++++++++++++++++ @@ -735,6 +808,10 @@ It supports the ``dry-run`` argument. .. opcode_params:: OP_INSTANCE_SHUTDOWN :exclude: instance_name, dry_run +Job result: + +.. opcode_result:: OP_INSTANCE_SHUTDOWN + ``/2/instances/[instance_name]/startup`` ++++++++++++++++++++++++++++++++++++++++ @@ -753,6 +830,11 @@ instance even if secondary disks are failing. It supports the ``dry-run`` argument. +Job result: + +.. opcode_result:: OP_INSTANCE_STARTUP + + ``/2/instances/[instance_name]/reinstall`` ++++++++++++++++++++++++++++++++++++++++++++++ @@ -789,16 +871,19 @@ It supports the following commands: ``POST``. ``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 + +Ganeti 2.4 and below used query parameters. Those are deprecated and +should no longer be used. -Either ``remote_node`` or ``iallocator`` needs to be defined when using -``mode=replace_new_secondary``. +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`` @@ -814,6 +899,10 @@ It supports the following commands: ``PUT``. Takes the bool parameter ``ignore_size``. When set ignore the recorded size (useful for forcing activation when recorded size is wrong). +Job result: + +.. opcode_result:: OP_INSTANCE_ACTIVATE_DISKS + ``/2/instances/[instance_name]/deactivate-disks`` +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -827,6 +916,31 @@ It supports the following commands: ``PUT``. 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`` +++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -845,6 +959,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_GROW_DISK :exclude: instance_name, disk +Job result: + +.. opcode_result:: OP_INSTANCE_GROW_DISK + ``/2/instances/[instance_name]/prepare-export`` +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -858,6 +976,10 @@ It supports the following commands: ``PUT``. Takes one parameter, ``mode``, for the export mode. Returns a job ID. +Job result: + +.. opcode_result:: OP_BACKUP_PREPARE + ``/2/instances/[instance_name]/export`` +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -877,6 +999,10 @@ Body parameters: :exclude: instance_name :alias: target_node=destination +Job result: + +.. opcode_result:: OP_BACKUP_EXPORT + ``/2/instances/[instance_name]/migrate`` ++++++++++++++++++++++++++++++++++++++++ @@ -895,6 +1021,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_MIGRATE :exclude: instance_name, live +Job result: + +.. opcode_result:: OP_INSTANCE_MIGRATE + ``/2/instances/[instance_name]/failover`` +++++++++++++++++++++++++++++++++++++++++ @@ -913,6 +1043,10 @@ Body parameters: .. opcode_params:: OP_INSTANCE_FAILOVER :exclude: instance_name +Job result: + +.. opcode_result:: OP_INSTANCE_FAILOVER + ``/2/instances/[instance_name]/rename`` ++++++++++++++++++++++++++++++++++++++++ @@ -1241,6 +1375,21 @@ It supports the following commands: ``GET``. 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`` +++++++++++++++++++++++++++++++++ @@ -1288,6 +1437,10 @@ The query arguments used up to and including Ganeti 2.4 are deprecated and should no longer be used. The new request format can be detected by the presence of the :pyeval:`rlib2._NODE_MIGRATE_REQV1` feature string. +Job result: + +.. opcode_result:: OP_NODE_MIGRATE + ``/2/nodes/[node_name]/role`` +++++++++++++++++++++++++++++ @@ -1326,15 +1479,19 @@ be a job id. 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. @@ -1383,6 +1540,11 @@ and ``name`` (name of the storage unit). Parameters can be passed 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`` +++++++++++++++++++++++++++++++++++++++ @@ -1402,6 +1564,11 @@ Repairs a storage unit on the node. Requires the parameters 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`` +++++++++++++++++++++++++++++