Module netapp_ontap.resources.cluster

Copyright © 2022 NetApp Inc. All rights reserved.

Overview

You can use this API to create a cluster, update cluster-wide configurations, and retrieve the current configuration details.

Creating a cluster

You can create a new cluster by issuing a POST request to /cluster. Parameters are provided in the body of the POST request to configure cluster-wide settings and add nodes during the cluster setup.

Fields used for creating a cluster

The fields used for the cluster APIs fall into the following categories:

  • Required cluster-wide configuration
  • Optional cluster-wide configuration

Required cluster-wide configuration

The following fields are always required for any POST /cluster request:

  • name
  • password

Optional cluster-wide configuration

The following fields are used to set up additional cluster-wide configurations:

  • location
  • contact
  • dns_domains
  • name_servers
  • ntp_servers
  • timezone
  • license
  • configuration_backup
  • management_interface
  • nodes

Nodes field

The nodes field specifies the nodes to join to the cluster. To use this API, all nodes must run the same version of ONTAP. If you do not specify a node, the cluster is configured with one node added. The REST request is issued to the node that is added to the cluster. If you specify one node, do not use the "node.cluster_interface.ip.address" field. If you specify multiple nodes, specify the node to which the REST request is issued in addition to the remote nodes. Use the "node.cluster_interface.ip.address" field to identify each node. All other node fields are optional in all cases. If you provide a field for one node, you need to provide the same field for all nodes.

Node networking fields

The cluster management interface and each node management interface use the cluster management interface subnet mask and gateway. For advanced configurations in which the cluster and node management interfaces are on different subnets, use the /network/ip/interface APIs to configure network interfaces after setup is complete. The management interfaces are used to communicate with the name servers and NTP servers. The address family of the name servers and NTP servers must match the management interfaces address family.

Single node cluster field

When the "single_node_cluster" field is set to "true", the cluster is created in single node cluster mode. You can provide a node field for this node for node-specific configuration but do not use the "node.cluster_interface.ip.address" field. Storage failover is configured to non-HA mode, and ports used for cluster ports are moved to the default IPspace. This might cause the node to reboot during setup. While a node reboots, the RESTful interface might not be available. See "Connection failures during cluster create" for more information.

When the "create_recommended_aggregates" parameter is set to "true", aggregates based on an optimal layout recommended by the system are created on each of the nodes in the cluster. The default setting is "false".


Performance monitoring

Performance of the cluster can be monitored by the metric.* and statistics.* fields. These fields show the performance of the cluster in terms of IOPS, latency and throughput. The metric.* fields denote an average, whereas the statistics.* fields denote a real-time monotonically increasing value aggregated across all nodes.


Monitoring cluster create status

Errors before the job starts

Configuration in the POST /cluster request is validated before the cluster create job starts. If an invalid configuration is found, an HTTP error code in the 4xx range is returned. No cluster create job is started.

Polling on the job

After a successful POST /cluster request is issued, an HTTP error code of 202 is returned along with a job UUID and link in the body of the response. The cluster create job continues asynchronously and is monitored with the job UUID using the /cluster/jobs API. The "message" field in the response of the GET /cluster/jobs/{uuid} request shows the current step in the job, and the "state" field shows the overall state of the job.

Errors during the job

If a failure occurs during the cluster create job, the job body provides details of the error along with error code fields. See the error table under "Responses" in the POST /cluster documentation for common error codes and descriptions.

Rerunning POST /cluster

The POST /cluster request can be rerun if errors occur. When rerunning the request, use the same body and query parameters. You can change the value of any field in the original body or query, but you cannot change the provided fields. For example, an initial request might have a body section as follows:

body =
{
  "name": "clusCreateRerun",
  "password": "openSesame",
  "nodes": [
    {
      "cluster_interface": {
        "ip": {
          "address": "1.1.1.1"
        }
      }
    },
    {
      "cluster_interface": {
        "ip": {
          "address": "2.2.2.2"
        }
      }
    }
  ]
}

