Search or ask Docker

Initialize a new swarm

POST /swarm/init — Docker Engine API 1.57.

View Markdown
POST/swarm/init

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"
}
DataPathPort

Type: integer

DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.
All schema constraints and annotations
{
  "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
  "format": "uint32",
  "type": "integer"
}
DefaultAddrPool

Type: array

Default Address Pool specifies default subnet pools for global scope networks.
Array item

Type: string

All schema constraints and annotations
{
  "example": [
    "10.10.0.0/16",
    "20.20.0.0/16"
  ],
  "type": "string"
}
All schema constraints and annotations
{
  "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
  "items": {
    "example": [
      "10.10.0.0/16",
      "20.20.0.0/16"
    ],
    "type": "string"
  },
  "type": "array"
}
ForceNewCluster

Type: boolean

Force creation of a new swarm.
All schema constraints and annotations
{
  "description": "Force creation of a new swarm.",
  "type": "boolean"
}
ListenAddr

Type: string

Listen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). 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 default swarm listening port is used.
All schema constraints and annotations
{
  "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
  "type": "string"
}
Spec

Schema: SwarmSpec

SubnetSize

Type: integer

SubnetSize specifies the subnet size of the networks created from the default subnet pool.
All schema constraints and annotations
{
  "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
  "format": "uint32",
  "type": "integer"
}
All schema constraints and annotations
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathPort": 4789,
    "DefaultAddrPool": [
      "10.10.0.0/8",
      "20.20.0.0/8"
    ],
    "ForceNewCluster": false,
    "ListenAddr": "0.0.0.0:2377",
    "Spec": {
      "CAConfig": {},
      "Dispatcher": {},
      "EncryptionConfig": {
        "AutoLockManagers": false
      },
      "Orchestration": {},
      "Raft": {}
    },
    "SubnetSize": 24
  },
  "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"
    },
    "DataPathPort": {
      "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
      "format": "uint32",
      "type": "integer"
    },
    "DefaultAddrPool": {
      "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
      "items": {
        "example": [
          "10.10.0.0/16",
          "20.20.0.0/16"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "ForceNewCluster": {
      "description": "Force creation of a new swarm.",
      "type": "boolean"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
      "type": "string"
    },
    "Spec": {
      "$ref": "#/components/schemas/SwarmSpec"
    },
    "SubnetSize": {
      "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
      "format": "uint32",
      "type": "integer"
    }
  },
  "title": "SwarmInitRequest",
  "type": "object"
}

Schema example

{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathPort": 4789,
  "DefaultAddrPool": [
    "10.10.0.0/8",
    "20.20.0.0/8"
  ],
  "ForceNewCluster": false,
  "ListenAddr": "0.0.0.0:2377",
  "Spec": {
    "CAConfig": {},
    "Dispatcher": {},
    "EncryptionConfig": {
      "AutoLockManagers": false
    },
    "Orchestration": {},
    "Raft": {}
  },
  "SubnetSize": 24
}

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"
}
DataPathPort

Type: integer

DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.
All schema constraints and annotations
{
  "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
  "format": "uint32",
  "type": "integer"
}
DefaultAddrPool

Type: array

Default Address Pool specifies default subnet pools for global scope networks.
Array item

Type: string

All schema constraints and annotations
{
  "example": [
    "10.10.0.0/16",
    "20.20.0.0/16"
  ],
  "type": "string"
}
All schema constraints and annotations
{
  "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
  "items": {
    "example": [
      "10.10.0.0/16",
      "20.20.0.0/16"
    ],
    "type": "string"
  },
  "type": "array"
}
ForceNewCluster

Type: boolean

Force creation of a new swarm.
All schema constraints and annotations
{
  "description": "Force creation of a new swarm.",
  "type": "boolean"
}
ListenAddr

Type: string

Listen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). 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 default swarm listening port is used.
All schema constraints and annotations
{
  "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
  "type": "string"
}
Spec

Schema: SwarmSpec

SubnetSize

Type: integer

