DocsKnowledge BaseAPI Explorer
Documentation›ZCF›ZStack Cloud›Explore more›CLI Command ManualZCF
Document navigation

Cluster

Overview

A cluster is a logical group of hosts (compute nodes). In a real data center, a cluster usually maps to a rack.

When you plan a cluster, note that:
  • All hosts in the same cluster must be installed with the same operating system.
  • All hosts in the same cluster must have the same network configuration.
  • All hosts in the same cluster must be able to access the same primary storage.
  • Before a cluster can provide VM services, the cluster must have a primary storage and an L2 network attached.
  • The scale of a cluster, which is the maximum number of hosts that the cluster can contain, is not limited.

The relationship between a typical cluster and its associated resources is as follows:

Cluster | Zone

You can create more than one cluster in a zone, and allocate newly created hosts to different clusters as needed.

Cluster | Primary Storage and L2 Network

You can attach primary storage and L2 networks to or detach them from a cluster. The following diagram shows the relationship between cluster and primary storage, L2 network.
Figure 1. Relationship Between Cluster and Primary Storage, L2 Network


Note:
When you attach a primary storage and an L2 network to a cluster, note that:
  1. Cluster | Primary Storage
    • A primary storage can be attached to one or more clusters.
    • A cluster can have one or more primary storage attached.
      The following are primary storage of the same type that a cluster can have:
      • A cluster can have one or more LocalStorage primary storage attached.
      • A cluster can have one or more NFS primary storage attached.
      • A cluster can have one or more SharedBlock primary storage attached.
      • A cluster can have one SharedMountPoint (SMP) primary storage attached.
      • A cluster can have only one Ceph primary storage attached.
      • A cluster can have only one AliyunNAS primary storage attached.
      • A cluster can have only one AliyunEBS primary storage attached.
      The following are combinations of primary storages that a cluster can have:
      • A cluster can have both a LocalStorage and an NFS primary storage attached.
      • A cluster can have both a LocalStorage and an SMP primary storage attached.
      • A cluster can have both a LocalStorage and a SharedBlock primary storage attached.
      • A cluster can have both a Ceph and a maximum of three LocalStorage primary storage attached.
      • A cluster can have both a Ceph and a SharedBlock primary storage attached.
      • A cluster can have both a Ceph and more than one SharedBlock primary storage attached.
      The following table lists the relationship between a primary storage and a cluster.
      Primary Storage Cluster
      LocalStorage A cluster can have one or more LocalStorage primary storage attached.
      NFS A cluster can have one or more NFS primary storage attached.
      SharedBlock A cluster can have one or more SharedBlock primary storage attached.
      SMP A cluster can have one SMP primary storage attached.
      Ceph A cluster can have only one Ceph primary storage attached.
      AliyunNAS A cluster can have only one AliyunNAS primary storage attached.
      AliyunEBS A cluster can have only one AliyunEBS primary storage attached.
      LocalStorage + NFS A cluster can have one LocalStorage and one NFS primary storage attached.
      LocalStorage + SMP A cluster can have one LocalStorage and one SMP primary storage attached.
      LocalStorage + SharedBlock A cluster can have one LocalStorage and one SharedBlock primary storage attached.
      Ceph + LocalStorage A cluster can have both a Ceph and a maximum of three LocalStorage primary storage attached.
      Ceph + SharedBlock
      • A cluster can have one Ceph and one SharedBlock primary storage attached.
      • A cluster can have one Ceph and multiple SharedBlock primary storage attached.
    • When you attach multiple LocalStorage primary storage to a cluster, partition the corresponding URLs on the hosts before you add hosts and primary storage, and make sure that each LocalStorage is deployed on an exclusive logical volume or physical disk.
    • A primary storage can be accessed by all hosts in the cluster to which the primary storage belongs.
    • If a primary storage cannot be accessed by hosts in the cluster due to network typology changes in the data center, you can detach the primary storage from the cluster.
  2. Cluster | L2 Network
    • A cluster can have one or more L2 networks attached. Also, an L2 network can be attached to one or more clusters.
    • A cluster can have a VXLAN pool attached. The VNIs in the VXLAN pool can be used to create different VXLAN networks.
    • One NIC can be used to create only one NoVlan network.
    • For VLAN networks, different VLAN IDs represent different L2 networks.
    • If hosts in a cluster no longer exist in the layer 2 broadcast domain of an L2 network due to network typology changes in the data center, you can detach the L2 network from the cluster.

