Product documentation
Develop for XenServer
8 Citrix Hypervisor 8.2 CU1
View PDF

Class: Cluster

June 19, 2024
Contributed by: 
X X

Cluster-wide Cluster metadata

Fields for class: Cluster

Field Type Qualifier Description
allowed_operations cluster_operation set 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.
cluster_config (string -> string) map RO/constructor Contains read-only settings for the cluster, such as timeouts and other options. It can only be set at cluster create time
cluster_hosts Cluster_host ref set RO/runtime A list of the cluster_host objects associated with the Cluster
cluster_stack string RO/constructor Simply the string ‘corosync’. No other cluster stacks are currently supported
cluster_stack_version int 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.
cluster_token string RO/constructor The secret key used by xapi-clusterd when it talks to itself on other hosts
current_operations (string -> cluster_operation) map 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.
is_quorate bool RO/runtime Whether the cluster stack thinks the cluster is quorate
live_hosts int RO/runtime Current number of live hosts, according to the cluster stack
other_config (string -> string) map RW Additional configuration
pending_forget string set RO/runtime Internal field used by Host.destroy to store the IP of cluster members marked as permanently dead but not yet removed
pool_auto_join bool RO/constructor True if automatically joining new pool members to the cluster. This will be true in the first release
quorum int RO/runtime Number of live hosts in order to be quorate
token_timeout float RO/constructor The corosync token timeout in seconds
token_timeout_coefficient float RO/constructor The corosync token timeout coefficient in seconds
uuid string RO/runtime Unique identifier/object reference

RPCs associated with class: Cluster

RPC name: add_to_other_config

Overview:

Add the given key-value pair to the other_config field of the given Cluster.

Signature:

