docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve/modularize the UCP HRM docs 

Resolves #1732. This separates out the use cases into three audiences:
administrators who configure UCP and HRM, users who use the web UI, and
users who use the Docker CLI or API. The CLI reference also provides a
guide to the label syntax and the full set of features.
This commit is contained in:
Adrian Kreher 2017-02-17 11:52:53 -08:00 committed by Joao Fernandes
parent a79cdddc09
commit 08d355c6d1
3 changed files with 149 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
datacenter/ucp/2.1/guides/admin/configure/use-domain-names-to-access-services.md
View File

@ -1,7 +1,7 @@
--- ---
description: Docker Universal Control Plane title: Configure the HTTP Routing Mesh
keywords: networking, kv, engine-discovery, ucp description: Learn how to configure UCP's HTTP Routing Mesh
title: Enable container networking with UCP keywords: ucp, services, http, dns
--- ---
UCP provides an HTTP routing mesh, that extends the networking capabilities UCP provides an HTTP routing mesh, that extends the networking capabilities
@ -56,62 +56,6 @@ This service must meet three criteria:
These options can be configured using the UCP UI, or can be entered manually These options can be configured using the UCP UI, or can be entered manually
using the `docker service` command. using the `docker service` command.
### Route to a service using the UI
<!-- todo: expand, add screenshots -->
When using the wizard to create services in the UCP UI, you may enable the HTTP
routing mesh for a service by publishing a port, and filling in the options
relating to "Routing Mesh Host".
### Route to a service using the CLI
The key of the label must begin with `com.docker.ucp.mesh.http`. For multiple
labels, some examples could be `com.docker.ucp.mesh.http.80` and
`com.docker.ucp.mesh.http.443`. Here `80` and `443` are used to differentiate
the HRM labels via port numbers. You can use whatever values you want, just
make sure they are different from each other and you can keep track of them.
Labels with the prefix `com.docker.ucp.mesh.http` allow you to configure a
single hostname and port to route to a service. If you wish to route multiple
ports or hostnames to the same service, then multiple labels with the prefix
`com.docker.ucp.mesh.http` may be created.
The syntax of this label is as follows:
The key of the label must begin with `com.docker.ucp.mesh.http`, for example
`com.docker.ucp.mesh.http.80` and `com.docker.ucp.mesh.http.443`.
The value of the label is a comma separated list of key/value pairs separated
by equals signs. These pairs are optional unless noted below, and are as
follows:
* `external_route` **(required)** the external URL to route to this service.
Examples: `http://myapp.example.com` and `sni://myapp.example.com`
* `internal_port`: the internal port to use for the service. Examples: `80`,
`8443`. This is **required** if more one port is published by the service.
* `sticky_sessions`: if present, use the named cookie to route the user to the
same backend task for this service. See the "Sticky Sessions" section below.
* `redirect`: if present, perform redirection to the specified URL. See the
"Redirection" section below.
Examples:
A service based on the image `myimage/mywebserver:latest` with a webserver running on port
8080 can be routed to `http://foo.example.com` can be created using the
following:
```sh
$ docker service create \
-p 8080 \
--network ucp-hrm \
--label com.docker.ucp.mesh.http.8080=external_route=http://foo.example.com,internal_port=8080 \
--name myservice \
myimage/mywebserver:latest
```
Next, you will need to route the referenced domains to the HTTP routing mesh.
## Route domains to the HTTP routing mesh ## Route domains to the HTTP routing mesh
The HTTP routing mesh uses the `Host` HTTP header (or the Server Name The HTTP routing mesh uses the `Host` HTTP header (or the Server Name
@ -136,6 +80,13 @@ routing mesh. Once the HTTP routing mesh is enabled, it will be able to route
to all services attached to any of these networks, but services on different to all services attached to any of these networks, but services on different
networks cannot communicate directly. networks cannot communicate directly.
## Using the HTTP routing mesh
Once DNS and networks are configured, you can begin setting up services for
these domains. See the guides for the [UCP web
UI](../../user/services/use-hostnames-to-access-your-service.md) and [Docker
CLI](../../user/services/hrm-labels.md).
## Disable the HTTP routing mesh ## Disable the HTTP routing mesh
To disable the HTTP routing mesh, first ensure that all services that are using To disable the HTTP routing mesh, first ensure that all services that are using
@ -144,48 +95,6 @@ the HTTP routing mesh are disconnected from the **ucp-hrm** network.
Next, go to the **UCP web UI**, navigate to the **Settings** page, and click Next, go to the **UCP web UI**, navigate to the **Settings** page, and click
the **Routing Mesh** tab. Uncheck the checkbox to disable the HTTP routing mesh. the **Routing Mesh** tab. Uncheck the checkbox to disable the HTTP routing mesh.
## Additional Routing Features
The HTTP routing mesh provides some additional features for some specific use
cases.
### Sticky Sessions
Enable the sticky sessions option for a route if your application requires that
a user's session continues to use the same task of a backend service. This
option uses HTTP cookies to choose which task receives a given connection.
The cookie name for this feature is configured as the value of this option
within the label. The cookie must be created by the application, and its value
is used to pick a backend task.
Stickyness may be lost temporarily if the number of tasks for a service
changes, or if a service is reconfigured in a way that requires all of its
tasks to restart.
This option is incompatible with the `sni` protocol (routing HTTPS connections
without termination).
### Redirection
The `redirect` option indicates that all requests to this route should be
redirected to another domain name using a HTTP redirect.
One use of this feature is for a service which only listens using HTTPS, with
HTTP traffic to it being redirected to HTTPS. If the service is on
`example.com`, then this can be accomplished with two labels:
* `com.docker.ucp.mesh.http.1=external_route=http://example.com,redirect=https://example.com`
* `com.docker.ucp.mesh.http.2=external_route=sni://example.com`
Another use is a service expecting traffic only on a single domain, but other
domains should be redirected to it. For example, a website that has been
renamed might use this functionality. The following labels accomplish this for
`new.example.com` and `old.example.com`
* `com.docker.ucp.mesh.http.1=external_route=http://old.example.com,redirect=http://new.example.com`
* `com.docker.ucp.mesh.http.2=external_route=http://new.example.com`
## Troubleshoot ## Troubleshoot
If a service is not configured properly for use of the HTTP routing mesh, this If a service is not configured properly for use of the HTTP routing mesh, this

118
datacenter/ucp/2.1/guides/user/services/hrm-labels.md Normal file
View File

@ -0,0 +1,118 @@
---
title: Use the Docker CLI to configure hostnames to access your service
description: Learn how to configure your services to make them accessible using a hostname instead of IP addresses and ports, using the Docker CLI.
keywords: ucp, services, http, dns
---
UCP's HTTP routing mesh provides configuration through the web UI, but it is
also possible to configure a service by using the Docker CLI directly. This
information is stored in the labels of the services and other configuration of
the service. This guide will walk you through configuring a sample service for
use with the HTTP routing mesh and also provide a full reference to the label
syntax.
This configuration can be performed manually using the Docker CLI. It is also
appropriate to use this in automation, either using the Docker CLI or the
Docker Remote API directly.
The HTTP routing mesh can route to a Docker service that runs a webserver (HTTP
or HTTPS). This service must meet three criteria:
* The service must be connected a network with a `com.docker.ucp.mesh.http` label
* The service must publish the ports that you wish to route
* The service must have one or more labels prefixed with
`com.docker.ucp.mesh.http` to specify the ports to route (see the syntax
below)
## Route to a service using the CLI
### Networks
Services must be connected to a network that has a `com.docker.ucp.mesh.http`
label. The value is not relevant. A `ucp-hrm` network is created for you
automatically when enabling the HTTP routing mesh, or your administrators may
create one for you. Refer to the administrator's guide for more information.
### Service Labels
The key of the label must begin with `com.docker.ucp.mesh.http`. For multiple
labels, some examples could be `com.docker.ucp.mesh.http.80` and
`com.docker.ucp.mesh.http.443`. Here `80` and `443` are used to differentiate
the HRM labels via port numbers. You can use whatever values you want, just
make sure they are different from each other and you can keep track of them.
Labels with the prefix `com.docker.ucp.mesh.http` allow you to configure a
single hostname and port to route to a service. If you wish to route multiple
ports or hostnames to the same service, then multiple labels with the prefix
`com.docker.ucp.mesh.http` may be created.
### Example using the CLI
A service based on the image `myimage/mywebserver:latest` with a webserver
running on port 8080 can be routed to `http://foo.example.com` can be created
using the following:
```sh
$ docker service create \
-p 8080 \
--network ucp-hrm \
--label com.docker.ucp.mesh.http.8080=external_route=http://foo.example.com,internal_port=8080 \
--name myservice \
myimage/mywebserver:latest
```
## Service Label Syntax
The key of the label must begin with `com.docker.ucp.mesh.http`, for example
`com.docker.ucp.mesh.http.80` and `com.docker.ucp.mesh.http.443`.
The value of the label is a comma separated list of key/value pairs separated
by equals signs. These pairs are optional unless noted below, and are as
follows:
* `external_route` **(required)** the external URL to route to this service.
Examples: `http://myapp.example.com` and `sni://myapp.example.com`
* `internal_port`: the internal port to use for the service. Examples: `80`,
`8443`. This is **required** if more one port is published by the service.
* `sticky_sessions`: if present, use the named cookie to route the user to the
same backend task for this service. See the "Sticky Sessions" section below.
* `redirect`: if present, perform redirection to the specified URL. See the
"Redirection" section below.
### Sticky Sessions
Enable the sticky sessions option for a route if your application requires that
a user's session continues to use the same task of a backend service. This
option uses HTTP cookies to choose which task receives a given connection.
The cookie name for this feature is configured as the value of this option
within the label. The cookie must be created by the application, and its value
is used to pick a backend task.
Stickyness may be lost temporarily if the number of tasks for a service
changes, or if a service is reconfigured in a way that requires all of its
tasks to restart.
This option is incompatible with the `sni` protocol (routing HTTPS connections
without termination).
### Redirection
The `redirect` option indicates that all requests to this route should be
redirected to another domain name using a HTTP redirect.
One use of this feature is for a service which only listens using HTTPS, with
HTTP traffic to it being redirected to HTTPS. If the service is on
`example.com`, then this can be accomplished with two labels:
* `com.docker.ucp.mesh.http.1=external_route=http://example.com,redirect=https://example.com`
* `com.docker.ucp.mesh.http.2=external_route=sni://example.com`
Another use is a service expecting traffic only on a single domain, but other
domains should be redirected to it. For example, a website that has been
renamed might use this functionality. The following labels accomplish this for
`new.example.com` and `old.example.com`
* `com.docker.ucp.mesh.http.1=external_route=http://old.example.com.com,redirect=http://new.example.com`
* `com.docker.ucp.mesh.http.2=external_route=http://new.example.com`

26
datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service.md
View File

@ -12,18 +12,26 @@ cluster.
![](../../images/use-hostnames-to-access-your-service-1.svg) ![](../../images/use-hostnames-to-access-your-service-1.svg)
UCP takes this one step further and allows you to configure your HTTP or HTTPS UCP takes this one step further and allows you to configure your HTTP or HTTPS
services to make them available using hostnames. services to make them available using hostnames while sharing the same port.
This simplifies configuration, with each service specifies the hostname or
hostnames that it handles, giving your team fewer places to configure common
options for routing.
In this example we're going to deploy an NGINX service and make it available In this example we're going to deploy an NGINX service and make it available
with the hostname `app.ucp.example.com`. with the hostname `app.ucp.example.com`. This guide uses the UCP web UI. The
same functionality is [provided via the Docker CLI and API using
labels](hrm-labels.md).
## Configuring a service for the HTTP routing mesh using the UCP web UI
Start by making sure that the Start by making sure that the
[HTTP routing mesh service is enabled](../../admin/configure/use-domain-names-to-access-services.md) [HTTP routing mesh service is enabled](../../admin/configure/use-domain-names-to-access-services.md),
and you have access to the `ucp-hrm` network. you have access to the `ucp-hrm` network, and that DNS records are configured.
If you don't have administrator credentials, ask your system administrator to If you don't have administrator credentials, ask your system administrator to
enable the HTTP routing mesh, and grant you access to the `ucp-hrm` network. enable the HTTP routing mesh, and grant you access to the `ucp-hrm` network.
Log in the **UCP web UI**, navigate to the **Services** page, and click Log in the **UCP web UI**, navigate to the **Services** page, and click
**Create a service**. Then create an NGIN service with the following **Create a service**. Then create an NGINX service with the following
configurations: configurations:
| Field | Value | | Field | Value |
@ -31,6 +39,8 @@ configurations:
| Service name | nginx | | Service name | nginx |
| Image name | nginx | | Image name | nginx |
| Internal port | 80 | | Internal port | 80 |
| Protocol | tcp |
| Publish Mode | ingress |
| Public port | 8000 | | Public port | 8000 |
| External scheme | http:// | | External scheme | http:// |
| Routing mesh host | app.ucp.example.com | | Routing mesh host | app.ucp.example.com |
@ -65,3 +75,9 @@ Now when you access `http://app.ucp.example.com` from your browser, you'll see
the default NGINX page. the default NGINX page.
![](../../images/use-hostnames-to-access-your-service-5.png){: .with-border} ![](../../images/use-hostnames-to-access-your-service-5.png){: .with-border}
## Next Steps
Once you have configured the HTTP routing mesh with a simple service, you may
want to explore other configuration options, including configuration using the
Docker CLI or advanced options.