1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. Hardware Services
  3. Cluster

Cluster

The cluster commands set up clustering and manage clustered resources.

Table 6-1 Cluster Commands

Request Append to Path /hardware/v{1|2} Description

GET

/cluster

List cluster properties and resources

GET

/cluster/resources/resource-path

List properties for the specified cluster resource

PUT

/cluster/resources/resource-path

Modify the specified cluster resource

PUT

/cluster/failback

Fail back all resources assigned to the cluster peer

PUT

/cluster/takeover

Take over all resources assigned to the cluster peer

PUT

/cluster/unconfig

Unconfigure a clustered appliance to standalone mode

GET

/cluster/links

Show cluster card link status

PUT

/cluster/setup

Perform initial cluster setup

List Cluster Properties

The cluster command lists the current cluster configuration state and resource properties.

Example Request:

GET /api/hardware/v2/cluster HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 529
X-Zfssa-Api: 1.0

{
  "cluster": {
    "state": "AKCS_OWNER",
    "description": "Active (takeover completed)",
    "peer_asn": "d23331e6-41f4-6a15-ac09-a4353e33b43a",
    "peer_hostname": "peer-1",
    "peer_state": "AKCS_STRIPPED",
    "peer_description": "Ready (waiting for failback)",
    "resources": [
      {
        "owner": "peer-1",
        "type": "private",
        "user_label": "peer-1",
        "details": [
          "ipaddr"
        ],
        "href": "/api/hardware/v2/cluster/resources/net/vnic1"
      },
      {
        "owner": "peer-1",
        "type": "singleton",
        "user_label": "",
        "details": [
          "8.03T"
        ],
        "href": "/api/hardware/v2/cluster/resources/zfs/cas1"
      },
      {
        "owner": "peer-2",
        "type": "singleton",
        "user_label": "",
        "details": [
          "18.7T"
        ],
        "href": "/api/hardware/v2/cluster/resources/zfs/cas2"
      }
    ]
  }
}

Use the href property from one of the resources listed by the cluster command to list the properties for only that specific cluster resource, as shown in the following example: 

GET /api/hardware/v2/cluster/resources/net/vnic1 HTTP/1.1

Modify a Cluster Resource

Use the PUT request with the href property from one of the resources listed by the cluster command to set the properties for that cluster resource.

Cluster Link Status

The cluster/links command returns the current link status of the cluster card.

Before performing initial cluster setup, use cluster/links to ensure that all links are in the AKCIOS_ACTIVE state. A connection that is not in the AKCIOS_ACTIVE state can mean that the other system is restarting/rebooting, or it can mean that the link is not cabled correctly or the cluster cables are not secure in their connectors. For cluster cabling instructions, see Connecting Cluster Cables in Oracle ZFS Storage Appliance Cabling Guide, Release OS8.8.x.

The output of the cluster/links command is different for different controller models. For Oracle ZFS Storage ZS9-2 controllers, status is returned for two cluster I/O links. For all other controllers, status is returned for three cluster I/O links. For a description of cluster I/O links, see Cluster Interconnect I/O in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

GET /api/hardware/v2/cluster/links HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

Example Result for Oracle ZFS Storage ZS9-2:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 84

{
    "links": {
        "lio_dev/i40e0 = AKCIOS_ACTIVE\n
        lio_dev/i40e1 = AKCIOS_ACTIVE"
    }
}

Example Result for Oracle ZFS Storage ZS7-2 or Oracle ZFS Storage ZS5-2 controllers:

HTTP/1.1 200 OK
X-Zfssa-Appliance-Api: 1.0
Content-Type: application/json
Content-Length: 181

{
  "links": "\n\tclustron_ng3:0/clustron_uart:0 = AKCIOS_ACTIVE
            \n\tclustron_ng3:0/clustron_uart:1 = AKCIOS_ACTIVE
            \n\tclustron_ng3:0/dlpi:0 = AKCIOS_ACTIVE\n\n"
}

Other controllers show similar links output. The only difference is in the portion that precedes /clustron or /dlpi. For example, clustron3_ng3:0 in the preceding example is clustron3:0 for Oracle ZFS Storage ZS5-4 controllers, clustron2:0 for Oracle ZFS Storage ZS4-4 controllers, and clustron2_embedded:0 for Oracle ZFS Storage ZS3-2 controllers.

Cluster Management Commands

Cluster management includes failback, takeover, and unconfig. On success, the commands return HTTP status 202 (Accepted). If the cluster is not in the correct state to accept the command, an HTTP status 409 (Conflict) is returned.

Takeover is automatically attempted whenever peer failure is detected. Takeover can also be performed by an administrator.

Failback must be performed by an administrator. The failback operation is asynchronous. When the REST client sends a failback command, HTTP status 202 is returned when the request has been successfully received. To monitor failback progress, the client can listen for alerts or poll the cluster state.

For more information about takeover and failback, see Cluster Takeover and Failback in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Example Request:

PUT /api/hardware/v2/cluster/failback HTTP/1.1

Unconfiguring a cluster node configures the node to standalone operation. In general, do not unconfigure a cluster node yourself. Unconfiguring a cluster node is destructive. Unconfiguring involves more than just the unconfig command. For more information, see Unconfiguring a Cluster Node in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Cluster Setup

Setup is one step in initial cluster configuration. For more information, see Upgrading a Standalone Appliance to a Clustered Configuration (BUI) in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

The cluster/setup command performs initial cluster configuration for the system. Specify values for the nodename and password properties. If setup is successful, HTTP status 202 Accepted is returned.

The cluster/setup command fails unless both of the following conditions exist:

  • All cluster links are in the AKCIOS_ACTIVE state. See Cluster Link Status.

  • The peer is powered on but not configured.

Note:

An initial cluster configuration setup can take several minutes to complete.

Example Request:

PUT /api/hardware/v2/cluster/setup HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: zfs-storage.example.com:215
Accept: application/json

{"nodename": "zfs-storage-2", "password": "password"}