diff --git a/_data/toc.yaml b/_data/toc.yaml index 21164c9e95..2e1ebb8333 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1264,8 +1264,8 @@ manuals: section: - path: /datacenter/ucp/2.1/guides/user/services/deploy-a-service/ title: Deploy a service - - path: /datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service/ - title: Use hostnames to access your service + - path: /datacenter/ucp/2.1/guides/user/services/use-domain-names-to-access-services/ + title: Use domain names to access services - path: /datacenter/ucp/2.1/guides/user/services/ title: Deploy an app from the UI - path: /datacenter/ucp/2.1/guides/user/services/deploy-app-cli/ 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 cc2140affa..0745daadf7 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,104 +1,78 @@ --- -title: Configure the HTTP Routing Mesh -description: Learn how to configure UCP's HTTP Routing Mesh +title: Use domain names to access services +description: Docker Universal Control Plane has an HTTP routing mesh that + allows you to make your services accessible through a domain name. Learn more. keywords: ucp, services, http, dns --- -UCP provides an HTTP routing mesh, that extends the networking capabilities -of Docker Engine. Docker Engine provides load balancing and service discovery -at the transport layer for TCP and UDP connections. UCP's HTTP routing mesh -allows you to extend service discovery to have name-based virtual hosting for -HTTP and HTTPS services. +Docker has a transport-layer load balancer, also know as an L4 load balancer. +This allows you to access your services independently of the node they are +running. -See the -[Docker Engine documentation on overlay networks](/engine/swarm/networking.md) -for more information on what Docker Engine provides. +![swarm routing mesh](../../images/use-domain-names-1.svg) + +In this example, the wordpress service is being served on port 8080. +Users can access wordpress using the IP address of any node +in the cluster and port 8080. If wordpress is not running in that node, the +request is redirected to a node that is. + +UCP extends this and provides an http routing mesh for application-layer +load balancing. This allows you to access services with HTTP and HTTPS endpoints +using a domain name instead of an IP. + +![http routing mesh](../../images/use-domain-names-2.svg) + +In this example, the Wordpress service listens on port 8080 and is attached to +the `ucp-hrm` network. There's also a DNS entry mapping `wordpress.example.org` +to the IP addresses of the UCP nodes. + +When users access `wordpress.example.org:80`, the HTTP routing mesh routes +the request to the service running Wordpress in a way that is transparent to +the user. ## Enable the HTTP routing mesh To enable the HTTP routing mesh, go to the **UCP web UI**, navigate to the -**Settings** page, and click the **Routing Mesh** tab. +**Settings** page, and click the **Routing Mesh** option. +Check the **Enable HTTP routing mesh** option. - +![http routing mesh](../../images/use-domain-names-3.png){: .with-border} -The default port for HTTP services is **80**, and the default port for HTTPS -services is **8443**. You may choose an alternate port on this screen. +By default the HTTP routing mesh service listens on port 80 for HTTP and port +8443 for HTTPS. Change the ports if you already have services that are using +them. -Check the checkbox to enable the HTTP routing mesh. This will create a service -called `ucp-hrm` and a network called `ucp-hrm`. +## Under the hood -If the HTTP routing mesh receives a HTTP request for a domain that it does not -handle, it returns a 503 error (Bad Gateway). For HTTPS requests, all unknown -domains are routed to the UCP web interface. +Once you enable the HTTP routing mesh, UCP deploys: -## HTTPS support +| Name | What | Description | +|:----------|:--------|:------------------------------------------------------------------------------| +| `ucp-hrm` | Service | Receive HTTP and HTTPS requests and send them to the right service | +| `ucp-hrm` | Network | The network used to communicate with the services using the HTTP routing mesh | -The HTTP routing mesh has support for routing using HTTPS. Using a feature of -HTTPS called Server Name Indication, the HTTP routing mesh is able to route -connections to service backends without terminating the HTTPS connection. +You then deploy a service that exposes a port, attach that service to the +`ucp-hrm` network, and create a DNS entry to map a domain name to the IP +address of the UCP nodes. -To use HTTPS support, no certificates for the service are provided to the HTTP -routing mesh. Instead, the backend service **must** handle HTTPS connections -directly. Services that meet this criteria can use the `SNI` protocol to -indicate handling of HTTPS in this manner. +When a user tries to access an HTTP service from that domain name: -## Route to a service +1. The DNS resolution will point them to the IP of one of the UCP nodes +2. The HTTP routing mesh looks at the Hostname header in the HTTP request +3. If there's a service that maps to that hostname the request is routed to the +port where the service is listening +4. If not, the user receives an HTTP 503, bad gateway error -The HTTP routing mesh can route to a Docker service that runs a webserver. -This service must meet three criteria: +For services exposing HTTPS things are similar. The HTTP routing mesh doesn't +terminate the TLS connection, and instead leverages an extension to TLS called +Server Name Indication, that allows a client to announce in clear the domain +name it is trying to reach. -* The service must be connected a network with a `com.docker.ucp.mesh.http` label -* The service must publish one or more ports -* 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) +When receiving a connection in the HTTPS port, the routing mesh looks at the +Server Name Indication header and routes the request to the right service. +The service is responsible for terminating the HTTPS connection. -These options can be configured using the UCP UI, or can be entered manually -using the `docker service` command. -## Route domains to the HTTP routing mesh +## Where to go next -The HTTP routing mesh uses the `Host` HTTP header (or the Server Name -Indication field for HTTPS requests) to determine which service should receive -a particular HTTP request. This is typically done using DNS and pointing one or -more domains to one or more nodes in the UCP cluster. - -## Networks, Access Control, and the HTTP routing mesh - -The HTTP routing mesh uses one or more overlay networks to communicate with the -backend services. By default, a single network is created called `ucp-hrm`, -with the access control label `ucp-hrm`. Adding a service to this network -either requires administrator-level access, or the user must be in a group that -gives them `ucp-hrm` access. - -This default configuration does not provide any isolation between services -using the HTTP routing mesh. - -Isolation between services may be implemented by creating one or more overlay -networks with the label `com.docker.ucp.mesh.http` prior to enabling the HTTP -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 -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. - -## Troubleshoot - -If a service is not configured properly for use of the HTTP routing mesh, this -information is available in the UI when inspecting the service. - -More logging from the HTTP routing mesh is available in the logs of the -`ucp-controller` containers on your UCP manager nodes. +* [Run only the images you trust](run-only-the-images-you-trust.md) diff --git a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-1.svg b/datacenter/ucp/2.1/guides/images/use-domain-names-1.svg similarity index 78% rename from datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-1.svg rename to datacenter/ucp/2.1/guides/images/use-domain-names-1.svg index 1f6a63f808..649439a15d 100644 --- a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-1.svg +++ b/datacenter/ucp/2.1/guides/images/use-domain-names-1.svg @@ -1,7 +1,7 @@ - - use-hostnames-1 + + use-domain-names-1 Created with Sketch. @@ -31,7 +31,7 @@ - + @@ -40,7 +40,7 @@ - + worker node @@ -48,14 +48,14 @@ - - UCP worker + + UCP - - nginx + + wordpress:8000 @@ -66,7 +66,7 @@ - + worker node @@ -74,8 +74,8 @@ - - UCP worker + + UCP @@ -88,7 +88,7 @@ - + manager node @@ -96,8 +96,8 @@ - - UCP manager + + UCP @@ -108,7 +108,7 @@ - + manager node @@ -116,8 +116,8 @@ - - UCP manager + + UCP @@ -128,7 +128,7 @@ - + manager node @@ -136,8 +136,8 @@ - - UCP manager + + UCP @@ -187,7 +187,12 @@ - + + + 192.168.99.100:8000 + + + \ No newline at end of file diff --git a/datacenter/ucp/2.1/guides/images/use-domain-names-2.svg b/datacenter/ucp/2.1/guides/images/use-domain-names-2.svg new file mode 100644 index 0000000000..070eeb9340 --- /dev/null +++ b/datacenter/ucp/2.1/guides/images/use-domain-names-2.svg @@ -0,0 +1,198 @@ + + + + use-domain-names-2 + Created with Sketch. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 192.168.99.104 + + + + + + worker node + + + + + + + UCP + + + + + + wordpress:8000 + + + + + + + 192.168.99.103 + + + + + + worker node + + + + + + + UCP + + + + + + + + + 192.168.99.102 + + + + + + manager node + + + + + + + UCP + + + + + + + 192.168.99.101 + + + + + + manager node + + + + + + + UCP + + + + + + + 192.168.99.100 + + + + + + manager node + + + + + + + UCP + + + + + + + + + + + HTTP routing mesh + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + wordpress.example.org:80 + + + + + + \ No newline at end of file diff --git a/datacenter/ucp/2.1/guides/images/use-domain-names-3.png b/datacenter/ucp/2.1/guides/images/use-domain-names-3.png new file mode 100644 index 0000000000..8b6715edc3 Binary files /dev/null and b/datacenter/ucp/2.1/guides/images/use-domain-names-3.png differ diff --git a/datacenter/ucp/2.1/guides/images/use-domain-names-4.png b/datacenter/ucp/2.1/guides/images/use-domain-names-4.png new file mode 100644 index 0000000000..c542ca6e44 Binary files /dev/null and b/datacenter/ucp/2.1/guides/images/use-domain-names-4.png differ diff --git a/datacenter/ucp/2.1/guides/images/use-domain-names-5.png b/datacenter/ucp/2.1/guides/images/use-domain-names-5.png new file mode 100644 index 0000000000..11cf78c24e Binary files /dev/null and b/datacenter/ucp/2.1/guides/images/use-domain-names-5.png differ diff --git a/datacenter/ucp/2.1/guides/images/use-domain-names-6.png b/datacenter/ucp/2.1/guides/images/use-domain-names-6.png new file mode 100644 index 0000000000..5473015c94 Binary files /dev/null and b/datacenter/ucp/2.1/guides/images/use-domain-names-6.png differ diff --git a/datacenter/ucp/2.1/guides/images/use-domain-names-7.png b/datacenter/ucp/2.1/guides/images/use-domain-names-7.png new file mode 100644 index 0000000000..150affb4e3 Binary files /dev/null and b/datacenter/ucp/2.1/guides/images/use-domain-names-7.png differ diff --git a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-2.png b/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-2.png deleted file mode 100644 index f64778e900..0000000000 Binary files a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-2.png and /dev/null differ diff --git a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-3.png b/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-3.png deleted file mode 100644 index 9bd8c501ad..0000000000 Binary files a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-3.png and /dev/null differ diff --git a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-4.png b/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-4.png deleted file mode 100644 index 24f9063475..0000000000 Binary files a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-4.png and /dev/null differ diff --git a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-5.png b/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-5.png deleted file mode 100644 index d412790f98..0000000000 Binary files a/datacenter/ucp/2.1/guides/images/use-hostnames-to-access-your-service-5.png and /dev/null differ diff --git a/datacenter/ucp/2.1/guides/user/services/hrm-labels.md b/datacenter/ucp/2.1/guides/user/services/hrm-labels.md deleted file mode 100644 index e9ae697ebd..0000000000 --- a/datacenter/ucp/2.1/guides/user/services/hrm-labels.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -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-domain-names-to-access-services.md b/datacenter/ucp/2.1/guides/user/services/use-domain-names-to-access-services.md new file mode 100644 index 0000000000..9dc2b47540 --- /dev/null +++ b/datacenter/ucp/2.1/guides/user/services/use-domain-names-to-access-services.md @@ -0,0 +1,181 @@ +--- +title: Use domain names to access services +description: Learn how to configure your services to make them accessible using a hostname instead of IP addresses and ports. +keywords: ucp, services, http, dns +redirect_from: +- /datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service/ +--- + +You can make it easier for users to access your HTTP and HTTPS services, by +making them accessible from a domain name, instead of an IP address. + +![http routing mesh](../../images/use-domain-names-2.svg) + +In this example, we're going to deploy a Wordpress service and make it accessible +to users at `http://wordpress.example.org`. + +## Enable the HTTP routing mesh + +Before you start, make sure an administrator user has +[enabled the HTTP routing mesh service](../../admin/configure/use-domain-names-to-access-services.md). +You also need permissions to attach services to the `ucp-hrm` network. + +## Deploy Wordpress + +Log in the **UCP web UI**, navigate to the **Services** page, and click +**Create a service**. Then create a Wordpress service with the following +configurations: + +| Field | Value | +|:------------------|:----------------------| +| Service name | wordpress | +| Image name | wordpress:latest | +| Internal port | 80 | +| Protocol | tcp | +| Publish Mode | ingress | +| Public port | 8000 | +| External scheme | http:// | +| Routing mesh host | wordpress.example.com | + +When creating the service, make sure to publish both internal and public ports. +This maps the port 80 on the container running the service, to port 8000 on the +ingress routing mesh. + +![](../../images/use-domain-names-4.png){: .with-border} + +Then click the **Add hostname based route** to set the hostname that will +resolve to the service. + +![](../../images/use-domain-names-5.png){: .with-border} + +Finally, you need to connect the service to the `ucp-hrm` network. This is +what ensures traffic send to the HTTP routing mesh is redirected to your +service. + +![](../../images/use-domain-names-6.png){: .with-border} + +Click **Deploy now** to deploy your service. Once the service is deployed, +the HTTP routing mesh service is reconfigured to redirect HTTP requests with +the hostname set to `wordpress.example.org`, to the Wordpress service. + +## Add a DNS entry + +Now that Wordpress is deployed, add a new DNS entry that maps +`wordpress.example.org` to the IP address of any node in the UCP cluster. +When testing locally, you can also change your `/etc/hosts` file to +create this mapping, instead of using a DNS service. + +Once this is done, you can access the wordpress service from your browser. + +![](../../images/use-domain-names-7.png){: .with-border} + +## From the CLI + +To deploy the Wordpress service from the CLI, you need to add labels to the +service that are specific to the HTTP routing mesh. + +Once you get your [UCP client bundle](../access-ucp/cli-based-access.md), you +can run: + +```none +docker service create \ + --publish target=80,published=8000 \ + --network ucp-hrm \ + --label com.docker.ucp.mesh.http=external_route=http://wordpress.example.org,internal_port=80 \ + --name wordpress \ + wordpress:latest +``` + +## Under the hood + +Under the hood, UCP relies on labels to configure your services to use the +HTTP routing mesh. The UCP web UI automatically adds labels to your services, +but when deploying from the CLI or using compose files, you need to add labels +to your services. + +The HTTP routing mesh can route to a service, as long as that service: + +* Is attached to a network that has the `com.docker.ucp.mesh.http` label. You +can use the default `ucp-hrm` network or create your own +* Publishes the ports that you want to route to +* Has one or more labels with the prefix `com.docker.ucp.mesh.http`, specifying +the ports to route to + +### Service labels + +The HTTP routing mesh label that you apply to your services needs to have a list +of keys and values separated by a comma, specifying how to route the traffic to +your service. The label syntax looks like this: + +```none +com.docker.ucp.mesh.http[.label-number]==,= +``` + +Where `.label-number` is an optional number that you can include in your label +name if you want to have multiple routes to the same service. As an example +you could have one route for HTTP and another for HTTPS. In that case you'd +apply two labels: + +```none +com.docker.ucp.mesh.http.1== +com.docker.ucp.mesh.http.2== +``` + +The keys and values in your label are what defined the route configuration. +These keys are supported: + +| Key | Mandatory | Values | Description | +|:----------------|:------------------------------------------|:-----------------------------------------|:---------------------------------------------------------------------------------------------------------| +| external_route | yes | http://domain-name or sni://domain-name | The external URL to route to this service | +| internal_port | yes, if the port published multiple ports | port-number | The internal port to use for the service | +| sticky_sessions | no | cookie-name | Always route a user to the same service, using HTTP cookies. This option can't be used with HTTPS routes | +| redirect | no | http://domain-name, or sni://domain-name | Redirect incoming requests to another route using an HTTP 301 redirect | + + +### Sticky sessions + +You can use the `sticky_sessions` value to always route a user to the same +backend service. The first time a user makes a request, the service includes +a cookie in the response. When the user makes a new request, their browser +will send the cookie, and the HTTP routing mesh can use it to decide to which +service to route to. + +Since this requires the HTTP routing mesh to be able to read the cookie, this +option only works with HTTP routes. + +Sticky sessions might stop temporarily if the service is reconfigured to +change the number of replicas, or if the replicas are restarted. + +### HTTP redirects + +You can use the `redirect` option to redirect requests from one route to +another. + +This allows you to redirect traffic to a new domain name if you've renamed the +domain you're using to serve your services. For that, you apply two labels to +your service: + +```none +com.docker.ucp.mesh.http.1=external_route=http://old.example.org,redirect=http://new.example.org +com.docker.ucp.mesh.http.2=external_route=http://new.example.org +``` + +You can also use this to redirect HTTP requests to an HTTPS route. For that you +apply two labels to your service: + +```none +com.docker.ucp.mesh.http.1=external_route=http://example.org,redirect=https://example.org +com.docker.ucp.mesh.http.2=external_route=sni://example.org +``` + +### Keep services isolated + +If you want to keep the services from sharing the same network, before +enabling the HTTP routing mesh: + +1. Create multiple networks and apply the `com.docker.ucp.mesh.http` label to them +2. Enable the HTTP routing mesh +3. Attach each service to one of the different networks you've created + +The HTTP routing mesh will route to all services in these networks, but services +on different networks can't communicate directly. 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 deleted file mode 100644 index 78a9f11fec..0000000000 --- a/datacenter/ucp/2.1/guides/user/services/use-hostnames-to-access-your-service.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Use 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. -keywords: ucp, services, http, dns ---- - -When you deploy a service with an HTTP or HTTPS endpoint, you can make it -accessible to users by mapping the service port to the swarm routing mesh port. -This makes your service available using the IP address of any node in the -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 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`. 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), -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 NGINX service with the following -configurations: - -| Field | Value | -|:------------------|:--------------------| -| 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 | - -When creating the service, make sure to publish both internal and public ports. -This maps the port 80 on the container running the service, to port 8000 on the -ingress routing mesh. - -![](../../images/use-hostnames-to-access-your-service-2.png){: .with-border} - -Then click the **Add hostname based route** to set the hostname that will -resolve to the service. - -![](../../images/use-hostnames-to-access-your-service-3.png){: .with-border} - -Finally, you need to connect the service to the `ucp-hrm` network. This is -what ensures traffic send to the HTTP routing mesh is redirected to your -service. - -![](../../images/use-hostnames-to-access-your-service-4.png){: .with-border} - -Click **Deploy now** to deploy your service. Once the service is deployed, -the HTTP routing mesh service is reconfigured to redirect HTTP requests with -the hostname set to `app.ucp.example.com`, to the NGINX service. - -To make this service accessible to users, you need to add an entry to your DNS, -mapping the name `app.ucp.example.com` to the IP address of any node in the -UCP cluster. When testing locally, you can also change your `/etc/hosts` file to -create this mapping, instead of using a DNS service. - -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.