Body parameters:
-``vg_name`` (string)
- Volume group name.
-``enabled_hypervisors`` (list)
- List of enabled hypervisors.
-``hvparams`` (dict)
- Cluster-wide hypervisor parameter defaults, hypervisor-dependent.
-``beparams`` (dict)
- Cluster-wide backend parameter defaults.
-``os_hvp`` (dict)
- Cluster-wide per-OS hypervisor parameter defaults.
-``osparams`` (dict)
- Dictionary with OS parameters.
-``candidate_pool_size`` (int)
- Master candidate pool size.
-``uid_pool`` (list)
- Set UID pool. Must be list of lists describing UID ranges (two items,
- start and end inclusive).
-``add_uids``
- Extend UID pool. Must be list of lists describing UID ranges (two
- items, start and end inclusive) to be added.
-``remove_uids``
- Shrink UID pool. Must be list of lists describing UID ranges (two
- items, start and end inclusive) to be removed.
-``maintain_node_health`` (bool)
- Whether to automatically maintain node health.
-``prealloc_wipe_disks`` (bool)
- Whether to wipe disks before allocating them to instances.
-``nicparams`` (dict)
- Cluster-wide NIC parameter defaults.
-``ndparams`` (dict)
- Cluster-wide node parameter defaults.
-``drbd_helper`` (string)
- DRBD helper program.
-``default_iallocator`` (string)
- Default iallocator for cluster.
-``master_netdev`` (string)
- Master network device.
-``reserved_lvs`` (list)
- List of reserved LVs (strings).
-``hidden_os`` (list)
- List of modifications as lists. Each modification must have two items,
- the operation and the OS name. The operation can be ``add`` or
- ``remove``.
-``blacklisted_os`` (list)
- List of modifications as lists. Each modification must have two items,
- the operation and the OS name. The operation can be ``add`` or
- ``remove``.
+.. opcode_params:: OP_CLUSTER_SET_PARAMS
``/2/groups``
Body parameters:
-``name`` (string, required)
- Node group name.
+.. opcode_params:: OP_GROUP_ADD
+
+Earlier versions used a parameter named ``name`` which, while still
+supported, has been renamed to ``group_name``.
``/2/groups/[group_name]``
Body parameters:
-``alloc_policy`` (string)
- If present, the new allocation policy for the node group.
+.. opcode_params:: OP_GROUP_SET_PARAMS
+ :exclude: group_name
``/2/groups/[group_name]/rename``
Body parameters:
-``new_name`` (string, required)
- New node group name.
+.. opcode_params:: OP_GROUP_RENAME
+ :exclude: group_name
+
+
+``/2/groups/[group_name]/assign-nodes``
++++++++++++++++++++++++++++++++++++++++
+
+Assigns nodes to a group.
+
+Supports the following commands: ``PUT``.
+
+``PUT``
+~~~~~~~
+
+Returns a job ID. It supports the ``dry-run`` and ``force`` arguments.
+
+Body parameters:
+
+.. opcode_params:: OP_GROUP_ASSIGN_NODES
+ :exclude: group_name, force, dry_run
``/2/instances``
``__version__`` (int, required)
Must be ``1`` (older Ganeti versions used a different format for
instance creation requests, version ``0``, but that format is not
- documented).
-``mode`` (string, required)
- Instance creation mode.
-``name`` (string, required)
- Instance name.
-``disk_template`` (string, required)
- Disk template for instance.
-``disks`` (list, required)
- List of disk definitions. Example: ``[{"size": 100}, {"size": 5}]``.
- Each disk definition must contain a ``size`` value and can contain an
- optional ``mode`` value denoting the disk access mode (``ro`` or
- ``rw``).
-``nics`` (list, required)
- List of NIC (network interface) definitions. Example: ``[{}, {},
- {"ip": "198.51.100.4"}]``. Each NIC definition can contain the
- optional values ``ip``, ``mode``, ``link`` and ``bridge``.
-``os`` (string, required)
- Instance operating system.
-``osparams`` (dictionary)
- Dictionary with OS parameters. If not valid for the given OS, the job
- will fail.
-``force_variant`` (bool)
- Whether to force an unknown variant.
-``no_install`` (bool)
- Do not install the OS (will enable no-start)
-``pnode`` (string)
- Primary node.
-``snode`` (string)
- Secondary node.
-``src_node`` (string)
- Source node for import.
-``src_path`` (string)
- Source directory for import.
-``start`` (bool)
- Whether to start instance after creation.
-``ip_check`` (bool)
- Whether to ensure instance's IP address is inactive.
-``name_check`` (bool)
- Whether to ensure instance's name is resolvable.
-``file_storage_dir`` (string)
- File storage directory.
-``file_driver`` (string)
- File storage driver.
-``iallocator`` (string)
- Instance allocator name.
-``source_handshake`` (list)
- Signed handshake from source (remote import only).
-``source_x509_ca`` (string)
- Source X509 CA in PEM format (remote import only).
-``source_instance_name`` (string)
- Source instance name (remote import only).
-``hypervisor`` (string)
- Hypervisor name.
-``hvparams`` (dict)
- Hypervisor parameters, hypervisor-dependent.
-``beparams`` (dict)
- Backend parameters.
+ documented and should no longer be used).
+
+.. opcode_params:: OP_INSTANCE_CREATE
+
+Earlier versions used parameters named ``name`` and ``os``. These have
+been replaced by ``instance_name`` and ``os_type`` to match the
+underlying opcode. The old names can still be used.
``/2/instances/[instance_name]``
Body parameters:
-``amount`` (int, required)
- Amount of disk space to add.
-``wait_for_sync`` (bool)
- Whether to wait for the disk to synchronize.
+.. opcode_params:: OP_INSTANCE_GROW_DISK
+ :exclude: instance_name, disk
``/2/instances/[instance_name]/prepare-export``
Body parameters:
-``mode`` (string)
- Export mode.
-``destination`` (required)
- Destination information, depends on export mode.
-``shutdown`` (bool, required)
- Whether to shutdown instance before export.
-``remove_instance`` (bool)
- Whether to remove instance after export.
-``x509_key_name``
- Name of X509 key (remote export only).
-``destination_x509_ca``
- Destination X509 CA (remote export only).
+.. opcode_params:: OP_BACKUP_EXPORT
+ :exclude: instance_name
+ :alias: target_node=destination
``/2/instances/[instance_name]/migrate``
Body parameters:
-``mode`` (string)
- Migration mode.
-``cleanup`` (bool)
- Whether a previously failed migration should be cleaned up.
+.. opcode_params:: OP_INSTANCE_MIGRATE
+ :exclude: instance_name, live
``/2/instances/[instance_name]/rename``
Body parameters:
-``new_name`` (string, required)
- New instance name.
-``ip_check`` (bool)
- Whether to ensure instance's IP address is inactive.
-``name_check`` (bool)
- Whether to ensure instance's name is resolvable.
+.. opcode_params:: OP_INSTANCE_RENAME
+ :exclude: instance_name
``/2/instances/[instance_name]/modify``
Body parameters:
-``osparams`` (dict)
- Dictionary with OS parameters.
-``hvparams`` (dict)
- Hypervisor parameters, hypervisor-dependent.
-``beparams`` (dict)
- Backend parameters.
-``force`` (bool)
- Whether to force the operation.
-``nics`` (list)
- List of NIC changes. Each item is of the form ``(op, settings)``.
- ``op`` can be ``add`` to add a new NIC with the specified settings,
- ``remove`` to remove the last NIC or a number to modify the settings
- of the NIC with that index.
-``disks`` (list)
- List of disk changes. See ``nics``.
-``disk_template`` (string)
- Disk template for instance.
-``remote_node`` (string)
- Secondary node (used when changing disk template).
-``os_name`` (string)
- Change instance's OS name. Does not reinstall the instance.
-``force_variant`` (bool)
- Whether to force an unknown variant.
+.. opcode_params:: OP_INSTANCE_SET_PARAMS
+ :exclude: instance_name
+
+
+``/2/instances/[instance_name]/console``
+++++++++++++++++++++++++++++++++++++++++
+
+Request information for connecting to instance's console.
+
+Supports the following commands: ``GET``.
+
+``GET``
+~~~~~~~
+
+Returns a dictionary containing information about the instance's
+console. Contained keys:
+
+``instance``
+ Instance name.
+``kind``
+ Console type, one of ``ssh``, ``vnc`` or ``msg``.
+``message``
+ Message to display (``msg`` type only).
+``host``
+ Host to connect to (``ssh`` and ``vnc`` only).
+``port``
+ TCP port to connect to (``vnc`` only).
+``user``
+ Username to use (``ssh`` only).
+``command``
+ Command to execute on machine (``ssh`` only)
+``display``
+ VNC display number (``vnc`` only).
``/2/instances/[instance_name]/tags``
effects. But whether it make sense to retry depends on the error
classification:
-``resolver_error``
+.. pyassert::
+
+ 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])
+
+:pyeval:`errors.ECODE_RESOLVER`
Resolver errors. This usually means that a name doesn't exist in DNS,
so if it's a case of slow DNS propagation the operation can be retried
later.
-``insufficient_resources``
+:pyeval:`errors.ECODE_NORES`
Not enough resources (iallocator failure, disk space, memory,
etc.). If the resources on the cluster increase, the operation might
succeed.
-``wrong_input``
+:pyeval:`errors.ECODE_INVAL`
Wrong arguments (at syntax level). The operation will not ever be
accepted unless the arguments change.
-``wrong_state``
+:pyeval:`errors.ECODE_STATE`
Wrong entity state. For example, live migration has been requested for
a down instance, or instance creation on an offline node. The
operation can be retried once the resource has changed state.
-``unknown_entity``
+:pyeval:`errors.ECODE_NOENT`
Entity not found. For example, information has been requested for an
unknown instance.
-``already_exists``
+:pyeval:`errors.ECODE_EXISTS`
Entity already exists. For example, instance creation has been
requested for an already-existing instance.
-``resource_not_unique``
+:pyeval:`errors.ECODE_NOTUNIQUE`
Resource not unique (e.g. MAC or IP duplication).
-``internal_error``
+:pyeval:`errors.ECODE_FAULT`
Internal cluster error. For example, a node is unreachable but not set
offline, or the ganeti node daemons are not working, etc. A
``gnt-cluster verify`` should be run.
-``environment_error``
+:pyeval:`errors.ECODE_ENVIRON`
Environment error (e.g. node disk error). A ``gnt-cluster verify``
should be run.
``GET``
~~~~~~~
+.. pyassert::
+
+ constants.VALID_STORAGE_TYPES == set([constants.ST_FILE,
+ constants.ST_LVM_PV,
+ constants.ST_LVM_VG])
+
Requests a list of storage units on a node. Requires the parameters
-``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``) and
+``storage_type`` (one of :pyeval:`constants.ST_FILE`,
+:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`) and
``output_fields``. The result will be a job id, using which the result
can be retrieved.
~~~~~~~
Modifies parameters of storage units on the node. Requires the
-parameters ``storage_type`` (one of ``file``, ``lvm-pv`` or ``lvm-vg``)
+parameters ``storage_type`` (one of :pyeval:`constants.ST_FILE`,
+:pyeval:`constants.ST_LVM_PV` or :pyeval:`constants.ST_LVM_VG`)
and ``name`` (name of the storage unit). Parameters can be passed
-additionally. Currently only ``allocatable`` (bool) is supported. The
-result will be a job id.
+additionally. Currently only :pyeval:`constants.SF_ALLOCATABLE` (bool)
+is supported. The result will be a job id.
``/2/nodes/[node_name]/storage/repair``
+++++++++++++++++++++++++++++++++++++++
``PUT``
~~~~~~~
+.. pyassert::
+
+ constants.VALID_STORAGE_OPERATIONS == {
+ constants.ST_LVM_VG: set([constants.SO_FIX_CONSISTENCY]),
+ }
+
Repairs a storage unit on the node. Requires the parameters
-``storage_type`` (currently only ``lvm-vg`` can be repaired) and
-``name`` (name of the storage unit). The result will be a job id.
+``storage_type`` (currently only :pyeval:`constants.ST_LVM_VG` can be
+repaired) and ``name`` (name of the storage unit). The result will be a
+job id.
``/2/nodes/[node_name]/tags``
+++++++++++++++++++++++++++++