A rerun request updates the body details to:

body =
{
  "name": "clusCreateRerun",
  "password": "openSesame",
  "nodes": [
    {
      "cluster_interface": {
        "ip": {
          "address": "3.3.3.3"
        }
      }
    },
    {
      "cluster_interface": {
        "ip": {
          "address": "4.4.4.4"
        }
      }
    }
  ]
}

A rerun request with the following body details is invalid:

body =
{
  "name": "clusCreateRerun",
  "password": "openSesame",
  "nodes": [
    {
      "cluster_interface": {
        "ip": {
          "address": "3.3.3.3"
        }
      }
    }
  ]
}

Note that the password might already be configured. If a password is already configured and then a new password is provided, the new request overwrites the existing password. If a password is already configured either by another interface or by a previous POST request to /cluster, authenticate any future REST requests with that password. If a POST request to /cluster with the default return_timeout of 0 returns an error, then the password was not changed.

Connection failures during cluster create

A request to poll the job status might fail during a cluster create job in the following two cases. In these cases, programmatic use of the RESTful interface might be resilient to these connection failures. 1. When the "single_node_cluster" flag is set to "true", the node might reboot. During this time, the RESTful interface might refuse connections and return errors on a GET request, or connection timeouts might occur. Programmatic use of the RESTful interface during reboots must consider these effects while polling a cluster create job. 2. The "mgmt_auto" LIF is removed during the cluster create job. A POST /cluster request might be issued on the "mgmt_auto" LIF. However, requests to poll the job status might fail during cluster create when the "mgmt_auto" LIF is removed. The "mgmt_auto" LIF is only removed if a cluster management interface is provided as an argument to POST /cluster, and only after the cluster management interface is created. Programmatic use of the POST /cluster API on the "mgmt_auto" LIF should be configured to dynamically switch to polling the job on the cluster management LIF.


Modifying cluster configurations

The following fields can be used to modify a cluster-wide configuration:

  • name
  • location
  • contact
  • dns_domains
  • name_servers
  • timezone
  • certificate

Examples

Minimally configuring a 2-node setup


from netapp_ontap import HostConnection
from netapp_ontap.resources import Cluster

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    resource = Cluster()
    resource.name = "clusCreateExample1"
    resource.password = "openSesame"
    resource.nodes = [
        {"cluster_interface": {"ip": {"address": "1.1.1.1"}}},
        {"cluster_interface": {"ip": {"address": "2.2.2.2"}}},
    ]
    resource.post(hydrate=True)
    print(resource)


Setting up a single node with additional node configuration and auto aggregate creation


from netapp_ontap import HostConnection
from netapp_ontap.resources import Cluster

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    resource = Cluster()
    resource.name = "clusCreateExample2"
    resource.password = "openSesame"
    resource.nodes = [{"name": "singleNode", "location": "Sunnyvale"}]
    resource.post(
        hydrate=True, single_node_cluster=True, create_recommended_aggregates=True
    )
    print(resource)


Modifying a cluster-wide configuration


from netapp_ontap import HostConnection
from netapp_ontap.resources import Cluster

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    resource = Cluster()
    resource.contact = "it@company.com"
    resource.certificate = {"uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"}
    resource.patch()


Creating a cluster using the cluster "create" operation

This example shows how to create a cluster using the cluster APIs. Specifically, this example shows the creation of a two-node cluster and uses information from the nodes themselves combined with user supplied information to configure the cluster.

Preparing for setup

Before the REST APIs can be issued to create the cluster, the cluster must be wired up and powered on. The network connections between the nodes for the cluster interconnect and the connections to the management network must be completed. After the nodes are powered on, the nodes automatically configure interfaces on the platform's default cluster ports to allow the nodes to discover each other during setup and expansion workflows. You must configure a management interface on one node or use the mgmt_auto LIF, which is assigned an IP address using DHCP, to start using the REST APIs. By making a console connection to a node, the cluster setup wizard guides you through the configuration of the initial node managment interface to which the REST calls can be sent. Once this step is completed, exit the wizard by typing "exit". You can then issue REST API requests. 1. Wire and power on the nodes. 2. Make a console connection to one node to access the cluster setup wizard. 3. Enter node management interface information to enable REST API requests to be sent to the node.

