Update deploy services with Interlock

_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

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.
+Once the [layer 7 routing solution is enabled](../deploy/index.md), you can
-Using [Service Labels](https://docs.docker.com/engine/reference/commandline/service_create/#set-metadata-on-a-service--l-label)
+start using it in your swarm services.
-the service is configured to publish itself to the load balancer.
 
-Note: the examples below assume a DNS entry (or local hosts entry if you are testing local) exists
+In this example we'll deploy a simple service which:
-for each of the applications.
 
-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`
+## Deploy the service
-- `com.docker.lb.port`
 
-The `com.docker.lb.hosts` label instructs Interlock where the service should be available.
+Create a `docker-compose.yml` file with:
-The `com.docker.lb.port` label instructs what port the proxy service should use to access
-the upstreams.
 
-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
+networks:
-$> docker network create -d overlay demo
+  demo-network:
-1se1glh749q1i4pw0kf26mfx5
+    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 \
+docker stack deploy --compose-file docker-compose.yml demo
-    --name demo \
-    --network demo \
-    --label com.docker.lb.hosts=demo.local \
-    --label com.docker.lb.port=8080 \
-    ehazlett/docker-demo
-6r0wiglf5f3bdpcy6zesh1pzx
 ```
 
-Interlock will detect once the service is available and publish it.  Once the tasks are running
+The `ucp-interlock` service detects that your service is using these labels
-and the proxy service has been updated the application should be available via `http://demo.local`
+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
+curl --header "Host: app.example.org" \
-{"instance":"c2f1afe673d4","version":"0.1",request_id":"7bcec438af14f8875ffc3deab9215bc5"}
+  http://<ucp-address>:<routing-http-port>/ping
 ```
 
-To increase service capacity use the Docker Service [Scale](https://docs.docker.com/engine/swarm/swarm-tutorial/scale-service/) command:
+Where:
 
-```bash
+* `<ucp-address>` is the domain name or IP address of a UCP node.
-$> docker service scale demo=4
+* `<routing-http-port>` is the [port you're using to route HTTP traffic](../deploy/index.md).
-demo scaled to 4
+
+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
+## Test using a browser
-across all service replicas.
+
+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" %}