Configure layer 7 routing service

Configure layer 7 routing service¶

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

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

Make the necessary changes to the config.toml file.

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

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 MKE 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.

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 extenstion.
`Args`	[]string	Arguments to be passed to the extension service.
`Labels`	map[string]string	Labels to add to the extension service.
`Networks`	[]string	Allows the administrator to cherry-pick a list of networks that Interlock can connect to. If this option is not specified, the proxy-service can connect to all networks.
`ContainerLabels`	map[string]string	labels for the extension service tasks.
`Constraints`	[]string	One or more constraints to use when scheduling the extenstion service.
`PlacementPreferences`	[]string	One of more placement prefs.
`ServiceName`	string	Name of the extension service.
`ProxyImage`	string	Name of the Docker image to use for the proxy service.
`ProxyArgs`	[]string	Arguments to pass to the proxy service.
`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`	unit	Number or proxy service replicas.
`ProxyStopSignal`	string	Stop signal for the proxy service, for example `SIGQUIT`.
`ProxyStopGracePeriod`	string	Stop grace period for the proxy service in seconds, for example `5s`.
`ProxyConstraints`	[]string	One or more constraints to use when scheduling the proxy service. Set the variable to `false`, as it is currenlty set to `true` by default.
`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`	int	Docker configuration object that is used as the extension template.
`Config`	Config	Proxy configuration used by the extensions as described in this section.
`HitlessServiceUpdate`	bool	When set to `true`, services can be updated without restarting the proxy container.
`ConfigImage`	Config	Name for the config service (used by hitless service updates). For example, `docker/ucp-interlock-config:3.2.1`.
`ConfigServiceName`	Config	Name of the config service. This name is equivalent to `ProxyServiceName`. For example, `ucp-interlock-config`.

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

updated: 2023-07-26 11:20

Configure

View Previous Section

Configure host mode networking