Welcome to the cluster setup wizard.
You can enter the following commands at any time:
  "help" or "?" - if you want to have a question clarified,
  "back" - if you want to change previously answered questions, and
  "exit" or "quit" - if you want to quit the cluster setup wizard.
  Any changes you made before quitting will be saved.
  You can return to cluster setup at any time by typing "cluster setup".
  To accept a default or omit a question, do not enter a value.
  This system will send event messages and periodic reports to NetApp Technical
  Support. To disable this feature, enter
  autosupport modify -support disable
  within 24 hours.
  Enabling AutoSupport can significantly speed problem determination and
  resolution should a problem occur on your system.
  For further information on AutoSupport, see:
    <http://support.netapp.com/autosupport/>
    Type yes to confirm and continue {yes}: yes
    Enter the node management interface port [e0c]:
      Enter the node management interface IP address: 10.224.82.249
      Enter the node management interface netmask: 255.255.192.0
      Enter the node management interface default gateway: 10.224.64.1
      A node management interface on port e0c with IP address 10.224.82.249 has been created.
      Use your web browser to complete cluster setup by accessing
      <https://10.224.82.249>
      Otherwise, press Enter to complete cluster setup using the command line
      interface: exit
      Exiting the cluster setup wizard. Any changes you made have been saved.
      The cluster administrator's account (username "admin") password is set to the system default.
      Warning: You have exited the cluster setup wizard before completing all
      of the tasks. The cluster is not configured. You can complete cluster setup by typing
      "cluster setup" in the command line interface.

Discovering the nodes

If you issue a GET /api/cluster/nodes request when the nodes are not in a cluster, the API returns a list of nodes that were discovered on the cluster interconnect. Information returned includes the node's serial number, model, software version, UUID, and cluster interface address. The number of nodes returned should be the same as the number of nodes expected to be in the cluster. If too many nodes are discovered, remove the nodes that should not be part of the cluster. If not enough nodes are discovered, verify all the nodes are powered on, that the connections to the cluster interconnect are complete, and retry the command.

from netapp_ontap import HostConnection
from netapp_ontap.resources import Node

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    print(list(Node.get_collection(fields="state,uptime")))

[
    Node(
        {
            "_links": {
                "self": {
                    "href": "/api/cluster/nodes/6dce4710-c860-11e9-b5bc-005056bb6135"
                }
            },
            "state": "up",
            "uuid": "6dce4710-c860-11e9-b5bc-005056bb6135",
            "uptime": 134555,
            "name": "cluster1",
        }
    )
]


Creating the cluster

When the node information is available, including each node's cluster interface address, you can assemble the information for creating the cluster. Provide the cluster name and the password for the admin account. The rest of the information is optional and can be configured later using other APIs. Provide the cluster interface address for each node to be included in the cluster so that you can connect to it while adding it to the cluster. In addition to the cluster interface address, you can provide the optional node name, location, and management interface information. If you do not provide node names, nodes are named based on the cluster name. The nodes' managment interface subnet mask and gateway values are omitted and must be the same as the cluster management interface's subnet mask and gateway.

