Skip to main content
A newer release of this product is available.

Create a peering relationship

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

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.

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.

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

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

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

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.

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.

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.

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.

error_arguments

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.