Skip to main content

Create a peering relationship

Contributors
PDFs

POST /cluster/peers

Introduced In: 9.6

Creates a peering relationship and, optionally, the IP interfaces it will use. There are two methods used to create a peering relationship:

  • Provide a remote IP address - Used when creating a new cluster peer relationship with a specific remote cluster. This requires at least one remote intercluster IP address from the remote cluster.

  • Do not provide a remote IP address - Used when the remote IP address is not provided and when the storage system is ready to accept peering requests from foreign clusters.

Required properties

  • remote.ip_addresses - Addresses of the remote peers. The local peer must be able to reach and connect to these addresses for the request to succeed in creating a peer. Only required when creating a peering relationship by providing a remote IP address.

  • Either set generate_passphrase to "true" or provide a passphrase in the body of the request. Only one of these options is required.

  • name - Name of the peering relationship or name of the remote peer.

  • passphrase - User generated passphrase for use in authentication.

  • generate_passphrase (true/false) - When "true", ONTAP automatically generates a passphrase to authenticate cluster peers.

  • ipspace - IPspace of the local intercluster LIFs. Assumes Default IPspace if not provided.

  • initial_allowed_svms - Local SVMs allowed to peer with the peer cluster's SVMs. Can be modified until the remote cluster accepts this cluster peering relationship.

  • local_network - Fields to create a local intercluster LIF.

  • expiry_time - Duration in ISO 8601 format for which the user-supplied or auto-generated passphrase is valid. Expiration time must not be greater than seven days into the future. ISO 8601 duration format is "PnDTnHnMnS" or "PnW" where n is a positive integer. The "nD", "nH", "nM" and "nS" fields can be dropped if zero. "P" must always be present and "T" must be present if there are any hours, minutes, or seconds fields.

  • encryption_proposed (none/tls-psk) - Encryption mechanism of the communication channel between the two peers.

  • peer_applications - SVM peering applications (SnapMirror, FlexCache or both) for which the SVM peering relationship is set up.

Additional information

As with creating a cluster peer through the CLI, the combinations of options must be valid in order for the create operation to succeed. The following list shows the combinations that will succeed and those that will fail:

  • A passphrase only (fail)

  • A peer IP address (fail)

  • A passphrase with an expiration time > 7 days into the future (fail)

  • A peer IP address and a passphrase (OK)

  • generate_passphrase=true (OK)

  • Any proposed encryption protocol (OK)

  • An IPspace name or UUID (OK)

  • A passphrase, peer IP address, and any proposed encryption protocol (OK)

  • A non empty list of initial allowed SVM peer names or UUIDs. (OK)

Parameters

Name Type In Required Description

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

Request Body

Name Type Description

_links

_links

authentication

authentication

encryption

encryption

initial_allowed_svms

array[initial_allowed_svms]

The local SVMs allowed to peer with the peer cluster's SVMs. This list can be modified until the remote cluster accepts this cluster peering relationship.

ip_address

string

IPv4 or IPv6 address

ipspace

ipspace

The IPspace of the local intercluster LIFs.

local_network

local_network

Cluster peering requires an intercluster LIF on each local node. These can be optionally created by specifying a list of IP addresses corresponding to each node.

name

string

Optional name for the cluster peer relationship. By default, it is the name of the remote cluster, or a temporary name might be autogenerated for anonymous cluster peer offers.

peer_applications

array[string]

Peering applications against which allowed SVMs are configured.

remote

remote

status

status

uuid

string

UUID of the cluster peer relationship. For anonymous cluster peer offers, the UUID will change when the remote cluster accepts the relationship.

version

version

