Configure host mode networking

Estimated reading time: 6 minutes

By default, layer 7 routing components communicate with one another using overlay networks, but Interlock supports host mode networking in a variety of ways, including proxy only, Interlock only, application only, and hybrid.

When using host mode networking, you cannot use DNS service discovery, since that functionality requires overlay networking. For services to communicate, each service needs to know the IP address of the node where the other service is running.

To use host mode networking instead of overlay networking:

  1. Perform the configuration needed for a production-grade deployment
  2. Update the ucp-interlock configuration
  3. Deploy your Swarm services

Configuration for a production-grade deployment

If you have not done so, configure the layer 7 routing solution for production.

The ucp-interlock-proxy service replicas should then be running on their own dedicated nodes.

Update the ucp-interlock config

Update the ucp-interlock service configuration so that it uses host mode networking.

Update the PublishMode key to:

PublishMode = "host"

When updating the ucp-interlock service to use the new Docker configuration, make sure to update it so that it starts publishing its port on the host:

docker service update \
  --config-rm $CURRENT_CONFIG_NAME \
  --config-add source=$NEW_CONFIG_NAME,target=/config.toml \
  --publish-add mode=host,target=8080 \

The ucp-interlock and ucp-interlock-extension services are now communicating using host mode networking.

Deploy your swarm services

Now you can deploy your swarm services. Set up your CLI client with a UCP client bundle, and deploy the service. The following example deploys a demo service that also uses host mode networking:

docker service create \
  --name demo \
  --detach=false \
  --label \
  --label \
  --publish mode=host,target=8080 \
  --env METADATA="demo" \

In this example, Docker allocates a high random port on the host where the service can be reached.

To test that everything is working, run the following command:

curl --header "Host:" \


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

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

The following example describes how to configure an eight (8) node Swarm cluster that uses host mode networking to route traffic without using overlay networks. There are three (3) managers and five (5) workers. Two of the workers are configured with node labels to be dedicated ingress cluster load balancer nodes. These will receive all application traffic.

This example does not cover the actual deployment of infrastructure. It assumes you have a vanilla Swarm cluster (docker init and docker swarm join from the nodes). See the Swarm documentation if you need help getting a Swarm cluster deployed.

Note: When using host mode networking, you cannot use the DNS service discovery because that requires overlay networking. You can use other tooling such as Registrator that will give you that functionality if needed.

Configure the load balancer worker nodes (lb-00 and lb-01) with node labels in order to pin the Interlock Proxy service. Once you are logged into one of the Swarm managers run the following to add node labels to the dedicated load balancer worker nodes:

$> docker node update --label-add nodetype=loadbalancer lb-00
$> docker node update --label-add nodetype=loadbalancer lb-01

Inspect each node to ensure the labels were successfully added:

$> docker node inspect -f '{{ .Spec.Labels  }}' lb-00
$> docker node inspect -f '{{ .Spec.Labels  }}' lb-01

Next, create a configuration object for Interlock that specifies host mode networking:

$> cat << EOF | docker config create service.interlock.conf -
ListenAddr = ":8080"
DockerURL = "unix:///var/run/docker.sock"
PollInterval = "3s"

    Image = "docker/ucp-interlock-extension:3.1.6"
    Args = []
    ServiceName = "interlock-ext"
    ProxyImage = "docker/ucp-interlock-proxy:3.1.6"
    ProxyArgs = []
    ProxyServiceName = "interlock-proxy"
    ProxyConfigPath = "/etc/nginx/nginx.conf"
    ProxyReplicas = 1
    PublishMode = "host"
    PublishedPort = 80
    TargetPort = 80
    PublishedSSLPort = 443
    TargetSSLPort = 443
      User = "nginx"
      PidPath = "/var/run/"
      WorkerProcesses = 1
      RlimitNoFile = 65535
      MaxConnections = 2048

Note the PublishMode = "host" setting. This instructs Interlock to configure the proxy service for host mode networking.

Now create the Interlock service also using host mode networking:

$> docker service create \
    --name interlock \
    --mount src=/var/run/docker.sock,dst=/var/run/docker.sock,type=bind \
    --constraint node.role==manager \
    --publish mode=host,target=8080 \
    --config src=service.interlock.conf,target=/config.toml \
    { page.ucp_org }}/ucp-interlock:3.1.6 -D run -c /config.toml

Configure proxy services

With the node labels, you can re-configure the Interlock Proxy services to be constrained to the workers. From a manager run the following to pin the proxy services to the load balancer worker nodes:

$> docker service update \
    --constraint-add node.labels.nodetype==loadbalancer \

Now you can deploy the application:

$> docker service create \
    --name demo \
    --detach=false \
    --label \
    --label \
    --publish mode=host,target=8080 \
    --env METADATA="demo" \

This runs the service using host mode networking. Each task for the service has a high port (for example, 32768) and uses the node IP address to connect. You can see this when inspecting the headers from the request:

$> curl -vs -H "Host: demo.local"
curl -vs -H "Host: demo.local"
*   Trying
* Connected to ( port 80 (#0)
> GET /ping HTTP/1.1
> Host: demo.local
> User-Agent: curl/7.54.0
> Accept: */*
< HTTP/1.1 200 OK
< Server: nginx/1.13.6
< Date: Fri, 10 Nov 2017 15:38:40 GMT
< Content-Type: text/plain; charset=utf-8
< Content-Length: 110
< Connection: keep-alive
< Set-Cookie: session=1510328320174129112; Path=/; Expires=Sat, 11 Nov 2017 15:38:40 GMT; Max-Age=86400
< x-request-id: e4180a8fc6ee15f8d46f11df67c24a7d
< x-proxy-id: d07b29c99f18
< x-server-info: interlock/2.0.0-preview (17476782) linux/amd64
< x-upstream-addr:
< x-upstream-response-time: 1510328320.172
routing, proxy, interlock, load balancing