from netapp_ontap import HostConnection
from netapp_ontap.resources import Cluster

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    resource = Cluster()
    resource.name = "cluster1"
    resource.location = "datacenter1"
    resource.contact = "me"
    resource.dns_domains = ["example.com"]
    resource.name_servers = ["10.224.223.130", "10.224.223.131", "10.224.223.132"]
    resource.ntp_servers = ["time.nist.gov"]
    resource.management_interface = {
        "ip": {
            "address": "10.224.82.25",
            "netmask": "255.255.192.0",
            "gateway": "10.224.64.1",
        }
    }
    resource.password = "mypassword"
    resource.license = {"keys": ["AMEPOSOIKLKGEEEEDGNDEKSJDE"]}
    resource.nodes = [
        {
            "cluster_interface": {"ip": {"address": "169.254.245.113"}},
            "name": "node1",
            "management_interface": {"ip": {"address": "10.224.82.29"}},
        },
        {
            "cluster_interface": {"ip": {"address": "169.254.217.95"}},
            "name": "node2",
            "management_interface": {"ip": {"address": "10.224.82.31"}},
        },
    ]
    resource.post(hydrate=True)
    print(resource)

Cluster(
    {
        "name_servers": ["10.224.223.130", "10.224.223.131", "10.224.223.132"],
        "contact": "me",
        "management_interface": {
            "ip": {
                "gateway": "10.224.64.1",
                "netmask": "255.255.192.0",
                "address": "10.224.82.25",
            }
        },
        "license": {"keys": ["AMEPOSOIKLKGEEEEDGNDEKSJDE"]},
        "password": "mypassword",
        "dns_domains": ["example.com"],
        "ntp_servers": ["time.nist.gov"],
        "location": "datacenter1",
        "nodes": [
            {
                "management_interface": {"ip": {"address": "10.224.82.29"}},
                "cluster_interface": {"ip": {"address": "169.254.245.113"}},
                "name": "node1",
            },
            {
                "management_interface": {"ip": {"address": "10.224.82.31"}},
                "cluster_interface": {"ip": {"address": "169.254.217.95"}},
                "name": "node2",
            },
        ],
        "name": "cluster1",
    }
)


Monitoring the progress of cluster creation

To monitor the progress of the cluster create operation, poll the returned job link until the state value is no longer "running" or "queued".

from netapp_ontap import HostConnection
from netapp_ontap.resources import Job

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    resource = Job(uuid="b5bc07e2-1e9-11e9-a751-005056bbd95f")
    resource.get()
    print(resource)

Job(
    {
        "message": "success",
        "code": 0,
        "uuid": "b5bc07e2-19e9-11e9-a751-005056bbd95f",
        "state": "success",
        "description": "POST /api/cluster",
        "_links": {
            "self": {"href": "/api/cluster/jobs/b5bc07e2-19e9-11e9-a751-005056bbd95f"}
        },
    }
)


Verifying the cluster information

After the cluster is created, you can verify the information applied using a number of APIs. You can retrieve most of the information provided using the /api/cluster and /api/cluster/nodes APIs. In addition, you can view the network interface and route information using the /api/network APIs. The following example shows how to retrieve the cluster information:

from netapp_ontap import HostConnection
from netapp_ontap.resources import Cluster

with HostConnection("<mgmt-ip>", username="admin", password="password", verify=False):
    resource = Cluster()
    resource.get()
    print(resource)