Cluster | Backup Storage

No direct dependency exists between a cluster and a backup storage. A backup storage can provide services for multiple clusters.

The following table lists the relationship between primary storage (PS) and backup storage (BS).
PS/BS ImageStore Ceph
LocalStorage ○ ×
NFS ○ ×
SMP ○ ×
Ceph ○ ○
SharedBlock ○ ×
  • When primary storage are LocalStorage, NFS, or SMP, the default type for backup storage is ImageStore.
  • When primary storage are NFS or SMP, you can manually mount the corresponding shared directories to the local directories of the corresponding backup storage. In this regard, both primary storage and backup storage can use the network shared storage.
  • When primary storage is Ceph, you can use the primary storage in the same Ceph cluster as backup storage. You can also use the ImageStore primary storage as backup storage.
  • When primary storage is SharedBlock, the default type for backup storage is ImageStore.
  • When primary storage is AliyunNAS, the default type for backup storage is ImageStore.
  • When primary storage is AliyunEBS, the default type for backup storage is AliyunEBS.

Inventory

Properties

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Property. 0.6
name The name. For more information, see Resource Property. 0.6
description The description. For more information, see Resource Property. Yes 0.6
hypervisorType The hypervisor type. For more information, see Cluster Hypervisor Type.
  • KVM
 0.6
state The state. For more information, see Resource Property.
  • Enabled
  • Disabled
 0.6
zoneUuid The UUID of the zone to which the cluster belongs. For more information, see Zone. 0.6
createDate The creation date. For more information, see Resource Property. 0.6
lastOpDate The last operation date. For more information, see Resource Property. 0.6
type The reserved field. 0.6
userTags The user tags. For more information, see CreateUserTag. Yes 0.6
systemTags The system tags. For more information, see CreateSystemTag. Yes 0.6

Sample

{
    "inventories":
        {
            "createDate": "Oct 30, 2017 1:50:00 PM",
            "description": "",
            "hypervisorType": "KVM",
            "lastOpDate": "Oct 30, 2017 1:50:00 PM",
            "name": "Cluster-1",
            "state": "Enabled",
            "type": "zstack",
            "uuid": "5c3699713b1c43219de14df7545f24d0",
            "zoneUuid": "e59b71e99d8a4ea1952b578388b8cd1d"
        }
}

Hypervisor Type

Hypervisor type indicates what kind of hypervisor (operating system) is installed on hosts in a cluster.

State

A cluster has the following two states: Enabled and Disabled, which is similar to Zone. When you change the state of a cluster, the change operation will be cascaded to all hosts in the cluster. For example, if you disable a cluster, you will also disable all hosts in the cluster.

Operations

CreateCluster

Creates a cluster. For example,
CreateCluster name=cluster1 hypervisorType=KVM zoneUuid=1b830f5bd1cb469b821b4b77babfdd6f

Parameters

Name Description Optional Valid Value Starting Version
zoneUuid The parent zone UUID. 0.6
name The resource name. For more information, see Resource Property. 0.6
resourceUuid The resource UUID. For more information, see CreateUserTag. Yes 0.6
description The resource description. For more information, see Resource Property. Yes 0.6
hypervisorType The hypervisor type. For more information, see Cluster Hypervisor Type. Yes
  • KVM
  • Simulator
 0.6
type The reserved field for internal use. Yes
  • zstack
 4.0.0
architecture Yes
  • x86_64
  • aarch64
  • mips64el
 4.0.0
tagUuids The tag UUIDs. 4.0.0
userTags The user tags. For more information, see CreateUserTag. The resource type is ClusterVO. Yes 0.6
systemTags The system tags. For more information, see CreateSystemTag. The resource type is ClusterVO. Yes 0.6
timeout Yes

