ganeti-rapi reads users and passwords from a file (usually
/var/lib/ganeti/rapi/users) on startup. Changes to the file will be
read automatically.
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:
- write
- Enables the user to execute operations modifying the cluster. Implies
read 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) 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
jack abc123
fred {cleartext}foo555
# Give write access to an imaginary instance creation script
autocreator xyz789 write
# 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. Alternatively, the appropriate parameter of your HTTP client
(such as -u for curl) can be used.
According to RFC 2616 the main difference between PUT and POST is
that POST can create new resources but PUT can only create the resource
the URI was pointing to on the PUT request.
Unfortunately, due to historic reasons, the Ganeti RAPI library is not
consistent with this usage, so just use the methods as documented below
for each resource.
For more details have a look in the source code at
lib/rapi/rlib2.py.
The root resource. Has no function, but for legacy reasons the GET
method is supported.
Has no function, but for legacy reasons the GET method is supported.
Cluster information resource.
It supports the following commands: GET.
Returns cluster information.
Example:
{
"config_version": 2000000,
"name": "cluster",
"software_version": "2.0.0~beta2",
"os_api_version": 10,
"export_version": 0,
"candidate_pool_size": 10,
"enabled_hypervisors": [
"fake"
],
"hvparams": {
"fake": {}
},
"default_hypervisor": "fake",
"master": "node1.example.com",
"architecture": [
"64bit",
"x86_64"
],
"protocol_version": 20,
"beparams": {
"default": {
"auto_balance": true,
"vcpus": 1,
"memory": 128
}
},
…
}
Redistribute configuration to all nodes.
It supports the following commands: PUT.
Redistribute configuration to all nodes. The result will be a job id.
Job result:
None
Returns a list of features supported by the RAPI server. Available
features:
- instance-create-reqv1
- Instance creation request data version 1 supported
- instance-reinstall-reqv1
- Instance reinstall supports body parameters
- node-migrate-reqv1
- Whether migrating a node (/2/nodes/[node_name]/migrate) supports
request body parameters
- node-evac-res1
- Whether evacuating a node (/2/nodes/[node_name]/evacuate) returns
a new-style result (see resource description)
Modifies cluster parameters.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- add_uids (defaults to None)
- Extend UID pool, must be list of lists describing UID ranges (two items, start and end inclusive) to be added
- beparams (defaults to None, must be None or Dictionary)
- Cluster-wide backend parameter defaults
- blacklisted_os (defaults to None, must be None or (List of ((Length 2) and (Item 0 is (OneOf add, remove), item 1 is NonEmptyString))))
- Modify list of blacklisted operating systems: each modification must have two items, the operation and the OS name; the operation can be add or remove
- candidate_pool_size (defaults to None, must be None or (Integer and GreaterThanZero))
- Master candidate pool size
- default_iallocator (defaults to None, must be None or String)
- Default iallocator for cluster
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disk_state (defaults to None, must be None or Dictionary)
- Set disk states
- diskparams (defaults to None, must be None or (Dictionary with keys of (OneOf sharedfile, diskless, plain, blockdev, drbd, ext, file, rbd) and values of Dictionary))
- Disk templates’ parameter defaults
- drbd_helper (defaults to None, must be None or String)
- DRBD helper program
- enabled_hypervisors (defaults to None, must be None or ((List of (OneOf chroot, xen-pvm, kvm, xen-hvm, lxc, fake)) and EvalToTrue))
- List of enabled hypervisors
- hidden_os (defaults to None, must be None or (List of ((Length 2) and (Item 0 is (OneOf add, remove), item 1 is NonEmptyString))))
- Modify list of hidden operating systems: each modification must have two items, the operation and the OS name; the operation can be add or remove
- hv_state (defaults to None, must be None or Dictionary)
- Set hypervisor states
- hvparams (defaults to None, must be None or (Dictionary with keys of NonEmptyString and values of Dictionary))
- Cluster-wide hypervisor parameter defaults, hypervisor-dependent
- ipolicy (defaults to None, must be None or Dictionary)
- Cluster-wide instance policy specs
- maintain_node_health (defaults to None, must be None or Boolean)
- Whether to automatically maintain node health
- master_netdev (defaults to None, must be None or String)
- Master network device
- master_netmask (defaults to None, must be None or (Integer and EqualOrGreaterThanZero))
- Netmask of the master IP
- ndparams (defaults to None, must be None or Dictionary)
- Cluster-wide node parameter defaults
- nicparams (defaults to None, must be None or Dictionary)
- Cluster-wide NIC parameter defaults
- os_hvp (defaults to None, must be None or (Dictionary with keys of NonEmptyString and values of Dictionary))
- Cluster-wide per-OS hypervisor parameter defaults
- osparams (defaults to None, must be None or (Dictionary with keys of NonEmptyString and values of Dictionary))
- Cluster-wide OS parameter defaults
- prealloc_wipe_disks (defaults to None, must be None or Boolean)
- Whether to wipe disks before allocating them to instances
- remove_uids (defaults to None)
- Shrink UID pool, must be list of lists describing UID ranges (two items, start and end inclusive) to be removed
- reserved_lvs (defaults to None, must be None or (List of NonEmptyString))
- List of reserved LVs
- uid_pool (defaults to None)
- Set UID pool, must be list of lists describing UID ranges (two items, start and end inclusive)
- use_external_mip_script (defaults to None, must be None or Boolean)
- Whether to use an external master IP address setup script
- vg_name (defaults to None, must be None or String)
- Volume group name
Job result:
None
The groups resource.
It supports the following commands: GET, POST.
Returns a list of all existing node groups.
Example:
[
{
"name": "group1",
"uri": "\/2\/groups\/group1"
},
{
"name": "group2",
"uri": "\/2\/groups\/group2"
}
]
If the optional bool bulk argument is provided and set to a true value
(i.e ?bulk=1), the output contains detailed information about node
groups as a list.
Returned fields: alloc_policy, ctime, custom_diskparams, custom_ipolicy, custom_ndparams, diskparams, ipolicy, mtime, name, ndparams, node_cnt, node_list, serial_no, tags, uuid.
Example:
[
{
"name": "group1",
"node_cnt": 2,
"node_list": [
"node1.example.com",
"node2.example.com"
],
"uuid": "0d7d407c-262e-49af-881a-6a430034bf43",
…
},
{
"name": "group2",
"node_cnt": 1,
"node_list": [
"node3.example.com"
],
"uuid": "f5a277e7-68f9-44d3-a378-4b25ecb5df5c",
…
},
…
]
Creates a node group.
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:
- alloc_policy (defaults to None, must be None or (OneOf preferred, last_resort, unallocable))
- Instance allocation policy
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disk_state (defaults to None, must be None or Dictionary)
- Set disk states
- diskparams (defaults to None, must be None or (Dictionary with keys of (OneOf sharedfile, diskless, plain, blockdev, drbd, ext, file, rbd) and values of Dictionary))
- Disk templates’ parameter defaults
- group_name (must be NonEmptyString)
- Group name
- hv_state (defaults to None, must be None or Dictionary)
- Set hypervisor states
- ipolicy (defaults to None, must be None or Dictionary)
- Group-wide instance policy specs
- ndparams (defaults to None, must be None or Dictionary)
- Default node parameters for group
Earlier versions used a parameter named name which, while still
supported, has been renamed to group_name.
Job result:
None
Returns information about a node group.
It supports the following commands: GET, DELETE.
Returns information about a node group, similar to the bulk output from
the node group list.
Returned fields: alloc_policy, ctime, custom_diskparams, custom_ipolicy, custom_ndparams, diskparams, ipolicy, mtime, name, ndparams, node_cnt, node_list, serial_no, tags, uuid.
Deletes a node group.
It supports the dry-run argument.
Job result:
None
Modifies the parameters of a node group.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- alloc_policy (defaults to None, must be None or (OneOf preferred, last_resort, unallocable))
- Instance allocation policy
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disk_state (defaults to None, must be None or Dictionary)
- Set disk states
- diskparams (defaults to None, must be None or (Dictionary with keys of (OneOf sharedfile, diskless, plain, blockdev, drbd, ext, file, rbd) and values of Dictionary))
- Disk templates’ parameter defaults
- hv_state (defaults to None, must be None or Dictionary)
- Set hypervisor states
- ipolicy (defaults to None, must be None or Dictionary)
- Group-wide instance policy specs
- ndparams (defaults to None, must be None or Dictionary)
- Default node parameters for group
Job result:
List of ((Length 2) and (Item 0 is (NonEmptyString [name of changed parameter]), item 1 is (Anything [new value])))
Renames a node group.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- new_name (must be NonEmptyString)
- New group name
Job result:
NonEmptyString [New group name]
Assigns nodes to a group.
Supports the following commands: PUT.
Returns a job ID. It supports the dry-run and force arguments.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- nodes (must be List of NonEmptyString)
- List of nodes to assign
Job result:
None
The networks resource.
It supports the following commands: GET, POST.
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: ctime, external_reservations, free_count, gateway, gateway6, group_list, inst_list, mac_prefix, map, mtime, name, network, network6, reserved_count, serial_no, tags, uuid.
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'],
…
},
…
]
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:
- add_reserved_ips (defaults to None, must be None or (List of (String and (IPv4 address))))
- Which IP addresses to reserve
- conflicts_check (defaults to True, must be Boolean)
- Whether to check for conflicting IP addresses
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- gateway (defaults to None, must be None or (String and (IPv4 address)))
- IPv4 gateway
- gateway6 (defaults to None, must be None or (String and (IPv6 address)))
- IPv6 gateway
- mac_prefix (defaults to None, must be None or NonEmptyString)
- MAC address prefix that overrides cluster one
- network (must be String and (IPv4 network))
- IPv4 subnet
- network6 (defaults to None, must be None or (String and (IPv6 network)))
- IPv6 subnet
- network_name (must be NonEmptyString)
- Set network name
- tags (defaults to [], must be List of NonEmptyString)
- Network tags
Job result:
None
Returns information about a network.
It supports the following commands: GET, DELETE.
Returns information about a network, similar to the bulk output from
the network list.
Returned fields: ctime, external_reservations, free_count, gateway, gateway6, group_list, inst_list, mac_prefix, map, mtime, name, network, network6, reserved_count, serial_no, tags, uuid.
Deletes a network.
It supports the dry-run argument.
Job result:
None
Modifies the parameters of a network.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- add_reserved_ips (defaults to None, must be None or (List of (String and (IPv4 address))))
- Which external IP addresses to reserve
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- gateway (defaults to None, must be None or (ValueNone or (String and (IPv4 address))))
- IPv4 gateway
- gateway6 (defaults to None, must be None or (ValueNone or (String and (IPv6 address))))
- IPv6 gateway
- mac_prefix (defaults to None, must be None or (ValueNone or String))
- MAC address prefix that overrides cluster one
- network6 (defaults to None, must be None or (ValueNone or (String and (IPv6 network))))
- IPv6 subnet
- network_name (must be NonEmptyString)
- Set network name
- remove_reserved_ips (defaults to None, must be None or (List of (String and (IPv4 address))))
- Which external IP addresses to release
Job result:
None
Connects a network to a nodegroup.
Supports the following commands: PUT.
Returns a job ID. It supports the dry-run arguments.
Body parameters:
- conflicts_check (defaults to True, must be Boolean)
- Whether to check for conflicting IPs
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- group_name (must be NonEmptyString)
- Group name
- network_link (must be String)
- Connectivity link
- network_mode (must be OneOf openvswitch, bridged, routed)
- Connectivity mode
- network_name (must be NonEmptyString)
- Set network name
Job result:
None
Disonnects a network from a nodegroup.
Supports the following commands: PUT.
Returns a job ID. It supports the dry-run arguments.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- group_name (must be NonEmptyString)
- Group name
- network_name (must be NonEmptyString)
- Set network name
Job result:
None
Tries to allocate multiple instances.
It supports the following commands: POST
The parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator used to allocate all the instances
- instances (defaults to [], must be List of (Instance of (ganeti.opcodes.OpInstanceCreate)))
- List of instance create opcodes describing the instances to allocate
- opportunistic_locking (defaults to False, must be Boolean)
- Whether to employ opportunistic locking for nodes, meaning nodes already locked by another opcode won’t be considered for instance allocation (only when an iallocator is used)
Job result:
Dictionary containing none but the required keys "allocatable" (value List of NonEmptyString), "jobs" (value List of ((Length 2) and (Item 0 is (Boolean [success]), item 1 is (String or JobId [Job ID if successful, error message otherwise]))) [List of submitted jobs])
The instances resource.
It supports the following commands: GET, POST.
Returns a list of all available instances.
Example:
[
{
"name": "web.example.com",
"uri": "\/instances\/web.example.com"
},
{
"name": "mail.example.com",
"uri": "\/instances\/mail.example.com"
}
]
If the optional bool bulk argument is provided and set to a true value
(i.e ?bulk=1), the output contains detailed information about
instances as a list.
Returned fields: admin_state, beparams, ctime, custom_beparams, custom_hvparams, custom_nicparams, disk.sizes, disk_template, disk_usage, hvparams, mtime, name, network_port, nic.bridges, nic.ips, nic.links, nic.macs, nic.modes, nic.networks, nic.networks.names, oper_ram, oper_state, oper_vcpus, os, pnode, serial_no, snodes, status, tags, uuid.
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,
…
},
…
]
Creates an instance.
If the optional bool dry-run argument is provided, the job will not be
actually executed, only the pre-execution checks will be done. Query-ing
the job result will return, in both dry-run and normal case, the list of
nodes selected for the instance.
Returns: a job ID that can be used later for polling.
Body parameters:
- __version__ (int, required)
- Must be 1 (older Ganeti versions used a different format for
instance creation requests, version 0, but that format is no
longer supported)
- beparams (defaults to {}, must be Dictionary)
- Backend parameters for instance
- conflicts_check (defaults to True, must be Boolean)
- Check for conflicting IPs
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disk_template (must be (None or (OneOf sharedfile, diskless, plain, blockdev, drbd, ext, file, rbd)) and CheckFileStorage)
- Disk template
- disks (must be List of (Dictionary with keys of NonEmptyString and values of (NonEmptyString or Integer) [Disk parameters]))
- Disk descriptions, for 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)
- file_driver (defaults to None, must be None or (OneOf blktap, loop))
- Driver for file-backed disks
- file_storage_dir (defaults to None, must be None or NonEmptyString)
- Directory for storing file-backed disks
- force_variant (defaults to False, must be Boolean)
- Whether to force an unknown OS variant
- hvparams (defaults to {}, must be Dictionary)
- Hypervisor parameters for instance, hypervisor-dependent
- hypervisor (defaults to None, must be None or NonEmptyString)
- Hypervisor
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for deciding which node(s) to use
- identify_defaults (defaults to False, must be Boolean)
- Reset instance parameters to default if equal
- ignore_ipolicy (defaults to False, must be Boolean)
- Whether to ignore ipolicy violations
- instance_name (must be NonEmptyString)
- Instance name
- ip_check (defaults to True, must be Boolean)
- Whether to ensure instance’s IP address is inactive
- mode (must be OneOf import, create, remote-import)
- Instance creation mode
- name_check (defaults to True, must be Boolean)
- Whether to check name
- nics (must be List of (Dictionary with keys of (OneOf ip, mac, link, mode, network) and values of (None or NonEmptyString) [NIC parameters]))
- List of NIC (network interface) definitions, for example [{}, {}, {"ip": "198.51.100.4"}]; each NIC definition can contain the optional values ip, link, mac, mode, network
- no_install (defaults to None, must be None or Boolean)
- Do not install the OS (will disable automatic start)
- opportunistic_locking (defaults to False, must be Boolean)
- Whether to employ opportunistic locking for nodes, meaning nodes already locked by another opcode won’t be considered for instance allocation (only when an iallocator is used)
- os_type (defaults to None, must be None or NonEmptyString)
- Operating system
- osparams (defaults to {}, must be Dictionary)
- OS parameters for instance
- pnode (defaults to None, must be None or NonEmptyString)
- Primary node
- snode (defaults to None, must be None or NonEmptyString)
- Secondary node
- source_handshake (defaults to None, must be None or List)
- Signed handshake from source (remote import only)
- source_instance_name (defaults to None, must be None or NonEmptyString)
- Source instance name (remote import only)
- source_shutdown_timeout (defaults to 120, must be Integer and EqualOrGreaterThanZero)
- How long source instance was given to shut down (remote import only)
- source_x509_ca (defaults to None, must be None or NonEmptyString)
- Source X509 CA in PEM format (remote import only)
- src_node (defaults to None, must be None or NonEmptyString)
- Source node for import
- src_path (defaults to None, must be None or NonEmptyString)
- Source directory for import
- start (defaults to True, must be Boolean)
- Whether to start instance after creation
- tags (defaults to [], must be List of NonEmptyString)
- Instance tags
- wait_for_sync (defaults to True, must be Boolean)
- Whether to wait for the disk to synchronize
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.
Job result:
List of NonEmptyString [instance nodes]
Instance-specific resource.
It supports the following commands: GET, DELETE.
Returns information about an instance, similar to the bulk output from
the instance list.
Returned fields: admin_state, beparams, ctime, custom_beparams, custom_hvparams, custom_nicparams, disk.sizes, disk_template, disk_usage, hvparams, mtime, name, network_port, nic.bridges, nic.ips, nic.links, nic.macs, nic.modes, nic.networks, nic.networks.names, oper_ram, oper_state, oper_vcpus, os, pnode, serial_no, snodes, status, tags, uuid.
Deletes an instance.
It supports the dry-run argument.
Job result:
None
It supports the following commands: GET.
Requests detailed information about the instance. An optional parameter,
static (bool), can be set to return only static information from the
configuration without querying the instance’s nodes. The result will be
a job id.
Job result:
Dictionary with keys of NonEmptyString and values of Dictionary
Reboots URI for an instance.
It supports the following commands: POST.
Reboots the instance.
The URI takes optional type=soft|hard|full and
ignore_secondaries=0|1 parameters.
type defines the reboot type. soft is just a normal reboot,
without terminating the hypervisor. hard means full shutdown
(including terminating the hypervisor process) and startup again.
full is like hard but also recreates the configuration from
ground up as if you would have done a gnt-instance shutdown and
gnt-instance start on it.
ignore_secondaries is a bool argument indicating if we start the
instance even if secondary disks are failing.
It supports the dry-run argument.
Job result:
None
Instance shutdown URI.
It supports the following commands: PUT.
Shutdowns an instance.
It supports the dry-run argument.
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- force (defaults to False, must be Boolean)
- Whether to force the operation
- ignore_offline_nodes (defaults to False, must be Boolean)
- Whether to ignore offline nodes
- no_remember (defaults to False, must be Boolean)
- Do not remember the state change
- timeout (defaults to 120, must be Integer and EqualOrGreaterThanZero)
- How long to wait for instance to shut down
Job result:
None
Instance startup URI.
It supports the following commands: PUT.
Startup an instance.
The URI takes an optional force=1|0 parameter to start the
instance even if secondary disks are failing.
It supports the dry-run argument.
Job result:
None
Installs the operating system again.
It supports the following commands: POST.
Returns a job ID.
Body parameters:
- os (string, required)
- Instance operating system.
- start (bool, defaults to true)
- Whether to start instance after reinstallation.
- osparams (dict)
- Dictionary with (temporary) OS parameters.
For backwards compatbility, this resource also takes the query
parameters os (OS template name) and nostartup (bool). New
clients should use the body parameters.
Replaces disks on an instance.
It supports the following commands: POST.
Returns a job ID.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disks (defaults to [], must be List of (Integer and EqualOrGreaterThanZero))
- Disk indexes
- early_release (defaults to False, must be Boolean)
- Whether to release locks as soon as possible
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for deciding new secondary node
- ignore_ipolicy (defaults to False, must be Boolean)
- Whether to ignore ipolicy violations
- mode (must be OneOf replace_on_primary, replace_new_secondary, replace_auto, replace_on_secondary)
- Replacement mode
- remote_node (defaults to None, must be None or NonEmptyString)
- New secondary node
Ganeti 2.4 and below used query parameters. Those are deprecated and
should no longer be used.
Job result:
None
Activate disks on an instance.
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:
List of ((Length 3) and (Item 0 is NonEmptyString, item 1 is NonEmptyString, item 2 is NonEmptyString))
Deactivate disks on an instance.
It supports the following commands: PUT.
Takes no parameters.
Job result:
None
Recreate disks of an instance. Supports the following commands:
POST.
Returns a job ID.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disks (defaults to [], must be (List of (Integer and EqualOrGreaterThanZero)) or (List of ((Length 2) and (Item 0 is (Integer and EqualOrGreaterThanZero [Disk index]), item 1 is (Dictionary with keys of NonEmptyString and values of (NonEmptyString or Integer) [Disk parameters] [Parameters])))))
- List of disk indexes (deprecated) or a list of tuples containing a disk index and a possibly empty dictionary with disk parameter changes
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for deciding new nodes
- nodes (defaults to [], must be List of NonEmptyString)
- New instance nodes, if relocation is desired
Job result:
None
Grows one disk of an instance.
Supports the following commands: POST.
Returns a job ID.
Body parameters:
- absolute (defaults to False, must be Boolean)
- Whether the amount parameter is an absolute target or a relative one
- amount (must be Integer and EqualOrGreaterThanZero)
- Amount of disk space to add (megabytes)
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- wait_for_sync (defaults to True, must be Boolean)
- Whether to wait for the disk to synchronize
Job result:
None
Prepares an export of an instance.
It supports the following commands: PUT.
Takes one parameter, mode, for the export mode. Returns a job ID.
Job result:
None or Dictionary
Exports an instance.
It supports the following commands: PUT.
Returns a job ID.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- destination (must be NonEmptyString or List)
- Destination information, depends on export mode
- destination_x509_ca (defaults to None, must be None or NonEmptyString)
- Destination X509 CA (remote export only)
- ignore_remove_failures (defaults to False, must be Boolean)
- Whether to ignore failures while removing instances
- mode (defaults to local, must be OneOf remote, local)
- Export mode
- remove_instance (defaults to False, must be Boolean)
- Whether to remove instance after export
- shutdown (defaults to True, must be Boolean)
- Whether to shutdown instance before export
- shutdown_timeout (defaults to 120, must be Integer and EqualOrGreaterThanZero)
- How long to wait for instance to shut down
- x509_key_name (defaults to None, must be None or List)
- Name of X509 key (remote export only)
Job result:
(Length 2) and (Item 0 is (Boolean [Finalizing status]), item 1 is (List of Boolean [Status for every exported disk]))
Migrates an instance.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- allow_failover (defaults to False, must be Boolean)
- Whether we can fallback to failover if migration is not possible
- allow_runtime_changes (defaults to True, must be Boolean)
- Allow runtime changes (eg. memory ballooning)
- cleanup (defaults to False, must be Boolean)
- Whether a previously failed migration should be cleaned up
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for deciding the target node for shared-storage instances
- ignore_ipolicy (defaults to False, must be Boolean)
- Whether to ignore ipolicy violations
- mode (defaults to None, must be None or (OneOf non-live, live))
- Migration mode
- target_node (defaults to None, must be None or NonEmptyString)
- Target node for shared-storage instances
Job result:
None
Does a failover of an instance.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for deciding the target node for shared-storage instances
- ignore_consistency (defaults to False, must be Boolean)
- Whether to ignore disk consistency
- ignore_ipolicy (defaults to False, must be Boolean)
- Whether to ignore ipolicy violations
- shutdown_timeout (defaults to 120, must be Integer and EqualOrGreaterThanZero)
- How long to wait for instance to shut down
- target_node (defaults to None, must be None or NonEmptyString)
- Target node for shared-storage instances
Job result:
None
Renames an instance.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- ip_check (defaults to False, must be Boolean)
- Whether to ensure instance’s IP address is inactive
- name_check (defaults to True, must be Boolean)
- Whether to check name
- new_name (must be NonEmptyString)
- New instance name
Job result:
NonEmptyString [New instance name]
Modifies an instance.
Supports the following commands: PUT.
Returns a job ID.
Body parameters:
- beparams (defaults to {}, must be Dictionary)
- Per-instance backend parameters
- conflicts_check (defaults to True, must be Boolean)
- Check for conflicting IPs
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disk_template (defaults to None, must be None or ((OneOf sharedfile, diskless, plain, blockdev, drbd, ext, file, rbd) and CheckFileStorage))
- Disk template for instance
- disks (defaults to [], must be (List of ((Length 3) and (Item 0 is (OneOf add, modify, remove), item 1 is (Integer [Disk index, can be negative, e.g. -1 for last disk]), item 2 is (Dictionary with keys of NonEmptyString and values of (NonEmptyString or Integer) [Disk parameters]))) [Recommended]) or (List of ((Length 2) and (Item 0 is ((OneOf add, remove) or (Integer and EqualOrGreaterThanZero)), item 1 is (Dictionary with keys of NonEmptyString and values of (NonEmptyString or Integer) [Disk parameters]))) [Deprecated]))
- List of disk changes; see nics
- force (defaults to False, must be Boolean)
- Whether to force the operation
- force_variant (defaults to False, must be Boolean)
- Whether to force an unknown OS variant
- hvparams (defaults to {}, must be Dictionary)
- Per-instance hypervisor parameters, hypervisor-dependent
- ignore_ipolicy (defaults to False, must be Boolean)
- Whether to ignore ipolicy violations
- nics (defaults to [], must be (List of ((Length 3) and (Item 0 is (OneOf add, modify, remove), item 1 is (Integer [Disk index, can be negative, e.g. -1 for last disk]), item 2 is (Dictionary with keys of (OneOf ip, mac, link, mode, network) and values of (None or NonEmptyString) [NIC parameters]))) [Recommended]) or (List of ((Length 2) and (Item 0 is ((OneOf add, remove) or (Integer and EqualOrGreaterThanZero)), item 1 is (Dictionary with keys of (OneOf ip, mac, link, mode, network) and values of (None or NonEmptyString) [NIC parameters]))) [Deprecated]))
- List of NIC changes: each item is of the form (op, index, settings), op is one of add, modify or remove, index can be either -1 to refer to the last position, or a zero-based index number; a deprecated version of this parameter used the form (op, settings), where 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
- offline (defaults to None, must be None or Boolean)
- Whether to mark instance as offline
- os_name (defaults to None, must be None or NonEmptyString)
- Change the instance’s OS without reinstalling the instance
- osparams (defaults to None, must be None or Dictionary)
- Per-instance OS parameters
- remote_node (defaults to None, must be None or NonEmptyString)
- Secondary node (used when changing disk template)
- runtime_mem (defaults to None, must be None or (Integer and GreaterThanZero))
- New runtime memory
- wait_for_sync (defaults to True, must be Boolean)
- Whether to wait for the disk to synchronize, when changing template
Job result:
List of ((Length 2) and (Item 0 is (NonEmptyString [name of changed parameter]), item 1 is (Anything [new value])))
Request information for connecting to instance’s console.
Supports the following commands: GET. Requires authentication with
one of the following options:
write, read.
Returns a dictionary containing information about the instance’s
console. Contained keys:
- instance
- Instance name
- kind
- Console type, one of ssh,
vnc, spice
or msg
- message
- Message to display (msg type only)
- host
- Host to connect to (ssh,
vnc or spice only)
- port
- TCP port to connect to (vnc or
spice only)
- user
- Username to use (ssh only)
- command
- Command to execute on machine (ssh only)
- display
- VNC display number (vnc only)
The /2/jobs resource.
It supports the following commands: GET.
Returns a dictionary of jobs.
Returns: a dictionary with jobs id and uri.
If the optional bool bulk argument is provided and set to a true value
(i.e. ?bulk=1), the output contains detailed information about jobs
as a list.
Returned fields for bulk requests (unlike other bulk requests, these
fields are not the same as for per-job requests):
end_ts, id, ops, opstatus, received_ts, start_ts, status, summary.
Individual job URI.
It supports the following commands: GET, DELETE.
Returns a dictionary with job parameters, containing the fields
end_ts, id, oplog, opresult, ops, opstatus, received_ts, start_ts, status, summary.
The result includes:
- id: job ID as a number
- status: current job status as a string
- ops: involved OpCodes as a list of dictionaries for each opcodes in
the job
- opstatus: OpCodes status as a list
- opresult: OpCodes results as a list
For a successful opcode, the opresult field corresponding to it will
contain the raw result from its LogicalUnit. In case an opcode
has failed, its element in the opresult list will be a list of two
elements:
- first element the error type (the Ganeti internal error name)
- second element a list of either one or two elements:
- the first element is the textual error description
- the second element, if any, will hold an error classification
The error classification is most useful for the OpPrereqError
error type - these errors happen before the OpCode has started
executing, so it’s possible to retry the OpCode without side
effects. But whether it make sense to retry depends on the error
classification:
- resolver_error
- 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
- Not enough resources (iallocator failure, disk space, memory,
etc.). If the resources on the cluster increase, the operation might
succeed.
- temp_insufficient_resources
- Simliar to insufficient_resources, but indicating the operation
should be attempted again after some time.
- wrong_input
- Wrong arguments (at syntax level). The operation will not ever be
accepted unless the arguments change.
- wrong_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
- Entity not found. For example, information has been requested for an
unknown instance.
- already_exists
- Entity already exists. For example, instance creation has been
requested for an already-existing instance.
- resource_not_unique
- Resource not unique (e.g. MAC or IP duplication).
- internal_error
- 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
- Environment error (e.g. node disk error). A gnt-cluster verify
should be run.
Note that in the above list, by entity we refer to a node or instance,
while by a resource we refer to an instance’s disk, or NIC, etc.
Cancel a not-yet-started job.
Waits for changes on a job. Takes the following body parameters in a
dict:
- fields
- The job fields on which to watch for changes
- previous_job_info
- 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
Returns None if no changes have been detected and a dict with two keys,
job_info and log_entries otherwise.
Nodes resource.
It supports the following commands: GET.
Returns a list of all nodes.
Example:
[
{
"id": "node1.example.com",
"uri": "\/nodes\/node1.example.com"
},
{
"id": "node2.example.com",
"uri": "\/nodes\/node2.example.com"
}
]
If the optional bool bulk argument is provided and set to a true value
(i.e ?bulk=1), the output contains detailed information about nodes
as a list.
Returned fields: cnodes, csockets, ctime, ctotal, dfree, drained, dtotal, group.uuid, master_candidate, master_capable, mfree, mnode, mtime, mtotal, name, ndparams, offline, pinst_cnt, pinst_list, pip, role, serial_no, sinst_cnt, sinst_list, sip, tags, uuid, vm_capable.
Example:
[
{
"pinst_cnt": 1,
"mfree": 31280,
"mtotal": 32763,
"name": "www.example.com",
"tags": [],
"mnode": 512,
"dtotal": 5246208,
"sinst_cnt": 2,
"dfree": 5171712,
"offline": false,
…
},
…
]
Returns information about a node.
It supports the following commands: GET.
Returned fields: cnodes, csockets, ctime, ctotal, dfree, drained, dtotal, group.uuid, master_candidate, master_capable, mfree, mnode, mtime, mtotal, name, ndparams, offline, pinst_cnt, pinst_list, pip, role, serial_no, sinst_cnt, sinst_list, sip, tags, uuid, vm_capable.
Powercycles a node. Supports the following commands: POST.
Returns a job ID.
Job result:
None or NonEmptyString
Evacuates instances off a node.
It supports the following commands: POST.
Returns a job ID. The result of the job will contain the IDs of the
individual jobs submitted to evacuate the node.
Body parameters:
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- early_release (defaults to False, must be Boolean)
- Whether to release locks as soon as possible
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for computing solution
- mode (must be OneOf all, secondary-only, primary-only)
- Node evacuation mode
- node_name (must be NonEmptyString)
- Node name
- remote_node (defaults to None, must be None or NonEmptyString)
- New secondary node
Up to and including Ganeti 2.4 query arguments were used. Those are no
longer supported. The new request can be detected by the presence of the
node-evac-res1 feature string.
Job result:
Dictionary containing none but the required key "jobs" (value List of ((Length 2) and (Item 0 is (Boolean [success]), item 1 is (String or JobId [Job ID if successful, error message otherwise]))) [List of submitted jobs])
Migrates all primary instances from a node.
It supports the following commands: POST.
If no mode is explicitly specified, each instances’ hypervisor default
migration mode will be used. Body parameters:
- allow_runtime_changes (defaults to True, must be Boolean)
- Allow runtime changes (eg. memory ballooning)
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- iallocator (defaults to None, must be None or NonEmptyString)
- Iallocator for deciding the target node for shared-storage instances
- ignore_ipolicy (defaults to False, must be Boolean)
- Whether to ignore ipolicy violations
- live (defaults to None, must be None or Boolean)
- Legacy setting for live migration, do not use
- mode (defaults to None, must be None or (OneOf non-live, live))
- Migration mode
- target_node (defaults to None, must be None or NonEmptyString)
- Target node for shared-storage instances
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 node-migrate-reqv1 feature string.
Job result:
Dictionary containing none but the required key "jobs" (value List of ((Length 2) and (Item 0 is (Boolean [success]), item 1 is (String or JobId [Job ID if successful, error message otherwise]))) [List of submitted jobs])
Manages node role.
It supports the following commands: GET, PUT.
The role is always one of the following:
- drained
- master-candidate
- offline
- regular
Note that the ‘master’ role is a special, and currently it can’t be
modified via RAPI, only via the command line (gnt-cluster
master-failover).
Returns the current node role.
Example:
Change the node role.
The request is a string which should be PUT to this URI. The result will
be a job id.
It supports the bool force argument.
Job result:
List of ((Length 2) and (Item 0 is (NonEmptyString [name of changed parameter]), item 1 is (Anything [new value])))
Modifies the parameters of a node. Supports the following commands:
POST.
Returns a job ID.
Body parameters:
- auto_promote (defaults to False, must be Boolean)
- Whether node(s) should be promoted to master candidate if necessary
- depends (defaults to None, must be None or (List of ((List or Tuple) and (Length 2) and (Item 0 is (JobId or RelativeJobId), item 1 is (List of (OneOf canceled, success, error))))))
- Job dependencies; if used through SubmitManyJobs relative (negative) job IDs can be used; see design document for details
- disk_state (defaults to None, must be None or Dictionary)
- Set disk states
- drained (defaults to None, must be None or Boolean)
- Whether the node should be marked as drained
- force (defaults to False, must be Boolean)
- Whether to force the operation
- hv_state (defaults to None, must be None or Dictionary)
- Set hypervisor states
- master_candidate (defaults to None, must be None or Boolean)
- Whether the node should become a master candidate
- master_capable (defaults to None, must be None or Boolean)
- Denote whether node can become master or master candidate
- ndparams (defaults to None, must be None or Dictionary)
- Set node parameters
- offline (defaults to None, must be None or Boolean)
- Whether the node should be marked as offline
- powered (defaults to None, must be None or Boolean)
- Whether the node should be marked as powered
- secondary_ip (defaults to None, must be None or NonEmptyString)
- Change node’s secondary IP address
- vm_capable (defaults to None, must be None or Boolean)
- Denote whether node can host instances
Job result:
List of ((Length 2) and (Item 0 is (NonEmptyString [name of changed parameter]), item 1 is (Anything [new value])))
Manages storage units on the node.
Requests a list of storage units on a node. Requires the parameters
storage_type (one of file,
lvm-pv or lvm-vg) and
output_fields. The result will be a job id, using which the result
can be retrieved.
Modifies storage units on the node.
Modifies parameters of storage units on the node. Requires the
parameters storage_type (one of file,
lvm-pv or 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.
Job result:
None
Repairs a storage unit on the node.
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.
Job result:
None
Requests resource information. Available fields can be found in man
pages and using /2/query/[resource]/fields. The resource is one of
node, group, network, cluster, lock, instance, job, export, extstorage, os. See the query2
design document for more details.
Supports the following commands: GET, PUT. Requires
authentication with one of the following options:
write, read.
Returns list of included fields and actual data. Takes a query parameter
named “fields”, containing a comma-separated list of field names. Does
not support filtering.
Returns list of included fields and actual data. The list of requested
fields can either be given as the query parameter “fields” or as a body
parameter with the same name. The optional body parameter “filter” can
be given and must be either null or a list containing filter
operators.
Request list of available fields for a resource. The resource is one of
node, group, network, cluster, lock, instance, job, export, extstorage, os. See the
query2 design document for more details.
Supports the following commands: GET.
Returns a list of field descriptions for available fields. Takes an
optional query parameter named “fields”, containing a comma-separated
list of field names.
OS resource.
It supports the following commands: GET.
Return a list of all OSes.
Can return error 500 in case of a problem. Since this is a costly
operation for Ganeti 2.0, it is not recommended to execute it too often.
Example:
The version resource.
This resource should be used to determine the remote API version and to
adapt clients accordingly.
It supports the following commands: GET.
Returns the remote API version. Ganeti 1.2 returned 1 and Ganeti 2.0
returns 2.