Cluster(
    {
        "version": {
            "major": 10,
            "generation": 9,
            "full": "NetApp Release 9.10.1: Mon May 24 08:07:35 UTC 2021",
            "minor": 1,
        },
        "name_servers": ["10.224.223.131", "10.224.223.130"],
        "san_optimized": False,
        "_links": {"self": {"href": "/api/cluster"}},
        "management_interfaces": [
            {
                "_links": {
                    "self": {
                        "href": "/api/network/ip/interfaces/beef2db7-bd67-11eb-95f4-005056a7b9b1"
                    }
                },
                "ip": {"address": "10.236.153.229"},
                "uuid": "beef2db7-bd67-11eb-95f4-005056a7b9b1",
                "name": "clus_mgmt",
            },
            {
                "_links": {
                    "self": {
                        "href": "/api/network/ip/interfaces/cb63e02c-bd72-11eb-95f4-005056a7b9b1"
                    }
                },
                "ip": {"address": "fd20:8b1e:b255:9051::a02"},
                "uuid": "cb63e02c-bd72-11eb-95f4-005056a7b9b1",
                "name": "sti44-vsim-ucs515w_cluster_mgmt_inet6",
            },
            {
                "_links": {
                    "self": {
                        "href": "/api/network/ip/interfaces/ea13dec1-bd72-11eb-bd00-005056a7f50e"
                    }
                },
                "ip": {"address": "fd20:8b1e:b255:9051::a0a"},
                "uuid": "ea13dec1-bd72-11eb-bd00-005056a7f50e",
                "name": "sti44-vsim-ucs515x_cluster_mgmt_inet6",
            },
        ],
        "contact": "divyabha",
        "certificate": {
            "uuid": "b282f3d1-bd67-11eb-95f4-005056a7b9b1",
            "_links": {
                "self": {
                    "href": "/api/security/certificates/b282f3d1-bd67-11eb-95f4-005056a7b9b1"
                }
            },
        },
        "statistics": {
            "iops_raw": {"total": 0, "write": 0, "read": 0, "other": 0},
            "status": "ok",
            "timestamp": "2021-05-26T20:36:25+00:00",
            "latency_raw": {"total": 0, "write": 0, "read": 0, "other": 0},
            "throughput_raw": {"total": 0, "write": 0, "read": 0, "other": 0},
        },
        "metric": {
            "status": "ok",
            "timestamp": "2021-05-26T20:36:15+00:00",
            "latency": {"total": 0, "write": 0, "read": 0, "other": 0},
            "throughput": {"total": 0, "write": 0, "read": 0, "other": 0},
            "duration": "PT15S",
            "iops": {"total": 0, "write": 0, "read": 0, "other": 0},
        },
        "peering_policy": {
            "encryption_required": False,
            "authentication_required": True,
            "minimum_passphrase_length": 8,
        },
        "uuid": "5f7f57c7-bd67-11eb-95f4-005056a7b9b1",
        "dns_domains": [
            "ctl.gdl.englab.netapp.com",
            "gdl.englab.netapp.com",
            "rtp.netapp.com",
            "eng.netapp.com",
            "netapp.com",
        ],
        "ntp_servers": ["10.235.48.111"],
        "location": "sti",
        "timezone": {"name": "America/New_York"},
        "name": "C1_sti44-vsim-ucs515w_1621957038",
    }
)

Classes

class Cluster (*args, **kwargs)

Complete cluster information

Initialize the instance of the resource.

Any keyword arguments are set on the instance as properties. For example, if the class was named 'MyResource', then this statement would be true:

MyResource(name='foo').name == 'foo'

Args

*args
Each positional argument represents a parent key as used in the URL of the object. That is, each value will be used to fill in a segment of the URL which refers to some parent object. The order of these arguments must match the order they are specified in the URL, from left to right.
**kwargs
each entry will have its key set as an attribute name on the instance and its value will be the value of that attribute.

Ancestors

Methods

def get(self, **kwargs) -> NetAppResponse

Retrieves the cluster configuration.

Learn more


Fetch the details of the object from the host.

Requires the keys to be set (if any). After returning, new or changed properties from the host will be set on the instance.

Returns

A NetAppResponse object containing the details of the HTTP response.

Raises

NetAppRestError: If the API call returned a status code >= 400

def patch(self, hydrate: bool = False, poll: bool = True, poll_interval: Union[int, NoneType] = None, poll_timeout: Union[int, NoneType] = None, **kwargs) -> NetAppResponse

Updates the cluster configuration after the cluster is created.

Learn more


Send the difference in the object's state to the host as a modification request.

Calculates the difference in the object's state since the last time we interacted with the host and sends this in the request body.

Args