void add_to_other_config (session ref session_ref, Cluster ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref 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

Return Type: void

RPC name: create

Overview:

Creates a Cluster object and one Cluster_host object as its first member

Signature:

Cluster ref create (session ref session_ref, PIF ref PIF, string cluster_stack, bool pool_auto_join, float token_timeout, float token_timeout_coefficient)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref 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

Return Type: Cluster ref

the new Cluster

Possible Error Codes: INVALID_CLUSTER_STACK, INVALID_VALUE, PIF_ALLOWS_UNPLUG, REQUIRED_PIF_IS_UNPLUGGED

RPC name: destroy

Overview:

Destroys a Cluster object and the one remaining Cluster_host member

Signature:

void destroy (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self the Cluster to destroy

Minimum Role: pool-operator

Return Type: void

Possible Error Codes: CLUSTER_DOES_NOT_HAVE_ONE_NODE, CLUSTER_STACK_IN_USE

RPC name: get_all

Overview:

Return a list of all the Clusters known to the system.

Signature:

Cluster ref set get_all (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: Cluster ref set

references to all objects

RPC name: get_all_records

Overview:

Return a map of Cluster references to Cluster records for all Clusters known to the system.

Signature:

(Cluster ref -> Cluster record) map get_all_records (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: (Cluster ref -> Cluster record) map

records of all objects

RPC name: get_allowed_operations

Overview:

Get the allowed_operations field of the given Cluster.

Signature:

cluster_operation set get_allowed_operations (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: cluster_operation set

value of the field

RPC name: get_by_uuid

Overview:

Get a reference to the Cluster instance with the specified UUID.

Signature:

Cluster ref get_by_uuid (session ref session_ref, string uuid)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return

Minimum Role: read-only

Return Type: Cluster ref

reference to the object

RPC name: get_cluster_config

Overview:

Get the cluster_config field of the given Cluster.

Signature:

(string -> string) map get_cluster_config (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_cluster_hosts

Overview:

Get the cluster_hosts field of the given Cluster.

Signature:

Cluster_host ref set get_cluster_hosts (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: Cluster_host ref set

value of the field

RPC name: get_cluster_stack

Overview:

Get the cluster_stack field of the given Cluster.

Signature:

string get_cluster_stack (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_cluster_stack_version

Overview:

Get the cluster_stack_version field of the given Cluster.

Signature:

int get_cluster_stack_version (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_cluster_token

Overview:

Get the cluster_token field of the given Cluster.

Signature:

string get_cluster_token (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_current_operations

Overview:

Get the current_operations field of the given Cluster.

Signature:

(string -> cluster_operation) map get_current_operations (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: (string -> cluster_operation) map

value of the field

RPC name: get_is_quorate

Overview:

Get the is_quorate field of the given Cluster.

Signature:

bool get_is_quorate (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_live_hosts

Overview:

Get the live_hosts field of the given Cluster.

Signature:

int get_live_hosts (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_network

Overview:

Returns the network used by the cluster for inter-host communication, i.e. the network shared by all cluster host PIFs

Signature:

network ref get_network (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self the Cluster with the network

Minimum Role: read-only

Return Type: network ref

network of cluster

RPC name: get_other_config

Overview:

Get the other_config field of the given Cluster.

Signature:

(string -> string) map get_other_config (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_pending_forget

Overview:

Get the pending_forget field of the given Cluster.

Signature:

string set get_pending_forget (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: string set

value of the field

RPC name: get_pool_auto_join

Overview:

Get the pool_auto_join field of the given Cluster.

Signature:

bool get_pool_auto_join (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_quorum

Overview:

Get the quorum field of the given Cluster.

Signature:

int get_quorum (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: int

value of the field

RPC name: get_record

Overview:

Get a record containing the current state of the given Cluster.

Signature:

Cluster record get_record (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: Cluster record

all fields from the object

RPC name: get_token_timeout

Overview:

Get the token_timeout field of the given Cluster.

Signature:

float get_token_timeout (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: float

value of the field

RPC name: get_token_timeout_coefficient

Overview:

Get the token_timeout_coefficient field of the given Cluster.

Signature:

float get_token_timeout_coefficient (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: float

value of the field

RPC name: get_uuid

Overview:

Get the uuid field of the given Cluster.

Signature:

string get_uuid (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: pool_create

Overview:

Attempt to create a Cluster from the entire pool

Signature:

Cluster ref pool_create (session ref session_ref, network ref network, string cluster_stack, float token_timeout, float token_timeout_coefficient)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref 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

Return Type: Cluster ref

the new Cluster

RPC name: pool_destroy

Overview:

Attempt to destroy the Cluster_host objects for all hosts in the pool and then destroy the Cluster.

Signature:

void pool_destroy (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self The cluster to destroy.

Minimum Role: pool-operator

Return Type: void

Possible Error Codes: CLUSTER_STACK_IN_USE, CLUSTERING_DISABLED, CLUSTER_HOST_IS_LAST

RPC name: pool_force_destroy

Overview:

Attempt to force destroy the Cluster_host objects, and then destroy the Cluster.

Signature:

void pool_force_destroy (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self The cluster to force destroy.

Minimum Role: pool-operator

Return Type: void

Possible Error Codes: CLUSTER_FORCE_DESTROY_FAILED

RPC name: pool_resync

Overview:

Resynchronise the cluster_host objects across the pool. Creates them where they need creating and then plugs them

Signature:

void pool_resync (session ref session_ref, Cluster ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self The cluster to resync

Minimum Role: pool-operator

Return Type: void

RPC name: remove_from_other_config

Overview:

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.

Signature:

void remove_from_other_config (session ref session_ref, Cluster ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
string key Key to remove

Minimum Role: pool-operator

Return Type: void

RPC name: set_other_config

Overview:

Set the other_config field of the given Cluster.

Signature:

void set_other_config (session ref session_ref, Cluster ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
Cluster ref self reference to the object
(string -> string) map value New value to set

Minimum Role: pool-operator

Return Type: void

Class: Cluster
June 19, 2024
Contributed by: 
X X
June 19, 2024
Contributed by: 
X X

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.