Route traffic to a simple swarm service

Estimated reading time: 2 minutes

Once the layer 7 routing solution is enabled, you can start using it in your swarm services.

In this example we’ll deploy a simple service which:

  • 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

Deploy the service

Create a docker-compose.yml file with:

version: "3.2"

    image: ehazlett/docker-demo
      replicas: 1
      labels: demo-network 8080
      - demo-network

    driver: overlay

Note that:

  • The label defines the hostname for the service. When the layer 7 routing solution gets a request containing in the host header, that request is forwarded to the demo service.
  • The 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 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, and deploy the service:

docker stack deploy --compose-file docker-compose.yml demo

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:

curl --header "Host:" \


If everything is working correctly, you should get a JSON result like:

{"instance":"63b855978452", "version":"0.1", "request_id":"d641430be9496937f2669ce6963b67d6"}

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 to the IP address of a UCP node. Once you do that, you’ll be able to start using the service from your browser.


routing, proxy