hydrate
If set to True, after the response is received from the call, a a GET call will be made to refresh all fields of the object.
poll
If set to True, the call will not return until the asynchronous job on the host has completed. Has no effect if the host did not return a job response.
poll_interval
If the operation returns a job, this specifies how often to query the job for updates.
poll_timeout
If the operation returns a job, this specifies how long to continue monitoring the job's status for completion.
**kwargs
Any key/value pairs passed will normally be sent as query parameters to the host. If any of these pairs are parameters that are sent as formdata then only parameters of that type will be accepted and all others will be discarded.

Returns

A NetAppResponse object containing the details of the HTTP response.

Raises

NetAppRestError: If the API call returned a status code >= 400

def post(self, hydrate: bool = False, poll: bool = True, poll_interval: Union[int, NoneType] = None, poll_timeout: Union[int, NoneType] = None, **kwargs) -> NetAppResponse

Creates a cluster.

Required properties

  • name
  • password
  • location
  • contact
  • dns_domains
  • name_servers
  • ntp_servers
  • license
  • configuration_backup
  • management_interface
  • nodes
  • timezone

Learn more


Send this object to the host as a creation request.

Args

hydrate
If set to True, after the response is received from the call, a a GET call will be made to refresh all fields of the object.
poll
If set to True, the call will not return until the asynchronous job on the host has completed. Has no effect if the host did not return a job response.
poll_interval
If the operation returns a job, this specifies how often to query the job for updates.
poll_timeout
If the operation returns a job, this specifies how long to continue monitoring the job's status for completion.
**kwargs
Any key/value pairs passed will normally be sent as query parameters to the host. If any of these pairs are parameters that are sent as formdata then only parameters of that type will be accepted and all others will be discarded.

Returns

A NetAppResponse object containing the details of the HTTP response.

Raises

NetAppRestError: If the API call returned a status code >= 400

Inherited members

class ClusterSchema (*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)

The fields of the Cluster object

Ancestors

  • netapp_ontap.resource.ResourceSchema
  • marshmallow.schema.Schema
  • marshmallow.base.SchemaABC

Class variables

certificate GET PATCH

The certificate field of the cluster.

configuration_backup POST

The configuration_backup field of the cluster.

contact GET POST PATCH

The contact field of the cluster.

Example: support@company.com

dns_domains GET POST PATCH

A list of DNS domains. Domain names have the following requirements:

  • The name must contain only the following characters: A through Z, a through z, 0 through 9, ".", "-" or "_".
  • The first character of each label, delimited by ".", must be one of the following characters: A through Z or a through z or 0 through 9.
  • The last character of each label, delimited by ".", must be one of the following characters: A through Z, a through z, or 0 through 9.
  • The top level domain must contain only the following characters: A through Z, a through z.
  • The system reserves the following names:"all", "local", and "localhost".

Example: ["example.com","example2.example3.com"]

license POST

The license field of the cluster.

The links field of the cluster.

location GET POST PATCH

The location field of the cluster.

Example: building 1

management_interface POST

The management_interface field of the cluster.

management_interfaces GET

The management_interfaces field of the cluster.

metric GET

The metric field of the cluster.

name GET POST PATCH

The name field of the cluster.

Example: cluster1

name_servers GET POST PATCH

The list of IP addresses of the DNS servers. Addresses can be either IPv4 or IPv6 addresses.

Example: ["10.224.65.20","2001:db08:a0b:12f0::1"]

nodes POST

The nodes field of the cluster.

ntp_servers GET POST

Host name, IPv4 address, or IPv6 address for the external NTP time servers.

Example: ["time.nist.gov","10.98.19.20","2610:20:6F15:15::27"]

password POST

Initial admin password used to create the cluster.

Example: mypassword

peering_policy GET POST PATCH

The peering_policy field of the cluster.

san_optimized GET

Specifies if this cluster is an All SAN Array.

statistics GET

The statistics field of the cluster.

timezone GET POST PATCH

The timezone field of the cluster.

uuid GET

The uuid field of the cluster.

Example: 1cd8a442-86d1-11e0-ae1c-123478563412

version GET

The version field of the cluster.