This returns the cluster version information. When the cluster has more than one node, the cluster version is equivalent to the lowest of generation, major, and minor versions on all nodes.
Example request 
{
  "_links": {
    "interfaces": {
      "href": "/api/resourcelink"
    },
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "authentication": {
    "expiry_time": "P1DT2H3M4S or '2017-01-25T11:20:13Z'",
    "in_use": "string",
    "passphrase": "string",
    "state": "string"
  },
  "encryption": {
    "proposed": "string",
    "state": "string"
  },
  "initial_allowed_svms": [
    {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "svm1",
      "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
    }
  ],
  "ip_address": "10.10.10.7",
  "ipspace": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "Default",
    "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
  },
  "local_network": {
    "broadcast_domain": "bd1",
    "gateway": "10.1.1.1",
    "interfaces": [
      {
        "ip_address": "10.10.10.7"
      }
    ],
    "netmask": "255.255.0.0"
  },
  "name": "cluster2",
  "peer_applications": [
    "snapmirror",
    "flexcache"
  ],
  "remote": {
    "ip_addresses": [
      "10.10.10.7"
    ],
    "name": "cluster2",
    "serial_number": "4048820-60-9"
  },
  "status": {
    "state": "available",
    "update_time": "2017-01-25 06:20:13 -0500"
  },
  "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412",
  "version": {
    "full": "NetApp Release 9.4.0: Sun Nov 05 18:20:57 UTC 2017",
    "generation": 9,
    "major": 4,
    "minor": 0,
    "patch": "P2"
  }
}

Response

Status: 201, Created
Name Type Description

_links

_links

num_records

integer

Number of records

records

