You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docker Cloud creates a per-user overlay network which connects all containers across all of the user's hosts. This network connects all of your containers on the `10.7.0.0/16` subnet, and gives every container a local IP. This IP persists on each container even if the container is redeployed and ends up on a different host. Every container can reach any other container on any port within the subnet.
9
+
Docker Cloud creates a per-user overlay network which connects all containers
10
+
across all of the user's hosts. This network connects all of your containers on
11
+
the `10.7.0.0/16` subnet, and gives every container a local IP. This IP persists
12
+
on each container even if the container is redeployed and ends up on a different
13
+
host. Every container can reach any other container on any port within the
14
+
subnet.
10
15
11
16
Docker Cloud gives your containers two ways find other services:
12
17
13
18
* Using service and container names directly as **hostnames**
19
+
14
20
* Using **service links**, which are based on [Docker Compose links](/compose/compose-file/#links)
15
21
16
-
**Service and Container Hostnames** update automatically when a service scales up or down or redeploys. As a user, you can configure service names, and Docker Cloud uses these names to find the IP of the services and containers for you. You can use hostnames in your code to provide abstraction that allows you to easily swap service containers or components.
22
+
**Service and Container Hostnames** update automatically when a service scales
23
+
up or down or redeploys. As a user, you can configure service names, and Docker
24
+
Cloud uses these names to find the IP of the services and containers for you.
25
+
You can use hostnames in your code to provide abstraction that allows you to
26
+
easily swap service containers or components.
17
27
18
-
**Service links** create environment variables which allow containers to communicate with each other within a stack, or with other services outside of a stack. You can specify service links explicitly when you create a new service or edit an existing one, or specify them in the stackfile for a service stack.
28
+
**Service links** create environment variables which allow containers to
29
+
communicate with each other within a stack, or with other services outside of a
30
+
stack. You can specify service links explicitly when you create a new service
31
+
or edit an existing one, or specify them in the stackfile for a service stack.
19
32
20
-
####Hostnames vs service links
33
+
### Hostnames vs service links
21
34
22
-
When a service is scaled up, a new hostname is created and automatically resolves to the new IP of the container, and the parent service hostname record also updates to include the new container's IP. However, new service link environment variables are not created, and existing ones are not removed, when a service scales up or down.
35
+
When a service is scaled up, a new hostname is created and automatically
36
+
resolves to the new IP of the container, and the parent service hostname record
37
+
also updates to include the new container's IP. However, new service link
38
+
environment variables are not created, and existing ones are not removed, when a
39
+
service scales up or down.
23
40
24
41
## Using service and container names as hostnames
25
42
26
-
You can use hostnames to connect any container in your Docker Cloud account to any other container on your account without having to create service links or manage environment variables. This is the recommended service discovery method.
43
+
You can use hostnames to connect any container in your Docker Cloud account to
44
+
any other container on your account without having to create service links or
45
+
manage environment variables. This is the recommended service discovery method.
27
46
28
-
Hostnames will always resolve to the correct IP for the service or container, and will update as the service scales up, scales down, or redeploys. The Docker Cloud automatic DNS service resolves the service name to the correct IP on the overlay network, even if the container has moved or is now on a different host.
47
+
Hostnames will always resolve to the correct IP for the service or container,
48
+
and will update as the service scales up, scales down, or redeploys. The Docker
49
+
Cloud automatic DNS service resolves the service name to the correct IP on the
50
+
overlay network, even if the container has moved or is now on a different host.
29
51
30
52
### Discovering containers on the same service or stack
31
53
32
-
A container can always discover other containers on the same stack using just the **container name** as hostname. This includes containers of the same service. Similarly, a container can always discover other services on the same stack using the **service name**.
54
+
A container can always discover other containers on the same stack using just
55
+
the **container name** as hostname. This includes containers of the same
56
+
service. Similarly, a container can always discover other services on the same
57
+
stack using the **service name**.
33
58
34
-
For example, a container `webapp-1` in the service `webapp` can connect to the container `db-1` in the service `db` by using `db-1` as the hostname. It can also connect to a peer container, `webapp-2`, by using `webapp-2` as the hostname.
59
+
For example, a container `webapp-1` in the service `webapp` can connect to the
60
+
container `db-1` in the service `db` by using `db-1` as the hostname. It can
61
+
also connect to a peer container, `webapp-2`, by using `webapp-2` as the
62
+
hostname.
35
63
36
-
A container `proxy-1` on the same stack could discover all `webapp` containers by using the **service name**`webapp` as hostname. Connecting to the service name resolves as an `A`[round-robin](http://en.wikipedia.org/wiki/Round-robin_DNS) record, listing all IPs of all containers on the service `webapp`.
64
+
A container `proxy-1` on the same stack could discover all `webapp` containers
65
+
by using the **service name**`webapp` as hostname. Connecting to the service
66
+
name resolves as an `A`
67
+
[round-robin](http://en.wikipedia.org/wiki/Round-robin_DNS) record, listing all
68
+
IPs of all containers on the service `webapp`.
37
69
38
70
### Discovering services or containers on another stack
39
71
40
-
To find a service or a container on another stack, append `.<stack_name>` to the service or container name. For example, if `webapp-1` on the stack `production` needs to access container `db-1` on the stack `common`, it could use the hostname `db-1.common` which Docker Cloud will resolve to the appropriate IP.
72
+
To find a service or a container on another stack, append `.<stack_name>` to the
73
+
service or container name. For example, if `webapp-1` on the stack `production`
74
+
needs to access container `db-1` on the stack `common`, it could use the
75
+
hostname `db-1.common` which Docker Cloud will resolve to the appropriate IP.
41
76
42
77
### Discovering services or containers not included in a stack
43
78
44
-
To find a container or service that is not included in a stack, use the service or container name as the hostname.
79
+
To find a container or service that is not included in a stack, use the service
80
+
or container name as the hostname.
45
81
46
-
If the container making the query is part of a stack, and there is a local match on the same stack, the local match will take precedence over the service or container that is outside the stack.
82
+
If the container making the query is part of a stack, and there is a local match
83
+
on the same stack, the local match will take precedence over the service or
84
+
container that is outside the stack.
47
85
48
-
> **Tip**: To work around this, you can rename the local match so that it has a more specific name. You might also put the external service or container in a dedicated stack so that you can specify the stack name as part of the namespace.
86
+
> **Tip**: To work around this, you can rename the local match so that it has a
87
+
more specific name. You might also put the external service or container in a
88
+
dedicated stack so that you can specify the stack name as part of the namespace.
49
89
50
90
## Using service links for service discovery
51
91
52
-
Docker Cloud's service linking is modeled on [Docker Compose links](/compose/compose-file/#links) to provide a basic service discovery functionality using directional links recorded in environment variables.
92
+
Docker Cloud's service linking is modeled on [Docker Compose
93
+
links](/compose/compose-file/#links) to provide a basic service discovery
94
+
functionality using directional links recorded in environment variables.
53
95
54
-
When you link a "client" service to a "server" service, Docker Cloud performs the following actions on the "client" service:
96
+
When you link a "client" service to a "server" service, Docker Cloud performs
97
+
the following actions on the "client" service:
55
98
56
99
1. Creates a group of environment variables that contain information about the exposed ports of the "server" service, including its IP address, port and protocol.
100
+
57
101
2. Copies all of the "server" service environment variables to the "client" service with an `HOSTNAME_ENV_` prefix.
102
+
58
103
3. Adds a DNS hostname to the Docker Cloud DNS service that resolves to the "server" service IP address.
59
104
60
-
Some environment variables such as the API endpoint are updated when a service scales up or down. Service links are only updated when a service is deployed or redeployed, but are not updated during runtime. No new service link environment variables are created when a service scales up or down.
105
+
Some environment variables such as the API endpoint are updated when a service
106
+
scales up or down. Service links are only updated when a service is deployed or
107
+
redeployed, but are not updated during runtime. No new service link environment
108
+
variables are created when a service scales up or down.
61
109
62
110
### Service link example
63
111
64
-
For the explanation of service linking, consider the following application diagram.
112
+
For the explanation of service linking, consider the following application
113
+
diagram.
65
114
66
115
67
116
68
-
Imagine that you are running a web service (`my-web-app`) with 2 containers (`my-web-app-1` and `my-web-app-2`). You want to add a proxy service (`my-proxy`) with one container (`my-proxy-1`) that will balance HTTP traffic to each of the containers in your `my-web-app` application, with a link name of `web`.
117
+
Imagine that you are running a web service (`my-web-app`) with 2 containers
118
+
(`my-web-app-1` and `my-web-app-2`). You want to add a proxy service
119
+
(`my-proxy`) with one container (`my-proxy-1`) that will balance HTTP traffic to
120
+
each of the containers in your `my-web-app` application, with a link name of
121
+
`web`.
69
122
70
123
### Service link environment variables
71
124
72
-
Several environment variables are set on each container at startup to provide link details to other containers. The links created are directional. These are similar to those used by Docker Compose.
125
+
Several environment variables are set on each container at startup to provide
126
+
link details to other containers. The links created are directional. These are
127
+
similar to those used by Docker Compose.
73
128
74
-
For our example app above, the following environment variables are set in the proxy containers to provide service links. The example proxy application can use these environment variables to configure itself on startup, and start balancing traffic between the two containers of `my-web-app`.
129
+
For our example app above, the following environment variables are set in the
130
+
proxy containers to provide service links. The example proxy application can use
131
+
these environment variables to configure itself on startup, and start balancing
132
+
traffic between the two containers of `my-web-app`.
@@ -91,7 +149,7 @@ To create these service links, you would specify the following in your stackfile
91
149
```yml
92
150
my-proxy:
93
151
links:
94
-
- my-web-app:web
152
+
- my-web-app:web
95
153
```
96
154
97
155
This example snippet creates a directional link from `my-proxy` to `my-web-app`, and calls that link `web`.
@@ -108,28 +166,47 @@ In the example, the `my-proxy` containers can access the service links using fol
108
166
| `web-1` | `172.16.0.5` |
109
167
| `web-2` | `172.16.0.6` |
110
168
111
-
The best way for the `my-proxy` service to connect to the `my-web-app` service containers is using the hostnames, because they are updated during runtime if `my-web-app` scales up or down. If `my-web-app` scales up, the new hostname `web-3` automatically resolves to the new IP of the container, and the hostname `web` is updated to include the new IP in its round-robin record.
169
+
The best way for the `my-proxy` service to connect to the `my-web-app` service
170
+
containers is using the hostnames, because they are updated during runtime if
171
+
`my-web-app`scales up or down. If `my-web-app` scales up, the new hostname
172
+
`web-3`automatically resolves to the new IP of the container, and the hostname
173
+
`web`is updated to include the new IP in its round-robin record.
112
174
113
-
However, the service link environment variables are not added or updated until the service is redeployed. If `my-web-app` scales up, no new service link environment variables (such as `WEB_3_PORT`, `WEB_3_PORT_80_TCP`, etc) are added to the "client" container. This means the client does not know how to contact the new "server" container.
175
+
However, the service link environment variables are not added or updated until
176
+
the service is redeployed. If `my-web-app` scales up, no new service link
177
+
environment variables (such as `WEB_3_PORT`, `WEB_3_PORT_80_TCP`, etc) are added
178
+
to the "client" container. This means the client does not know how to contact
179
+
the new "server" container.
114
180
115
181
### Service environment variables
116
182
117
-
Environment variables specified in the service definition are instantiated in each individual container. This ensures that each container has a copy of the service's defined environment variables, and also allows other connecting containers to read them.
183
+
Environment variables specified in the service definition are instantiated in
184
+
each individual container. This ensures that each container has a copy of the
185
+
service's defined environment variables, and also allows other connecting
186
+
containers to read them.
118
187
119
-
These environment variables are prefixed with the `HOSTNAME_ENV_` in each container.
188
+
These environment variables are prefixed with the `HOSTNAME_ENV_` in each
189
+
container.
120
190
121
-
In our example, if we launch our `my-web-app` service with an environment variable of `WEBROOT=/login`, the following environment variables are set and available in the proxy containers:
191
+
In our example, if we launch our `my-web-app` service with an environment
192
+
variable of `WEBROOT=/login`, the following environment variables are set and
193
+
available in the proxy containers:
122
194
123
195
| Name | Value |
124
196
|:------------------|:---------|
125
197
| WEB_1_ENV_WEBROOT | `/login` |
126
198
| WEB_2_ENV_WEBROOT | `/login` |
127
199
128
-
In our example, this enables the "client" service (`my-proxy-1`) to read configuration information such as usernames and passwords, or simple configuration, from the "server" service containers (`my-web-app-1` and `my-web-app-2`).
200
+
In our example, this enables the "client" service (`my-proxy-1`) to read
201
+
configuration information such as usernames and passwords, or simple
202
+
configuration, from the "server" service containers (`my-web-app-1` and
203
+
`my-web-app-2`).
129
204
130
205
#### Docker Cloud specific environment variables
131
206
132
-
In addition to the standard Docker environment variables, Docker Cloud also sets special environment variables that enable containers to self-configure. These environment variables are updated on redeploy.
207
+
In addition to the standard Docker environment variables, Docker Cloud also sets
208
+
special environment variables that enable containers to self-configure. These
209
+
environment variables are updated on redeploy.
133
210
134
211
In the example above, you will also find the following environment variables in the `my-proxy` containers:
135
212
@@ -152,13 +229,21 @@ In the example above, you will also find the following environment variables in
152
229
Where:
153
230
154
231
* `WEB_DOCKERCLOUD_API_URL` is the Docker Cloud API resource URI of the linked service. Because this is a link, the link name i the environment variable prefix.
232
+
155
233
* `DOCKERCLOUD_SERVICE_API_URI` and `DOCKERCLOUD_SERVICE_API_URL` are the Docker Cloud API resource URI and URL of the service running in the container.
234
+
156
235
* `DOCKERCLOUD_CONTAINER_API_URI` and `DOCKERCLOUD_CONTAINER_API_URL` are the Docker Cloud API resource URI and URL of the container itself.
236
+
157
237
* `DOCKERCLOUD_NODE_API_URI` and `DOCKERCLOUD_NODE_API_URL` are the Docker Cloud API resource URI and URL of the node where the container is running.
238
+
158
239
* `DOCKERCLOUD_CONTAINER_HOSTNAME` and `DOCKERCLOUD_CONTAINER_FQDN` are the external hostname and Fully Qualified Domain Name (FQDN) of the container itself.
240
+
159
241
* `DOCKERCLOUD_SERVICE_HOSTNAME` and `DOCKERCLOUD_SERVICE_FQDN` are the external hostname and Fully Qualified Domain Name (FQDN) of the service to which the container belongs.
242
+
160
243
* `DOCKERCLOUD_NODE_HOSTNAME` and `DOCKERCLOUD_NODE_FQDN` are the external hostname and Fully Qualified Domain Name (FQDN) of the node where the container is running.
161
244
162
245
These environment variables are also copied to linked containers with the `NAME_ENV_` prefix.
163
246
164
-
If you provide API access to your service, you can use the generated token (stored in `DOCKERCLOUD_AUTH`) to access these API URLs to gather information or automate operations, such as scaling.
247
+
If you provide API access to your service, you can use the generated token
248
+
(stored in `DOCKERCLOUD_AUTH`) to access these API URLs to gather information or
0 commit comments