SubnetSize specifies the subnet size of the networks created from the default subnet pool.
All schema constraints and annotations
{
  "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
  "format": "uint32",
  "type": "integer"
}
All schema constraints and annotations
{
  "example": {
    "AdvertiseAddr": "192.168.1.1:2377",
    "DataPathPort": 4789,
    "DefaultAddrPool": [
      "10.10.0.0/8",
      "20.20.0.0/8"
    ],
    "ForceNewCluster": false,
    "ListenAddr": "0.0.0.0:2377",
    "Spec": {
      "CAConfig": {},
      "Dispatcher": {},
      "EncryptionConfig": {
        "AutoLockManagers": false
      },
      "Orchestration": {},
      "Raft": {}
    },
    "SubnetSize": 24
  },
  "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"
    },
    "DataPathPort": {
      "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
      "format": "uint32",
      "type": "integer"
    },
    "DefaultAddrPool": {
      "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
      "items": {
        "example": [
          "10.10.0.0/16",
          "20.20.0.0/16"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "ForceNewCluster": {
      "description": "Force creation of a new swarm.",
      "type": "boolean"
    },
    "ListenAddr": {
      "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
      "type": "string"
    },
    "Spec": {
      "$ref": "#/components/schemas/SwarmSpec"
    },
    "SubnetSize": {
      "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
      "format": "uint32",
      "type": "integer"
    }
  },
  "title": "SwarmInitRequest",
  "type": "object"
}

Schema example

{
  "AdvertiseAddr": "192.168.1.1:2377",
  "DataPathPort": 4789,
  "DefaultAddrPool": [
    "10.10.0.0/8",
    "20.20.0.0/8"
  ],
  "ForceNewCluster": false,
  "ListenAddr": "0.0.0.0:2377",
  "Spec": {
    "CAConfig": {},
    "Dispatcher": {},
    "EncryptionConfig": {
      "AutoLockManagers": false
    },
    "Orchestration": {},
    "Raft": {}
  },
  "SubnetSize": 24
}

Response 200

no error

application/json

Type: string

The node ID
All schema constraints and annotations
{
  "description": "The node ID",
  "example": "7v2t30z9blmxuhnyo6s4cpenp",
  "type": "string"
}

Schema example

"7v2t30z9blmxuhnyo6s4cpenp"

Response 200

no error

text/plain

Type: string

The node ID
All schema constraints and annotations
{
  "description": "The node ID",
  "example": "7v2t30z9blmxuhnyo6s4cpenp",
  "type": "string"
}

Schema example

7v2t30z9blmxuhnyo6s4cpenp

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

#/components/schemas/SwarmSpec

Complete operation contract
{
  "operationId": "SwarmInit",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathPort": 4789,
            "DefaultAddrPool": [
              "10.10.0.0/8",
              "20.20.0.0/8"
            ],
            "ForceNewCluster": false,
            "ListenAddr": "0.0.0.0:2377",
            "Spec": {
              "CAConfig": {},
              "Dispatcher": {},
              "EncryptionConfig": {
                "AutoLockManagers": false
              },
              "Orchestration": {},
              "Raft": {}
            },
            "SubnetSize": 24
          },
          "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"
            },
            "DataPathPort": {
              "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
              "format": "uint32",
              "type": "integer"
            },
            "DefaultAddrPool": {
              "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
              "items": {
                "example": [
                  "10.10.0.0/16",
                  "20.20.0.0/16"
                ],
                "type": "string"
              },
              "type": "array"
            },
            "ForceNewCluster": {
              "description": "Force creation of a new swarm.",
              "type": "boolean"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
              "type": "string"
            },
            "Spec": {
              "$ref": "#/components/schemas/SwarmSpec"
            },
            "SubnetSize": {
              "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
              "format": "uint32",
              "type": "integer"
            }
          },
          "title": "SwarmInitRequest",
          "type": "object"
        }
      },
      "text/plain": {
        "schema": {
          "example": {
            "AdvertiseAddr": "192.168.1.1:2377",
            "DataPathPort": 4789,
            "DefaultAddrPool": [
              "10.10.0.0/8",
              "20.20.0.0/8"
            ],
            "ForceNewCluster": false,
            "ListenAddr": "0.0.0.0:2377",
            "Spec": {
              "CAConfig": {},
              "Dispatcher": {},
              "EncryptionConfig": {
                "AutoLockManagers": false
              },
              "Orchestration": {},
              "Raft": {}
            },
            "SubnetSize": 24
          },
          "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"
            },
            "DataPathPort": {
              "description": "DataPathPort specifies the data path port number for data traffic.\nAcceptable port range is 1024 to 49151.\nif no port is set or is set to 0, default port 4789 will be used.\n",
              "format": "uint32",
              "type": "integer"
            },
            "DefaultAddrPool": {
              "description": "Default Address Pool specifies default subnet pools for global\nscope networks.\n",
              "items": {
                "example": [
                  "10.10.0.0/16",
                  "20.20.0.0/16"
                ],
                "type": "string"
              },
              "type": "array"
            },
            "ForceNewCluster": {
              "description": "Force creation of a new swarm.",
              "type": "boolean"
            },
            "ListenAddr": {
              "description": "Listen address used for inter-manager communication, as well\nas determining the networking interface used for the VXLAN\nTunnel Endpoint (VTEP). This can either be an address/port\ncombination in the form `192.168.1.1:4567`, or an interface\nfollowed by a port number, like `eth0:4567`. If the port number\nis omitted, the default swarm listening port is used.\n",
              "type": "string"
            },
            "Spec": {
              "$ref": "#/components/schemas/SwarmSpec"
            },
            "SubnetSize": {
              "description": "SubnetSize specifies the subnet size of the networks created\nfrom the default subnet pool.\n",
              "format": "uint32",
              "type": "integer"
            }
          },
          "title": "SwarmInitRequest",
          "type": "object"
        }
      }
    },
    "required": true,
    "x-codegen-request-body-name": "body"
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "description": "The node ID",
            "example": "7v2t30z9blmxuhnyo6s4cpenp",
            "type": "string"
          }
        },
        "text/plain": {
          "schema": {
            "description": "The node ID",
            "example": "7v2t30z9blmxuhnyo6s4cpenp",
            "type": "string"
          }
        }
      },
      "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": "Initialize a new swarm",
  "tags": [
    "Swarm"
  ]
}