Configure layer 7 routing service

This topic applies to Docker Enterprise.

The Docker Enterprise platform business, including products, customers, and employees, has been acquired by Mirantis, inc., effective 13-November-2019. For more information on the acquisition and how it may affect you and your business, refer to the Docker Enterprise Customer FAQ.

To further customize the layer 7 routing solution, you must update the ucp-interlock service with a new Docker configuration.

1. Find out what configuration is currently being used for the ucp-interlock service and save it to a file:

   CURRENT_CONFIG_NAME=$(docker service inspect --format '{{ (index .Spec.TaskTemplate.ContainerSpec.Configs 0).ConfigName }}' ucp-interlock)
   docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > config.toml
   

2. Make the necessary changes to the config.toml file. See TOML file configuration options for more information.

3. Create a new Docker configuration object from the config.toml file:

   NEW_CONFIG_NAME="com.docker.ucp.interlock.conf-$(( $(cut -d '-' -f 2 <<< "$CURRENT_CONFIG_NAME") + 1 ))"
   docker config create $NEW_CONFIG_NAME config.toml
   

4. Update the ucp-interlock service to start using the new configuration:

   docker service update \
     --config-rm $CURRENT_CONFIG_NAME \
     --config-add source=$NEW_CONFIG_NAME,target=/config.toml \
     ucp-interlock
   

By default, the ucp-interlock service is configured to roll back to a previous stable configuration if you provide an invalid configuration.

If you want the service to pause instead of rolling back, you can update it with the following command:

docker service update \
  --update-failure-action pause \
  ucp-interlock

Note

When you enable the layer 7 routing solution from the UCP UI, the ucp-interlock service is started using the default configuration.

If you’ve customized the configuration used by the ucp-interlock service, you must update it again to use the Docker configuration object you’ve created.

TOML file configuration options

The following sections describe how to configure the primary Interlock services:

• Core
• Extension
• Proxy

Core configuration

The core configuration handles the Interlock service itself. The following configuration options are available for the ucp-interlock service.

Extension configuration

Interlock must contain at least one extension to service traffic. The following options are available to configure the extensions.

Proxy

Options are made available to the extensions, and the extensions utilize the options needed for proxy service configuration. This provides overrides to the extension configuration.

Because Interlock passes the extension configuration directly to the extension, each extension has different configuration options available. Refer to the documentation for each extension for supported options:

• NGINX

Customize the default proxy service

The default proxy service used by UCP to provide layer 7 routing is NGINX. If users try to access a route that hasn’t been configured, they will see the default NGINX 404 page:

You can customize this by labeling a service with com.docker.lb.default_backend=true. In this case, if users try to access a route that’s not configured, they are redirected to this service.

As an example, create a docker-compose.yml file with:

version: "3.2"

services:
  demo:
    image: ehazlett/interlock-default-app
    deploy:
      replicas: 1
      labels:
        com.docker.lb.default_backend: "true"
        com.docker.lb.port: 80
    networks:
      - demo-network

networks:
  demo-network:
    driver: overlay

Set up your CLI client with a UCP client bundle, and deploy the service:

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

If users try to access a route that’s not configured, they are directed to this demo service.

To minimize forwarding interruption to the updating service while updating a single replicated service, use com.docker.lb.backend_mode=vip.

Example Configuration

The following is an example configuration to use with the NGINX extension.

ListenAddr = ":8080"
DockerURL = "unix:///var/run/docker.sock"
PollInterval = "3s"

[Extensions.default]
  Image = "docker/interlock-extension-nginx:3.2.6"
  Args = ["-D"]
  ServiceName = "interlock-ext"
  ProxyImage = "docker/ucp-interlock-proxy:3.2.6"
  ProxyArgs = []
  ProxyServiceName = "interlock-proxy"
  ProxyConfigPath = "/etc/nginx/nginx.conf"
  ProxyStopGracePeriod = "3s"
  PublishMode = "ingress"
  PublishedPort = 80
  ProxyReplicas = 1
  TargetPort = 80
  PublishedSSLPort = 443
  TargetSSLPort = 443
  [Extensions.default.Config]
    User = "nginx"
    PidPath = "/var/run/proxy.pid"
    WorkerProcesses = 1
    RlimitNoFile = 65535
    MaxConnections = 2048

Next steps

• Configure host mode networking
• Configure an NGINX extension
• Use application service labels
• Tune the proxy service
• Update Interlock services