# Module `netapp_ontap.resources.cluster`

Copyright © 2021 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.

### Create recommended aggregates parameter

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.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")))

Try it out

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

### 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"
        resource.management_interface.ip.netmask = "255.255.192.0"
        resource.management_interface.ip.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)

Try it out

    Cluster(
        {
            "password": "mypassword",
            "name_servers": ["10.224.223.130", "10.224.223.131", "10.224.223.132"],
            "location": "datacenter1",
            "dns_domains": ["example.com"],
            "name": "cluster1",
            "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"}},
                },
            ],
            "license": {"keys": ["AMEPOSOIKLKGEEEEDGNDEKSJDE"]},
            "contact": "me",
            "management_interface": {
                "ip": {
                    "gateway": "10.224.64.1",
                    "address": "10.224.82.25",
                    "netmask": "255.255.192.0",
                }
            },
            "ntp_servers": ["time.nist.gov"],
        }
    )

### 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 "runnning" 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)

Try it out

    Job(
        {
            "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"}
            },
            "message": "success",
        }
    )

### 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(fields="management_interfaces")
        print(resource)

Try it out

    Cluster(
        {
            "management_interfaces": [
                {
                    "name": "cluster_mgmt",
                    "uuid": "c661725a-19e9-11e9-a751-005056bbd95f",
                    "_links": {
                        "self": {
                            "href": "/api/network/ip/interfaces/c661725a-19e9-11e9-a751-005056bbd95f"
                        }
                    },
                    "ip": {"address": "10.224.82.25"},
                }
            ],
            "_links": {"self": {"href": "/api/cluster"}},
        }
    )

## 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

  - Resource

  ### Methods

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

    Retrieves the cluster configuration.

    ### Learn more

    - `DOC /cluster`

    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: typing.Union = None, poll_timeout: typing.Union = None, **kwargs) -> NetAppResponse`

    Updates the cluster configuration after the cluster is created.

    ### Related ONTAP commands * `cluster identity modify` * `system node modify` * `vserver services dns modify` * `vserver services name-service dns modify` * `timezone` * `security ssl modify`

    ### Learn more

    - `DOC /cluster`

    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: typing.Union = None, poll_timeout: typing.Union = None, **kwargs) -> NetAppResponse`

    Creates a cluster.

    ### Required properties

    - `name`
    - `password`

    ### Recommended optional properties

    - `location`
    - `contact`
    - `dns_domains`
    - `name_servers`
    - `ntp_servers`
    - `license`
    - `configuration_backup`
    - `management_interface`
    - `nodes`
    - `timezone`

    ### Learn more

    - `DOC /cluster`

    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

  - `Resource`:
    - `from_dict`
    - `get_collection_url`
    - `get_connection`
    - `instance_location`
    - `path_keys`
    - `poll`
    - `set_connection`
    - `to_dict`
`class ClusterSchema (*, only: typing.Union = None, exclude: typing.Union = (), many: bool = False, context: typing.Dict = None, load_only: typing.Union = (), dump_only: typing.Union = (), partial: typing.Union = 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.

  `links GET`

    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

  `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.