Skip to content

Commit 19b6591

Browse files
author
LRubin
committed
swarm beta docs for limited publish
Signed-off-by: LRubin <lrubin@docker.com>
1 parent 47cd038 commit 19b6591

1 file changed

Lines changed: 160 additions & 0 deletions

File tree

‎docker-cloud/cloud-swarm/index.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
description: Work with swarms in Docker Cloud
3+
keywords: swarm mode, swarms, orchestration Cloud, fleet management
4+
title: Swarms in Docker Cloud
5+
---
6+
7+
<b>Note</b>: All Swarm management features in Docker Cloud are free while in Beta.
8+
{: style="text-align:center" }
9+
10+
--------
11+
Docker Cloud now allows you to connect to clusters of Docker Engines running in v1.13 [Swarm Mode](/engine/swarm/).
12+
13+
## Enable Swarm Mode in Docker Cloud
14+
15+
By default, Docker Cloud allows you to manage [node clusters](../infrastructure/), but you can opt in to use the Beta Swarm Mode
16+
features. Swarm management replaces the node cluster management features when
17+
the Swarm Mode interface is enabled.
18+
19+
Click the **Swarm Mode** toggle to enable the swarm mode interface.
20+
21+
You can switch between node cluster and swarm mode at any time, and enabling swarm mode does _not_ remove or disconnect existing node clusters.
22+
23+
Swarm mode is free while in preview.
24+
25+
## Swarm mode and organizations
26+
27+
If you are using Docker Cloud in an [organization](../orgs/), you can use Swarm
28+
Mode to access any Docker swarms available to your organization. Members of the
29+
`owners` team grant each team in an organization access to the swarms they need.
30+
If necessary, you can create new teams to manage beta swarm access.
31+
32+
If you are using swarm mode as a member of a team other than the `owners` team,
33+
you will only see the swarms that you have been granted access to.
34+
35+
If you are a member of the `owners` team, you must switch to the Swarm Mode
36+
Docker Cloud interface to grant teams access to your organization's swarms.
37+
Swarms only appear in the [resource management](../orgs/#/set-team-permissions)
38+
screens for teams when in the swarm mode interface.
39+
40+
## Register an existing swarm
41+
42+
At this time, you cannot _create_ swarms from within Docker Cloud. However you can register existing swarms as part of the beta functionality.
43+
44+
Before you begin, make sure you have the following:
45+
46+
- a Docker ID
47+
- a Docker swarm composed of v1.13 (or later) Docker Engine nodes
48+
- a terminal session connected to one of the swarm's manager node
49+
- incoming port 2376 unblocked on that manager node
50+
51+
> **Note**: The IP to the manager node for your swarm must be open and publicly accessible so that Docker Cloud can connect and run commands.
52+
53+
To register an existing swarm in Docker Cloud:
54+
55+
1. Log in to Docker Cloud if necessary.
56+
2. If necessary, click the **Swarm mode** toggle to activate the Swarm Mode interface.
57+
3. Click **Swarms** in the top navigation.
58+
4. Click **Bring your own swarm**
59+
5. Select the whole command displayed in the dialog, and copy it to your clipboard.
60+
6. In terminal or another shell, connect to the Docker Engine running in the swarm's manager node using SSH.
61+
7. Paste the command you copied into the terminal session connected to the manager node.
62+
8. When prompted, log in using your Docker ID and password.
63+
64+
The registration process uses your Docker ID to determine which namespaces you have access to<!--are allowed to register the swarm under TODO:CLOUD-4079 -->. Once you log in, the CLI lists these namespaces to help you with the next step.
65+
66+
9. Enter a name, with a namespace before the name if needed, and press Enter.
67+
68+
If you do not enter a name, the swarm is registered to your Docker ID account with a randomized name that is displayed before the shell prompt. For example, the prompt might look like this:
69+
70+
```none
71+
Enter a name for the new cluster [mydockerid/5rdshkgzn1sw016zimgckzx3j]:
72+
```
73+
74+
You can enter a name at the prompt to discard the random name.
75+
76+
To register a swarm with an organization, prefix the new name with the organization name, for example `myorganization/myteamswarm`.
77+
78+
The manager node pulls the `dockercloud/registration` container and runs it on the swarm. The swarm then appears in the **Swarms** screen in Docker Cloud.
79+
80+
### Swarm Registration example
81+
82+
```none
83+
$ docker@swarm-m:~$ docker run -ti --rm -e -v /v
84+
ar/run/docker.sock:/var/run/docker.sock dockercloud/registration
85+
SwarmID of the node: 1btbwtge4xwjj0mjpdpr7jutn
86+
DockerVersion of the node: 1.24
87+
Use your Docker ID credentials to authenticate:
88+
Username: myusername
89+
Password:
90+
91+
Available namespaces:
92+
* myorganization
93+
* pacificocean
94+
* sealife
95+
Enter name for the new cluster [myusername/1btbwtge4xwjj0mjpdpr7jutn]:myswarm
96+
Registering this Docker cluster with Docker Cloud...
97+
Successfully registered the node as myswarm
98+
You can now access this cluster using the following command in any Docker Engine:
99+
docker run --rm -ti -v /var/run/docker.sock:/var/run/docker.sock -e DOCKER_HOST dockercloud/client myswarm
100+
```
101+
102+
## Swarm statuses in Docker Cloud
103+
104+
Swarms that are registered in Docker Cloud appear in the Swarms list. Each line in the list also shows the swarm's status. The statuses are:
105+
106+
<!-- TODO - **DEPLOYING**: Docker Cloud is provisioning the nodes of this swarm. -->
107+
- **DEPLOYED**: the swarm is sending heartbeat pings to Docker Cloud, and Cloud can contact it to run a health check.
108+
- **UNREACHABLE**: the swarm is sending heartbeart pings, but Docker Cloud cannot contact the swarm.
109+
- **UNAVAILABLE**: Docker Cloud is not receiving any heartbeats from the swarm.
110+
- **REMOVED**: the swarm has been unregistered from Docker Cloud and will be removed from the list soon.
111+
112+
> **Note**: [Removing a swarm](#unregister-a-swarm-from-Docker-cloud) only makes the swarm unavailable in Docker Cloud. It does not change the swarm itself or any processes running on the swarm.
113+
114+
## Connect to a swarm through Docker Cloud
115+
116+
Docker Cloud allows you to connect your local Docker Engine to any swarm you
117+
have access to in Docker Cloud. To do this, you run a proxy container in your local Docker instance, which connects to a manager node on the target swarm.
118+
119+
> **Note**: To connect to a swarm, you must first be logged in to Docker using a Docker ID which has access to the swarm. Use the `docker login` command from your terminal to log in.
120+
121+
1. Log in to Docker Cloud in your web browser.
122+
2. Click **Swarms** in the top navigation, and click the name of the swarm you want to connect to.
123+
3. Copy the command provided in the dialog that appears.
124+
4. In a terminal window connected to your local Docker Engine, paste the command, and press **Enter**.
125+
126+
The local Docker Engine downloads a containerized Docker Cloud client tool, and connects to the swarm.
127+
128+
5. To complete the connection process, run the `export DOCKER_HOST` command found in the previous command's output.
129+
130+
Be sure to include the client connection port in the URL. For example `export DOCKER_HOST=tcp://swarmID.myusername.docker.cloud:32768`.
131+
132+
To switch Docker hosts you can either run the `export` command again to overwrite it, or use `unset DOCKER_HOST`.
133+
134+
## Unregister a swarm from Docker Cloud
135+
136+
Unregistering a swarm from Docker Cloud only removes the swarm from Docker
137+
Cloud, deletes any access rights granted to teams, and disables proxy
138+
connections. Unregistering does not stop the services, containers, or processes on the swarm, and it does not disband the swarm or terminate the nodes.
139+
140+
To unregister a swarm from Docker Cloud:
141+
142+
1. Log in to Docker Cloud if necessary.
143+
2. Click **Swarms** in the top navigation.
144+
3. Put your mouse cursor on the swarm you want to unregister.
145+
4. Click the trash can icon that appears.
146+
5. In the confirmation dialog that appears, click **Unregister**.
147+
148+
Docker Cloud marks the swarm as `REMOVED` and removes the swarm from the list in the next few minutes.
149+
150+
## Reconnect a swarm
151+
152+
If you accidentally unregister a swarm from Docker Cloud, or decide that you
153+
want to re-register the swarm after it has been removed, you can re-register it
154+
using the same process as a normal registration. If the swarm is registered to
155+
an organization, its access permissions were deleted when it was unregistered,
156+
and must be recreated.
157+
158+
> **Note**: You cannot register a new or different swarm under the name of a
159+
swarm that was unregistered. To re-register a swarm, it must have the same swarm
160+
ID as it did when previously registered.

0 commit comments

Comments
 (0)