array[cluster_peer]
Example response 
{
  "_links": {
    "next": {
      "href": "/api/resourcelink"
    },
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "num_records": 1,
  "records": [
    {
      "_links": {
        "interfaces": {
          "href": "/api/resourcelink"
        },
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "authentication": {
        "expiry_time": "P1DT2H3M4S or '2017-01-25T11:20:13Z'",
        "in_use": "string",
        "passphrase": "string",
        "state": "string"
      },
      "encryption": {
        "proposed": "string",
        "state": "string"
      },
      "initial_allowed_svms": [
        {
          "_links": {
            "self": {
              "href": "/api/resourcelink"
            }
          },
          "name": "svm1",
          "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
        }
      ],
      "ip_address": "10.10.10.7",
      "ipspace": {
        "_links": {
          "self": {
            "href": "/api/resourcelink"
          }
        },
        "name": "Default",
        "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
      },
      "local_network": {
        "broadcast_domain": "bd1",
        "gateway": "10.1.1.1",
        "interfaces": [
          {
            "ip_address": "10.10.10.7"
          }
        ],
        "netmask": "255.255.0.0"
      },
      "name": "cluster2",
      "peer_applications": [
        "snapmirror",
        "flexcache"
      ],
      "remote": {
        "ip_addresses": [
          "10.10.10.7"
        ],
        "name": "cluster2",
        "serial_number": "4048820-60-9"
      },
      "status": {
        "state": "available",
        "update_time": "2017-01-25 06:20:13 -0500"
      },
      "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412",
      "version": {
        "full": "NetApp Release 9.4.0: Sun Nov 05 18:20:57 UTC 2017",
        "generation": 9,
        "major": 4,
        "minor": 0,
        "patch": "P2"
      }
    }
  ]
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

1966366

The system SVM of the cluster IPspace hosts cluster LIFs only.

4653058

Cannot peer with self.

4653075

Cannot peer with two clusters using the same cluster peer relationship name.

4653075

Cannot peer two clusters with the same name.

4653076

Cannot peer two clusters with the same UUID.

4653229

Value for "expiry_time" is obsolete.

4653236

The specified passphrase is too short.

4653365

IPspaces are unavailable with cluster peering: {ipspace}.

4653368

Invalid peer address passed in "ip_addresses": Verify that the peer address is correct, and then try the operation again.

4653419

An unencrypted peering relationship is not suported because the cluster peering policy requires the use of encryption.

4653708

The specified addresses must be of the same address family.

4656069

Specifying a passphrase without remote IP addresses is not supported.

4656070

The encryption protocol is meaningful only with authenticated cluster peer relationships.

4656071

Cannot peer with a cluster bearing the same name as the local cluster.

4656072

The name must conform to the same rules as a cluster name.

4656074

Cannot check whether all nodes of this cluster support encryption.

4656075

Cannot specify encryption: this operation requires an ECV of 9.6.0 or later.

4656077

Specify either remote IP addresses or generate_passphrase.

4656079

No cluster nodes were found. Check your cluster configuration.

4656081

Creating an intercluster LIF requires a list of local IP addresses.

4656085

Cannot create an intercluster LIF with an empty list of local IP addresses.

4656086

Creating an intercluster LIF requires a broadcast domain that is in use within the IPspace.

4656087

The number of local intercluster IP addresses must be less than or equal to the number of available nodes.

4656088

Found no ports matching the IPspace and the broadcast domain.

4656089

Found no matching entry for IPspace.

4656090

The given IPspace differs from the IPspace entry found.

4656091

Creating an intercluster LIF requires a subnet mask or a subnet mask length.

4656094

Found no ports to bind to intercluster LIFs. Check your network configuration.

4656095

The address family of the specified peer addresses is not valid in IPspace. Use /api/network/ip/interfaces/ to verify that required LIFs are present and operational on each cluster node.

4656096

Creating an intercluster LIF requires an IPv4 or IPv6 address of the default router.

4656100

Cannot use peer address "ip_addresses" because it is already in use on the local cluster. Use /api/network/ip/interfaces to view the address in use.

4656101

Cannot specify a remote IP that resolves to both IPv4 and IPv6. Specify an IPv4 or IPv6 address.

8847365

Unknown Host

Also see the table of common errors in the Response body overview section of this documentation.

Name Type Description

error

returned_error
Example error 
{
  "error": {
    "arguments": [
      {
        "code": "string",
        "message": "string"
      }
    ],
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

interfaces

href

self

href

authentication

Name Type Description

expiry_time

string

The time when the passphrase will expire, in ISO 8601 duration format or date and time format. The default is 1 hour.

generate_passphrase

boolean

Auto generate a passphrase when true.

in_use

string

passphrase

string

A password to authenticate the cluster peer relationship.

state

string

encryption

Name Type Description

proposed

string

state

string

_links

Name Type Description

self

href

initial_allowed_svms

SVM, applies only to SVM-scoped objects.

Name Type Description

_links

_links

name

string

The name of the SVM. This field cannot be specified in a PATCH method.

uuid

string

The unique identifier of the SVM. This field cannot be specified in a PATCH method.

ipspace

The IPspace of the local intercluster LIFs.

Name Type Description

_links

_links

name

string

IPspace name

uuid

string

IPspace UUID

interfaces

Name Type Description

ip_address

string

IPv4 or IPv6 address

local_network

Cluster peering requires an intercluster LIF on each local node. These can be optionally created by specifying a list of IP addresses corresponding to each node.

Name Type Description

broadcast_domain

string

Broadcast domain that is in use within the IPspace.

gateway

string

The IPv4 or IPv6 address of the default router.

interfaces

array[interfaces]

netmask

string

IPv4 mask or netmask length.

remote

Name Type Description

ip_addresses

array[string]

The IPv4 addresses, IPv6 addresses, or hostnames of the peers.

name

string

The name of the remote cluster.

serial_number

string

The serial number of the remote cluster.

status

Name Type Description

state

string

update_time

string

The last time the state was updated.

version

This returns the cluster version information. When the cluster has more than one node, the cluster version is equivalent to the lowest of generation, major, and minor versions on all nodes.

Name Type Description

full

string

The full cluster version string.

generation

integer

The generation portion of the version.

major

integer

The major portion of the version.

minor

integer

The minor portion of the version.

patch

string

The patch portion of the version.

cluster_peer

Name Type Description

_links

_links

authentication

authentication

encryption

encryption

initial_allowed_svms

array[initial_allowed_svms]

The local SVMs allowed to peer with the peer cluster's SVMs. This list can be modified until the remote cluster accepts this cluster peering relationship.

ip_address

string

IPv4 or IPv6 address

ipspace

ipspace

The IPspace of the local intercluster LIFs.

local_network

local_network

Cluster peering requires an intercluster LIF on each local node. These can be optionally created by specifying a list of IP addresses corresponding to each node.

name

string

Optional name for the cluster peer relationship. By default, it is the name of the remote cluster, or a temporary name might be autogenerated for anonymous cluster peer offers.

peer_applications

array[string]

Peering applications against which allowed SVMs are configured.

remote

remote

status

status

uuid

string

UUID of the cluster peer relationship. For anonymous cluster peer offers, the UUID will change when the remote cluster accepts the relationship.

version

version

This returns the cluster version information. When the cluster has more than one node, the cluster version is equivalent to the lowest of generation, major, and minor versions on all nodes.

_links

Name Type Description

next

href

self

href

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

returned_error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.