mirror of https://github.com/docker/docs.git
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
Joao Fernandes
parent
a79cdddc09
commit
08d355c6d1
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
description: Docker Universal Control Plane
|
||||
keywords: networking, kv, engine-discovery, ucp
|
||||
title: Enable container networking with UCP
|
||||
title: Configure the HTTP Routing Mesh
|
||||
description: Learn how to configure UCP's HTTP Routing Mesh
|
||||
keywords: ucp, services, http, dns
|
||||
---
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
If a service is not configured properly for use of the HTTP routing mesh, this
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
@ -12,18 +12,26 @@ cluster.
|
|||
|
||||
|
||||
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
|
||||
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
|
||||
[HTTP routing mesh service is enabled](../../admin/configure/use-domain-names-to-access-services.md)
|
||||
and you have access to the `ucp-hrm` network.
|
||||
[HTTP routing mesh service is enabled](../../admin/configure/use-domain-names-to-access-services.md),
|
||||
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
|
||||
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
|
||||
**Create a service**. Then create an NGIN service with the following
|
||||
**Create a service**. Then create an NGINX service with the following
|
||||
configurations:
|
||||
|
||||
| Field | Value |
|
||||
|
|
@ -31,6 +39,8 @@ configurations:
|
|||
| Service name | nginx |
|
||||
| Image name | nginx |
|
||||
| Internal port | 80 |
|
||||
| Protocol | tcp |
|
||||
| Publish Mode | ingress |
|
||||
| Public port | 8000 |
|
||||
| External scheme | http:// |
|
||||
| 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.
|
||||
|
||||
{: .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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue