Configure layer 7 routing service

Estimated reading time: 8 minutes

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 pause if you provide an invalid configuration. The service will not restart without manual intervention.

If you want the service to automatically rollback to a previous stable configuration, you can update it with the following command:

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

Note: Every time 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 configuraton handles the Interlock service itself. These are the configuration options for the ucp-interlock service:

Option Type Description
ListenAddr string Address to serve the Interlock GRPC API. Defaults to 8080.
DockerURL string Path to the socket or TCP address to the Docker API. Defaults to unix:///var/run/docker.sock
TLSCACert string Path to the CA certificate for connecting securely to the Docker API.
TLSCert string Path to the certificate for connecting securely to the Docker API.
TLSKey string Path to the key for connecting securely to the Docker API.
AllowInsecure bool Skip TLS verification when connecting to the Docker API via TLS.
PollInterval string Interval to poll the Docker API for changes. Defaults to 3s.
EndpointOverride string Override the default GRPC API endpoint for extensions. The default is detected via Swarm.
Extensions []Extension Array of extensions as listed below.

Extension configuration

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

Option Type Description
Image string Name of the Docker Image to use for the extension service
Args []string Arguments to be passed to the Docker extension service upon creation
Labels map[string]string Labels to add to the extension service
ContainerLabels map[string]string labels to be added to the extension service tasks
Constraints []string one or more constraints to use when scheduling the extension service
PlacementPreferences []string one or more placement prefs to use when scheduling the extension service
ServiceName string Name of the extension service
ProxyImage string Name of the Docker Image to use for the proxy service
ProxyArgs []string Arguments to be passed to the Docker proxy service upon creation
ProxyLabels map[string]string Labels to add to the proxy service
ProxyContainerLabels map[string]string labels to be added to the proxy service tasks
ProxyServiceName string Name of the proxy service
ProxyConfigPath string Path in the service for the generated proxy config
ProxyReplicas uint number of proxy service replicas
ProxyStopSignal string stop signal for the proxy service (i.e. SIGQUIT)
ProxyStopGracePeriod string stop grace period for the proxy service (i.e. 5s)
ProxyConstraints []string one or more constraints to use when scheduling the proxy service
ProxyPlacementPreferences []string one or more placement prefs to use when scheduling the proxy service
ProxyUpdateDelay string delay between rolling proxy container updates
ServiceCluster string Name of the cluster this extension services
PublishMode string (ingress or host) Publish mode that the proxy service uses
PublishedPort int Port on which the proxy service serves non-SSL traffic
PublishedSSLPort int Port on which the proxy service serves SSL traffic
Template string Docker configuration object that is used as the extension template
Config Config Proxy configuration used by the extensions as described in the following table

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:

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:

Default NGINX page

You can customize this by labelling 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.

Custom default page

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.0"
  Args = ["-D"]
  ServiceName = "interlock-ext"
  ProxyImage = "docker/ucp-interlock-proxy:3.2.0"
  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

routing, proxy, interlock, load balancing