diff --git a/_data/toc.yaml b/_data/toc.yaml index 5b97afdef8..62a326b66d 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1709,6 +1709,11 @@ manuals: path: /ee/ucp/interlock/deploy/configure/ - title: Configuration reference path: /ee/ucp/interlock/deploy/configuration-reference/ + - sectiontitle: Route traffic to services + section: + - title: Simple swarm service + path: /ee/ucp/interlock/usage/ + - sectiontitle: Introduction diff --git a/ee/ucp/images/route-simple-app-1.png b/ee/ucp/images/route-simple-app-1.png new file mode 100644 index 0000000000..38a4402e41 Binary files /dev/null and b/ee/ucp/images/route-simple-app-1.png differ diff --git a/ee/ucp/interlock/usage/index.md b/ee/ucp/interlock/usage/index.md index 23863399bb..8e16c3eca8 100644 --- a/ee/ucp/interlock/usage/index.md +++ b/ee/ucp/interlock/usage/index.md @@ -1,5 +1,5 @@ --- -title: Basic deployment +title: Route traffic to a simple swarm service description: Learn about Interlock, an application routing and load balancing system for Docker Swarm. keywords: ucp, interlock, load balancing @@ -11,60 +11,94 @@ ui_tabs: {% if include.version=="ucp-3.0" %} -Once Interlock has been deployed you are now ready to launch and publish applications. -Using [Service Labels](https://docs.docker.com/engine/reference/commandline/service_create/#set-metadata-on-a-service--l-label) -the service is configured to publish itself to the load balancer. +Once the [layer 7 routing solution is enabled](../deploy/index.md), you can +start using it in your swarm services. -Note: the examples below assume a DNS entry (or local hosts entry if you are testing local) exists -for each of the applications. +In this example we'll deploy a simple service which: -To publish we will create a Docker Service using two labels: +* Has a JSON endpoint that returns the ID of the task serving the request. +* Has a web UI that shows how many tasks the service is running. +* Can be reached at `http://app.example.org`. -- `com.docker.lb.hosts` -- `com.docker.lb.port` +## Deploy the service -The `com.docker.lb.hosts` label instructs Interlock where the service should be available. -The `com.docker.lb.port` label instructs what port the proxy service should use to access -the upstreams. +Create a `docker-compose.yml` file with: -In this example we will publish a demo service to the host `demo.local`. +```yaml +version: "3.2" -First we will create an overlay network so that service traffic is isolated and secure: +services: + demo: + image: ehazlett/docker-demo + deploy: + replicas: 1 + labels: + com.docker.lb.hosts: app.example.org + com.docker.lb.network: demo-network + com.docker.lb.port: 8080 + networks: + - demo-network -```bash -$> docker network create -d overlay demo -1se1glh749q1i4pw0kf26mfx5 +networks: + demo-network: + driver: overlay ``` -Next we will deploy the application: +Note that: + +* The `com.docker.lb.hosts` label defines the hostname for the service. When +the layer 7 routing solution gets a request containing `app.example.org` in +the host header, that request is forwarded to the demo service. +* The `com.docker.lb.network` defines which network the `ucp-interlock-proxy` +should attach to in order to be able to communicate with the demo service. +To use layer 7 routing, your services need to be attached to at least one network. +If your service is only attached to a single network, you don't need to add +a label to specify which network to use for routing. +* The `com.docker.lb.port` label specifies which port the `ucp-interlock-proxy` +service should use to communicate with this demo service. +* Your service doesn't need to expose a port in the swarm routing mesh. All +communications are done using the network you've specified. + +Set up your CLI client with a [UCP client bundle](../../user-access/cli.md), +and deploy the service: ```bash -$> docker service create \ - --name demo \ - --network demo \ - --label com.docker.lb.hosts=demo.local \ - --label com.docker.lb.port=8080 \ - ehazlett/docker-demo -6r0wiglf5f3bdpcy6zesh1pzx +docker stack deploy --compose-file docker-compose.yml demo ``` -Interlock will detect once the service is available and publish it. Once the tasks are running -and the proxy service has been updated the application should be available via `http://demo.local` +The `ucp-interlock` service detects that your service is using these labels +and automatically reconfigures the `ucp-interlock-proxy` service. + +## Test using the CLI + +To test that requests are routed to the demo service, run: ```bash -$> curl -s -H "Host: demo.local" http://127.0.0.1/ping -{"instance":"c2f1afe673d4","version":"0.1",request_id":"7bcec438af14f8875ffc3deab9215bc5"} +curl --header "Host: app.example.org" \ + http://:/ping ``` -To increase service capacity use the Docker Service [Scale](https://docs.docker.com/engine/swarm/swarm-tutorial/scale-service/) command: +Where: -```bash -$> docker service scale demo=4 -demo scaled to 4 +* `` is the domain name or IP address of a UCP node. +* `` is the [port you're using to route HTTP traffic](../deploy/index.md). + +If everything is working correctly, you should get a JSON result like: + +```json +{"instance":"63b855978452", "version":"0.1", "request_id":"d641430be9496937f2669ce6963b67d6"} ``` -The four service replicas will be configured as upstreams. The load balancer will balance traffic -across all service replicas. +## Test using a browser + +Since the demo service exposes an HTTP endpoint, you can also use your browser +to validate that everything is working. + +Make sure the `/etc/hosts` file in your system has an entry mapping +`app.example.org` to the IP address of a UCP node. Once you do that, you'll be +able to start using the service from your browser. + +![browser](../../images/route-simple-app-1.png){: .with-border } {% elsif include.version=="ucp-2.2" %}