DeleteCluster

Deletes a cluster. For example,
DeleteCluster uuid=c1bd173d5cd84f0e9e7c47195ae27ec6

Parameters

Name Description Optional Valid Value Starting Version
uuid The cluster UUID. 0.6
deleteMode The delete mode. For more information, see DeleteResources. Yes
  • Permissive
  • Enforcing
 0.6
userTags The user tags. For more information, see CreateUserTag. The resource type is ClusterVO. Yes 0.6
systemTags The system tags. For more information, see CreateSystemTag. The resource type is ClusterVO. Yes 0.6
timeout Yes

QueryCluster

Queries a cluster. For example,
QueryCluster hypervisorType=KVM
QueryCluster primaryStorage.availableCapacity>=100000000

Primitive Fields of Query

See Cluster Inventory.

Nested and Expanded Fields of Query

Field Inventory Description Starting Version
zone Zone Inventory The parent zone. 0.6
host Host Inventory The host that belongs to the cluster. 0.6
vmInstance VM Instance Inventory The VM instance that belongs to the cluster. 0.6
l2Network L2 Network Inventory The L2 network that is attached to the cluster. 0.6
l2VlanNetwork l2VlanNetwork Inventory The L2 network that is attached to the cluster. This L2 network uses VLAN to create layer 2 broadcast domains. 0.6
primaryStorage Primary Storage Inventory The primary storage that is attached to the cluster. 0.6

UpdateCluster

Updates a cluster. For example,
UpdateCluster uuid=26aad17353dd4de0ac7bc5540d76da23 name=test

Parameters

Name Description Optional Valid Value Starting Version
uuid The cluster UUID. 0.6
name The resource name. For more information, see Resource Property. Yes 0.6
description The resource description. For more information, see Resource Property. Yes 0.6
userTags The user tags. For more information, see CreateUserTag. The resource type is ClusterVO. Yes 0.6
systemTags The system tags. For more information, see CreateSystemTag. The resource type is ClusterVO. Yes 0.6
timeout Yes

ChangeClusterState

Changes the state of a cluster. For example,
ChangeClusterState uuid=26aad17353dd4de0ac7bc5540d76da23 stateEvent=enable

Parameters

Name Description Optional Valid Value Starting Version
uuid The cluster UUID. 0.6
stateEvent The state event. Yes
  • enable
  • disable
 0.6
userTags The user tags. For more information, see CreateUserTag. The resource type is ClusterVO. Yes 0.6
systemTags The system tags. For more information, see CreateSystemTag. The resource type is ClusterVO. Yes 0.6
timeout Yes

UpdateClusterOS

Updates the operating system of hosts in a cluster. For example,
UpdateClusterOS uuid=fb498a6086ea43449f33d5bbb9daa73e

Parameters

Name Description Optional Valid Value Starting Version
uuid The cluster UUID. 0.6
excludePackages The packages not to be upgraded. Yes 3.7.0
updatePackages The packages to be upgraded. Yes 3.7.0
releaseVersion The release version of the operating system. Yes 3.7.0
resourceUuid Yes 3.7.0
tagUuids The tag UUID list. Yes 3.7.0
systemTags The system tags. For more information, see CreateSystemTag. The resource type is ClusterVO. Yes 0.6
userTags The user tags. For more information, see CreateUserTag. The resource type is ClusterVO. Yes 0.6
timeout Yes

Tags

User Tags

You can create a user tag on a cluster by using resourceType=ClusterVO. For example,
CreateUserTag resourceType=ClusterVO resourceUuid=80a979b9e0234564a22a4cca8c1dff43 tag=secureCluster

System Tags

Reserved Capacity
Tag Description Example Starting Version
host::reservedMemory::{capacity} See Host Capacity Reservation. host::reservedMemory::1G 0.6
PreviousZoneNextHost
CLI Command Manual | 4.8.38 | ZStack Cloud · ZCF | ZStack Resource Center