Create a peering relationship

05/09/2024 Contributors

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.

Recommended optional properties

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:

Name

Type

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

Name

Type

Description

_links

authentication

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.

ipspace

The IPspace of the local intercluster LIFs.

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.

peer_applications

array[string]

Peering applications against which allowed SVMs are configured.

remote

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

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": "ok",
    "state": "ok"
  },
  "encryption": {
    "proposed": "none",
    "state": "none"
  },
  "initial_allowed_svms": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "ipspace": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "exchange",
    "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": {
    },
    "name": "cluster2",
    "serial_number": "4048820-60-9"
  },
  "status": {
    "state": "available",
    "update_time": "2017-01-25T11:20:13Z"
  },
  "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"
  }
}

Response

Status: 201, Created

Name	Type	Description
_links	_links
authentication	authentication
ip_address	string	IPv4 or IPv6 address
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.

Name

Type

Description

_links

authentication

ip_address

string

IPv4 or IPv6 address

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.

Example response

{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "authentication": {
    "expiry_time": "2017-01-25T11:20:13Z"
  },
  "ip_address": "10.10.10.7",
  "name": "cluster2"
}

Error

Status: Default

ONTAP Error Response Codes

Error Code	Description
1966366	The system SVM of the cluster IPspace hosts cluster LIFs only.
4653365	IPspaces are unavailable with cluster peering: {ipspace}.
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.
4656096	Creating an intercluster LIF requires an IPv4 or IPv6 address of the default router.

Name	Type	Description
error	error

Name

Type

Description

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

Name

Type

Description

href

string

_links

Name	Type	Description
interfaces	href
self	href

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

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

Name

Type

Description

proposed

string

state

string

_links

Name	Type	Description
self	href

Name

Type

Description

self

href

initial_allowed_svms

Name	Type	Description
_links	_links
name	string	The name of the SVM.
uuid	string	The unique identifier of the SVM.

Name

Type

Description

_links

name

string

The name of the SVM.

uuid

string

The unique identifier of the SVM.

ipspace

The IPspace of the local intercluster LIFs.

Name	Type	Description
_links	_links
name	string	IPspace name
uuid	string	IPspace UUID

Name

Type

Description

_links

name

string

IPspace name

uuid

string

IPspace UUID

interfaces

Name	Type	Description
ip_address	string	IPv4 or IPv6 address

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.

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.

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.

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.

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.

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

Name

Type

Description

_links

authentication

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.

ipspace

The IPspace of the local intercluster LIFs.

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.

peer_applications

array[string]

Peering applications against which allowed SVMs are configured.

remote

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

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.

authentication

Name	Type	Description
expiry_time	string	The date and time the passphrase will expire. The default expiry time is one hour.
passphrase	string	A password to authenticate the cluster peer relationship.

Name

Type

Description

expiry_time

string

The date and time the passphrase will expire. The default expiry time is one hour.

passphrase

string

A password to authenticate the cluster peer relationship.

error_arguments

Name	Type	Description
code	string	Argument code
message	string	Message argument

Name

Type

Description

code

string

Argument code

message

string

Message argument

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.

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.

Create a peering relationship

Creating your file...

Required properties

Recommended optional properties

Additional information

Parameters

Request Body

Response

Error

Definitions