Create a peering relationship

08/29/2024 Contributors

POST /cluster/peers

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

Provide remote IP

Here the user provides the remote IP address. Creating a new cluster peer relationship with a specific remote cluster requires at least one remote intercluster IP address from that cluster.

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.
Either set generate_passphrase to true or provide a passphrase in the body of the request; only one of them is required.

Optional properties

The following fields are optional for a POST on /cluster/peer/. All fields must follow the structure in the cluster peer API definition.

name - Name of the peering relationship.
passphrase - User generated passphrase for use in authentication.
generate_passphrase (true/false) - When this option is 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 - 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.
local_network - fields to create a local intercluster LIF. See section on "Creating local intercluster lifs".
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" should always be present and "T" should 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.

Do not provide remote IP

This method is used when the remote IP address is not provided. This method is used when the filer is ready to accept peering request from foreign clusters.

Required properties

generate_passphrase (true) - This option must be set to true. ONTAP automatically generates a passphrase to authenticate cluster peers. Either set generate_passphrase to true or provide a passphrase in the body of the request; only one of them is required.

Optional properties

The following fields are optional for a POST on /cluster/peer/. All fields must follow the structure in the cluster peer API definition.

name - Name of the remote peer.
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. This list can be modified until the remote cluster accepts this cluster peering relationship.
local_network - Fields to create a local intercluster LIF. See section on "Creating local intercluster lifs".
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" should always be present and "T" should 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.

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)
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 initial allowed vserver peer names or UUIDs. (OK)

Learn more

DOC /cluster/peers

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

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.

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.

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"
    }
  ],
  "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",
  "remote": {
    "ip_addresses": [
      "10.10.10.7"
    ],
    "name": "cluster2",
    "serial_number": "4048820-60-9"
  },
  "status": {
    "state": "available",
    "update_time": "2017-01-25 11:20:13 UTC"
  },
  "uuid": "1cd8a442-86d1-11e0-ae1c-123478563412"
}

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 may 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 may be autogenerated for anonymous cluster peer offers.

Example response

{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "authentication": {
    "expiry_time": "2017-01-25 11:20:13 UTC",
    "passphrase": "string"
  },
  "ip_address": "10.10.10.7",
  "name": "cluster2"
}

Error

Status: Default

ONTAP Error Response Codes

Error Code	Description
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.
4656077	Specify either remote IP addresses or generate_passphrase.
4656075	Cannot specify encryption: this operation requires an ECV of 9.6.0 or later.
4656079	No cluster nodes were found. Check your cluster configuration.
4656085	Cannot create an intercluster LIF with an empty list of local IP addresses.
4656087	The number of local intercluster IP addresses must be less than or equal to the number of available nodes.
4656086	Creating an intercluster LIF requires a broadcast domain that is in use within the IPspace.
4653365	IPspaces are unavailable with cluster peering: {ipspace}.
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 network mask or a network mask length.
4656081	Creating an intercluster LIF requires a list of local IP addresses.
1966366	The System SVM of the cluster IPspace hosts Cluster LIFs only.
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

SVM, applies only to SVM-scoped objects.

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.

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

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.

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.

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

Provide remote IP

Required properties

Optional properties

Do not provide remote IP

Required properties

Optional properties

Additional information

Learn more

Request Body

Response

Error

Definitions