Search or ask Docker

Join an existing swarm

POST /swarm/join — Docker Engine API 1.57.

View Markdown
POST/swarm/join

Connection and access

API connection and authentication guidance

/v1.57

No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.

Parameters

No parameters are declared.

Request and responses

Request

application/json

Type: object

AdvertiseAddr

Type: string

Externally reachable address advertised to other nodes. This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the port number from the listen address is used. If AdvertiseAddr is not specified, it will be automatically detected when possible.
All schema constraints and annotations
{
  "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
  "type": "string"
}
DataPathAddr

Type: string

Address or interface to use for data path traffic (format: <ip|interface>), for example, 192.168.1.1, or an interface, like eth0. If DataPathAddr is unspecified, the same address as AdvertiseAddr is used.

The DataPathAddr specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster.

All schema constraints and annotations
{
  "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
  "type": "string"
}
JoinToken · required

Type: string

Secret token for joining this swarm.
All schema constraints and annotations
{
  "description": "Secret token for joining this swarm.",
  "type": "string"
}
ListenAddr · required

Type: string

Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This is required for joining a swarm. If the port number is omitted, the default swarm listening port is used.
All schema constraints and annotations
{
  "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
  "type": "string"
}
RemoteAddrs · required

Type: array

Addresses of manager nodes already participating in the swarm.
Array item

Type: string

All schema constraints and annotations
{
  "type": "string"
}
All schema constraints and annotations
{
  "description": "Addresses of manager nodes already participating in the swarm.\n",
  "items": {
    "type": "string"
  },
  "type": "array"
}
All schema constraints and annotations
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathAddr": "192.168.1.1",
    "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
    "ListenAddr": "0.0.0.0:2377",
    "RemoteAddrs": [
      "node1:2377"
    ]
  },
  "properties": {
    "AdvertiseAddr": {
      "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
      "type": "string"
    },
    "DataPathAddr": {
      "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
      "type": "string"
    },
    "JoinToken": {
      "description": "Secret token for joining this swarm.",
      "type": "string"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
      "type": "string"
    },
    "RemoteAddrs": {
      "description": "Addresses of manager nodes already participating in the swarm.\n",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "ListenAddr",
    "RemoteAddrs",
    "JoinToken"
  ],
  "title": "SwarmJoinRequest",
  "type": "object"
}

Schema example

{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathAddr": "192.168.1.1",
  "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
  "ListenAddr": "0.0.0.0:2377",
  "RemoteAddrs": [
    "node1:2377"
  ]
}

Request

text/plain

Type: object

AdvertiseAddr

Type: string

Externally reachable address advertised to other nodes. This can either be an address/port combination in the form 192.168.1.1:4567, or an interface followed by a port number, like eth0:4567. If the port number is omitted, the port number from the listen address is used. If AdvertiseAddr is not specified, it will be automatically detected when possible.
All schema constraints and annotations
{
  "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
  "type": "string"
}
DataPathAddr

Type: string

Address or interface to use for data path traffic (format: <ip|interface>), for example, 192.168.1.1, or an interface, like eth0. If DataPathAddr is unspecified, the same address as AdvertiseAddr is used.

The DataPathAddr specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster.

All schema constraints and annotations
{
  "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
  "type": "string"
}
JoinToken · required

Type: string

Secret token for joining this swarm.
All schema constraints and annotations
{
  "description": "Secret token for joining this swarm.",
  "type": "string"
}
ListenAddr · required

Type: string

Listen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This is required for joining a swarm. If the port number is omitted, the default swarm listening port is used.
All schema constraints and annotations
{
  "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
  "type": "string"
}
RemoteAddrs · required

Type: array

Addresses of manager nodes already participating in the swarm.
Array item

Type: string

