From 08d355c6d1303d7537156d25c40d65acbfac3510 Mon Sep 17 00:00:00 2001 From: Adrian Kreher Date: Fri, 17 Feb 2017 11:52:53 -0800 Subject: [PATCH] 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. --- .../use-domain-names-to-access-services.md | 111 ++-------------- .../2.1/guides/user/services/hrm-labels.md | 118 ++++++++++++++++++ .../use-hostnames-to-access-your-service.md | 26 +++- 3 files changed, 149 insertions(+), 106 deletions(-) create mode 100644 datacenter/ucp/2.1/guides/user/services/hrm-labels.md diff --git a/datacenter/ucp/2.1/guides/admin/configure/use-domain-names-to-access-services.md b/datacenter/ucp/2.1/guides/admin/configure/use-domain-names-to-access-services.md index 1c6ed0ca58..cc2140affa 100644 --- a/datacenter/ucp/2.1/guides/admin/configure/use-domain-names-to-access-services.md +++ b/datacenter/ucp/2.1/guides/admin/configure/use-domain-names-to-access-services.md @@ -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 - - - -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 diff --git a/datacenter/ucp/2.1/guides/user/services/hrm-labels.md b/datacenter/ucp/2.1/guides/user/services/hrm-labels.md new file mode 100644 index 0000000000..e9ae697ebd --- /dev/null +++ b/datacenter/ucp/2.1/guides/user/services/hrm-labels.md @@ -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` diff --git a/datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service.md b/datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service.md index 02342f1456..78a9f11fec 100644 --- a/datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service.md +++ b/datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service.md @@ -12,18 +12,26 @@ cluster. ![](../../images/use-hostnames-to-access-your-service-1.svg) 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. ![](../../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.