Class: Cluster
Cluster-wide Cluster metadata
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) |
Enums
cluster_operation
| Values: | add | adding a new member to the cluster |
| remove | removing a member from the cluster | |
| enable | enabling any cluster member | |
| disable | disabling any cluster member | |
| destroy | completely destroying a cluster |
Fields
enum cluster_operation set
allowed_operations
[RO/runtime]
list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
| Default value: | {} | |
| Published in: | XenServer 4.0 (rio) | list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client. |
(string → string) map
cluster_config
[RO/constructor]
Contains read-only settings for the cluster, such as timeouts and other options. It can only be set at cluster create time
| Default value: | {} | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Cluster_host ref set
cluster_hosts
[RO/runtime]
A list of the cluster_host objects associated with the Cluster
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) |
string
cluster_stack
[RO/constructor]
Simply the string 'corosync'. No other cluster stacks are currently supported
| Default value: | "corosync" | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
int
cluster_stack_version
[RO/constructor]
Version of cluster stack, not writable via the API. Defaulting to 2 for backwards compatibility when upgrading from a cluster without this field, which means it is necessarily running version 2 of corosync, the only cluster stack supported so far.
| Default value: | 2 | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
string
cluster_token
[RO/constructor]
The secret key used by xapi-clusterd when it talks to itself on other hosts
| Default value: | "" | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
(string → enum cluster_operation) map
current_operations
[RO/runtime]
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
| Default value: | {} | |
| Published in: | XenServer 4.0 (rio) | links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task. |
Prototype
bool
is_quorate
[RO/runtime]
Whether the cluster stack thinks the cluster is quorate
| Default value: | false | |
| Prototyped in: | XAPI 24.3.0 (24.3.0) | |
Prototype
int
live_hosts
[RO/runtime]
Current number of live hosts, according to the cluster stack
| Default value: | 0 | |
| Prototyped in: | XAPI 24.3.0 (24.3.0) | |
(string → string) map
other_config
[RW]
Additional configuration
| Default value: | {} | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
string set
pending_forget
[RO/runtime]
Internal field used by Host.destroy to store the IP of cluster members marked as permanently dead but not yet removed
| Default value: | {} | |
| Published in: | XenServer 7.6 (lima) | |
bool
pool_auto_join
[RO/constructor]
True if automatically joining new pool members to the cluster. This will be `true` in the first release
| Default value: | true | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Prototype
int
quorum
[RO/runtime]
Number of live hosts in order to be quorate
| Default value: | 0 | |
| Prototyped in: | XAPI 24.3.0 (24.3.0) | |
float
token_timeout
[RO/constructor]
The corosync token timeout in seconds
| Default value: | 20. | |
| Prototyped in: | XenServer 7.5 (kolkata) | the unit is milliseconds |
| Changed in: | XenServer 7.6 (lima) | the unit is now seconds |
| Published in: | XenServer 7.6 (lima) | |
float
token_timeout_coefficient
[RO/constructor]
The corosync token timeout coefficient in seconds
| Default value: | 1. | |
| Prototyped in: | XenServer 7.5 (kolkata) | the unit is milliseconds |
| Changed in: | XenServer 7.6 (lima) | the unit is now seconds |
| Published in: | XenServer 7.6 (lima) | |
string
uuid
[RO/runtime]
Unique identifier/object reference
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) |
Messages
void
add_to_other_config
(session ref, Cluster ref, string, string)
Add the given key-value pair to the other_config field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| string key | Key to add | |
| string value | Value to add | |
| Minimum role: | pool-operator | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Cluster ref
create
(session ref, PIF ref, string, bool, float, float)
Creates a Cluster object and one Cluster_host object as its first member
| Parameters: | session ref session_id | Reference to a valid session |
| PIF ref PIF | The PIF to connect the cluster's first cluster_host to | |
| string cluster_stack | simply the string 'corosync'. No other cluster stacks are currently supported | |
| bool pool_auto_join | true if xapi is automatically joining new pool members to the cluster | |
| float token_timeout | Corosync token timeout in seconds | |
| float token_timeout_coefficient | Corosync token timeout coefficient in seconds | |
| Minimum role: | pool-operator | |
| Result: | the new Cluster | |
| Errors: | INVALID_CLUSTER_STACK | The cluster stack provided is not supported. |
| INVALID_VALUE | The value given is invalid | |
| PIF_ALLOWS_UNPLUG | The operation you requested cannot be performed because the specified PIF allows unplug. | |
| REQUIRED_PIF_IS_UNPLUGGED | The operation you requested cannot be performed because the specified PIF is currently unplugged. | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
void
destroy
(session ref, Cluster ref)
Destroys a Cluster object and the one remaining Cluster_host member
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | the Cluster to destroy | |
| Minimum role: | pool-operator | |
| Errors: | CLUSTER_DOES_NOT_HAVE_ONE_NODE | An operation failed as it expected the cluster to have only one node but found multiple cluster_hosts. |
| CLUSTER_STACK_IN_USE | The cluster stack is still in use by at least one plugged PBD. | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Cluster ref set
get_all
(session ref)
Return a list of all the Clusters known to the system.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | references to all objects | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
(Cluster ref → Cluster record) map
get_all_records
(session ref)
Return a map of Cluster references to Cluster records for all Clusters known to the system.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | records of all objects | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
enum cluster_operation set
get_allowed_operations
(session ref, Cluster ref)
Get the allowed_operations field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client. |
Cluster ref
get_by_uuid
(session ref, string)
Get a reference to the Cluster instance with the specified UUID.
| Parameters: | session ref session_id | Reference to a valid session |
| string uuid | UUID of object to return | |
| Minimum role: | read-only | |
| Result: | reference to the object | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
(string → string) map
get_cluster_config
(session ref, Cluster ref)
Get the cluster_config field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Cluster_host ref set
get_cluster_hosts
(session ref, Cluster ref)
Get the cluster_hosts field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
string
get_cluster_stack
(session ref, Cluster ref)
Get the cluster_stack field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
int
get_cluster_stack_version
(session ref, Cluster ref)
Get the cluster_stack_version field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
string
get_cluster_token
(session ref, Cluster ref)
Get the cluster_token field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
(string → enum cluster_operation) map
get_current_operations
(session ref, Cluster ref)
Get the current_operations field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task. |
Prototype
bool
get_is_quorate
(session ref, Cluster ref)
Get the is_quorate field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XAPI 24.3.0 (24.3.0) | |
Prototype
int
get_live_hosts
(session ref, Cluster ref)
Get the live_hosts field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XAPI 24.3.0 (24.3.0) | |
network ref
get_network
(session ref, Cluster ref)
Returns the network used by the cluster for inter-host communication, i.e. the network shared by all cluster host PIFs
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | the Cluster with the network | |
| Minimum role: | read-only | |
| Result: | network of cluster | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
(string → string) map
get_other_config
(session ref, Cluster ref)
Get the other_config field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
string set
get_pending_forget
(session ref, Cluster ref)
Get the pending_forget field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 7.6 (lima) | |
bool
get_pool_auto_join
(session ref, Cluster ref)
Get the pool_auto_join field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Prototype
int
get_quorum
(session ref, Cluster ref)
Get the quorum field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XAPI 24.3.0 (24.3.0) | |
Cluster record
get_record
(session ref, Cluster ref)
Get a record containing the current state of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | all fields from the object | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
float
get_token_timeout
(session ref, Cluster ref)
Get the token_timeout field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | the unit is milliseconds |
| Changed in: | XenServer 7.6 (lima) | the unit is now seconds |
| Published in: | XenServer 7.6 (lima) | |
float
get_token_timeout_coefficient
(session ref, Cluster ref)
Get the token_timeout_coefficient field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | the unit is milliseconds |
| Changed in: | XenServer 7.6 (lima) | the unit is now seconds |
| Published in: | XenServer 7.6 (lima) | |
string
get_uuid
(session ref, Cluster ref)
Get the uuid field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
Cluster ref
pool_create
(session ref, network ref, string, float, float)
Attempt to create a Cluster from the entire pool
| Parameters: | session ref session_id | Reference to a valid session |
| network ref network | the single network on which corosync carries out its inter-host communications | |
| string cluster_stack | simply the string 'corosync'. No other cluster stacks are currently supported | |
| float token_timeout | Corosync token timeout in seconds | |
| float token_timeout_coefficient | Corosync token timeout coefficient in seconds | |
| Minimum role: | pool-operator | |
| Result: | the new Cluster | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
void
pool_destroy
(session ref, Cluster ref)
Attempt to destroy the Cluster_host objects for all hosts in the pool and then destroy the Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | The cluster to destroy. | |
| Minimum role: | pool-operator | |
| Errors: | CLUSTER_STACK_IN_USE | The cluster stack is still in use by at least one plugged PBD. |
| CLUSTERING_DISABLED | An operation was attempted while clustering was disabled on the cluster_host. | |
| CLUSTER_HOST_IS_LAST | The last cluster host cannot be destroyed. Destroy the cluster instead | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
void
pool_force_destroy
(session ref, Cluster ref)
Attempt to force destroy the Cluster_host objects, and then destroy the Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | The cluster to force destroy. | |
| Minimum role: | pool-operator | |
| Errors: | CLUSTER_FORCE_DESTROY_FAILED | Force destroy failed on a Cluster_host while force destroying the cluster. |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
void
pool_resync
(session ref, Cluster ref)
Resynchronise the cluster_host objects across the pool. Creates them where they need creating and then plugs them
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | The cluster to resync | |
| Minimum role: | pool-operator | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
void
remove_from_other_config
(session ref, Cluster ref, string)
Remove the given key and its corresponding value from the other_config field of the given Cluster. If the key is not in that Map, then do nothing.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| string key | Key to remove | |
| Minimum role: | pool-operator | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |
void
set_other_config
(session ref, Cluster ref, (string → string) map)
Set the other_config field of the given Cluster.
| Parameters: | session ref session_id | Reference to a valid session |
| Cluster ref self | reference to the object | |
| (string → string) map value | New value to set | |
| Minimum role: | pool-operator | |
| Prototyped in: | XenServer 7.5 (kolkata) | |
| Published in: | XenServer 7.6 (lima) | |