All schema constraints and annotations
{
  "type": "string"
}
All schema constraints and annotations
{
  "description": "Addresses of manager nodes already participating in the swarm.\n",
  "items": {
    "type": "string"
  },
  "type": "array"
}
All schema constraints and annotations
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathAddr": "192.168.1.1",
    "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
    "ListenAddr": "0.0.0.0:2377",
    "RemoteAddrs": [
      "node1:2377"
    ]
  },
  "properties": {
    "AdvertiseAddr": {
      "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
      "type": "string"
    },
    "DataPathAddr": {
      "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
      "type": "string"
    },
    "JoinToken": {
      "description": "Secret token for joining this swarm.",
      "type": "string"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
      "type": "string"
    },
    "RemoteAddrs": {
      "description": "Addresses of manager nodes already participating in the swarm.\n",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "ListenAddr",
    "RemoteAddrs",
    "JoinToken"
  ],
  "title": "SwarmJoinRequest",
  "type": "object"
}

Schema example

{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathAddr": "192.168.1.1",
  "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
  "ListenAddr": "0.0.0.0:2377",
  "RemoteAddrs": [
    "node1:2377"
  ]
}

Response 200

no error

application/json

Response 200

no error

text/plain

Response 400

bad parameter

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 500

server error

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 503

node is already part of a swarm

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Referenced schemas

#/components/schemas/ErrorResponse

Complete operation contract
{
  "operationId": "SwarmJoin",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathAddr": "192.168.1.1",
            "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
            "ListenAddr": "0.0.0.0:2377",
            "RemoteAddrs": [
              "node1:2377"
            ]
          },
          "properties": {
            "AdvertiseAddr": {
              "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
              "type": "string"
            },
            "DataPathAddr": {
              "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
              "type": "string"
            },
            "JoinToken": {
              "description": "Secret token for joining this swarm.",
              "type": "string"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
              "type": "string"
            },
            "RemoteAddrs": {
              "description": "Addresses of manager nodes already participating in the swarm.\n",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "ListenAddr",
            "RemoteAddrs",
            "JoinToken"
          ],
          "title": "SwarmJoinRequest",
          "type": "object"
        }
      },
      "text/plain": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathAddr": "192.168.1.1",
            "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2",
            "ListenAddr": "0.0.0.0:2377",
            "RemoteAddrs": [
              "node1:2377"
            ]
          },
          "properties": {
            "AdvertiseAddr": {
              "description": "Externally reachable address advertised to other nodes. This\ncan either be an address/port combination in the form\n`192.168.1.1:4567`, or an interface followed by a port number,\nlike `eth0:4567`. If the port number is omitted, the port\nnumber from the listen address is used. If `AdvertiseAddr` is\nnot specified, it will be automatically detected when possible.\n",
              "type": "string"
            },
            "DataPathAddr": {
              "description": "Address or interface to use for data path traffic (format:\n`\u003cip|interface\u003e`), for example,  `192.168.1.1`, or an interface,\nlike `eth0`. If `DataPathAddr` is unspecified, the same address\nas `AdvertiseAddr` is used.\n\nThe `DataPathAddr` specifies the address that global scope\nnetwork drivers will publish towards other nodes in order to\nreach the containers running on this node. Using this parameter\nit is possible to separate the container data traffic from the\nmanagement traffic of the cluster.\n",
              "type": "string"
            },
            "JoinToken": {
              "description": "Secret token for joining this swarm.",
              "type": "string"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication if the node\ngets promoted to manager, as well as determining the networking\ninterface used for the VXLAN Tunnel Endpoint (VTEP). This is\nrequired for joining a swarm. If the port number is omitted,\nthe default swarm listening port is used.\n",
              "type": "string"
            },
            "RemoteAddrs": {
              "description": "Addresses of manager nodes already participating in the swarm.\n",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "ListenAddr",
            "RemoteAddrs",
            "JoinToken"
          ],
          "title": "SwarmJoinRequest",
          "type": "object"
        }
      }
    },
    "required": true,
    "x-codegen-request-body-name": "body"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {},
        "text/plain": {}
      },
      "description": "no error"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "bad parameter"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "server error"
    },
    "503": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "node is already part of a swarm"
    }
  },
  "summary": "Join an existing swarm",
  "tags": [
    "Swarm"
  ]
}