diff --git a/_data/toc.yaml b/_data/toc.yaml index bed96aef10..5b97afdef8 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1699,6 +1699,18 @@ manuals: path: /ee/ucp/interlock/ - title: Architecture path: /ee/ucp/interlock/architecture/ + - sectiontitle: Deploy + section: + - title: Simple deployment + path: /ee/ucp/interlock/deploy/ + - title: Production deployment + path: /ee/ucp/interlock/deploy/production/ + - title: Configure your deployment + path: /ee/ucp/interlock/deploy/configure/ + - title: Configuration reference + path: /ee/ucp/interlock/deploy/configuration-reference/ + + - sectiontitle: Introduction section: - title: What is Layer 7 routing diff --git a/ee/ucp/interlock/configuration/index.md b/ee/ucp/interlock/configuration/index.md deleted file mode 100644 index 77a60222cd..0000000000 --- a/ee/ucp/interlock/configuration/index.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Configure Interlock -description: Learn about Interlock, an application routing and load balancing system - for Docker Swarm. -keywords: ucp, interlock, load balancing -ui_tabs: -- version: ucp-3.0 - orhigher: false ---- - -{% if include.version=="ucp-3.0" %} - -Interlock configuration is managed via file as [TOML](https://github.com/toml-lang/toml). -The following will describe how to configure the various components of Interlock. - -## Core -The core configuration handles the Interlock service itself. The following options -are available: - -| Option | Type | Description | -|:-------------------|:------------|:----------------------------------------------------------------------------------------------| -| `ListenAddr` | string | address to serve the Interlock GRPC API (default: `:8080`) | -| `DockerURL` | string | path to the socket or TCP address to the Docker API (default: `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 (default: `3s`) | -| `EndpointOverride` | string | override the default GRPC API endpoint for extensions (by default this is detected via Swarm) | -| `Extensions` | []Extension | array of extensions as listed below | - -## Extension -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 be added to 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 be added to the proxy service | -| `ProxyServiceName` | string | name of the proxy service | -| `ProxyConfigPath` | string | path in the service for the generated proxy config | -| `ServiceCluster` | string | name of the cluster this extension services | -| `PublishMode` | string (`ingress` or `host`) | publish mode that the proxy service uses | -| `PublishedPort` | int | port that the proxy service serves non-SSL traffic | -| `PublishedSSLPort` | int | port that the proxy service serves SSL traffic | -| `Template` | string | Docker config object that is used as the extension template | -| `Config` | Config | proxy configuration used by the extensions as listed below | - -## Proxy -The following options are made available to the extensions. The extensions use whichever they need to configure -the proxy service. This provides a way for the user to provide overrides to the extension configuration. - -Interlock passes extension configuration through directly to the extension. Therefore, each extension has -different configuration options available. See the docs for each extension for the officially supported options. - -## Example Configuration -The following is an example configuration to use with the Nginx extension. - -```toml -ListenAddr = ":8080" -DockerURL = "unix:///var/run/docker.sock" -PollInterval = "3s" - -[Extensions] - [Extensions.default] - Image = "docker/interlock-extension-nginx:latest" - Args = ["-D"] - ProxyImage = "nginx:alpine" - ProxyArgs = [] - ProxyConfigPath = "/etc/nginx/nginx.conf" - ServiceCluster = "" - PublishMode = "ingress" - PublishedPort = 80 - TargetPort = 80 - PublishedSSLPort = 443 - TargetSSLPort = 443 - [Extensions.default.Config] - User = "nginx" - PidPath = "/var/run/proxy.pid" - WorkerProcesses = 1 - RlimitNoFile = 65535 - MaxConnections = 2048 - [Extensions.default.Labels] - extension_name = "defaultExtension" - [Extensions.default.ProxyLabels] - proxy_name = "defaultProxy" -``` - -{% endif %} diff --git a/ee/ucp/interlock/deploy/configuration-reference.md b/ee/ucp/interlock/deploy/configuration-reference.md new file mode 100644 index 0000000000..099775c760 --- /dev/null +++ b/ee/ucp/interlock/deploy/configuration-reference.md @@ -0,0 +1,155 @@ +--- +title: Layer 7 routing configuration reference +description: Learn about Interlock, an application routing and load balancing system + for Docker Swarm. +keywords: ucp, interlock, load balancing +ui_tabs: +- version: ucp-3.0 + orhigher: false +--- + +{% if include.version=="ucp-3.0" %} + +Once you enable the layer 7 routing service, UCP creates the +`com.docker.ucp.interlock.conf-1` configuration and uses it to configure all +the internal components of this service. + +The configuration is managed as a TOML file. + +## Example configuration + +Here's an example of the default configuration used by UCP: + +```toml +ListenAddr = ":8080" +DockerURL = "unix:///var/run/docker.sock" +AllowInsecure = false +PollInterval = "3s" + +[Extensions] + [Extensions.default] + Image = "dockereng/ucp-interlock-extension:3.0.0-2e21c4d" + ServiceName = "ucp-interlock-extension" + Args = [""] + Constraints = ["node.labels.com.docker.ucp.orchestrator.swarm==true"] + ProxyImage = "dockereng/ucp-interlock-proxy:3.0.0-2e21c4d" + ProxyServiceName = "ucp-interlock-proxy" + ProxyConfigPath = "/etc/nginx/nginx.conf" + ProxyReplicas = 2 + ProxyStopSignal = "SIGQUIT" + ProxyStopGracePeriod = "5s" + ProxyConstraints = ["node.labels.com.docker.ucp.orchestrator.swarm==true"] + PublishMode = "ingress" + PublishedPort = 80 + TargetPort = 80 + PublishedSSLPort = 8443 + TargetSSLPort = 443 + [Extensions.default.Labels] + "com.docker.ucp.InstanceID" = "xybt14ctipeasd7lfggl4hw94" + [Extensions.default.ContainerLabels] + "com.docker.ucp.InstanceID" = "xybt14ctipeasd7lfggl4hw94" + [Extensions.default.ProxyLabels] + "com.docker.ucp.InstanceID" = "xybt14ctipeasd7lfggl4hw94" + [Extensions.default.ProxyContainerLabels] + "com.docker.ucp.InstanceID" = "xybt14ctipeasd7lfggl4hw94" + [Extensions.default.Config] + Version = "" + User = "nginx" + PidPath = "/var/run/proxy.pid" + MaxConnections = 1024 + ConnectTimeout = 600 + SendTimeout = 600 + ReadTimeout = 600 + IPHash = false + AdminUser = "" + AdminPass = "" + SSLOpts = "" + SSLDefaultDHParam = 1024 + SSLDefaultDHParamPath = "" + SSLVerify = "required" + WorkerProcesses = 1 + RLimitNoFile = 65535 + SSLCiphers = "HIGH:!aNULL:!MD5" + SSLProtocols = "TLSv1.2" + AccessLogPath = "/dev/stdout" + ErrorLogPath = "/dev/stdout" + MainLogFormat = "'$remote_addr - $remote_user [$time_local] \"$request\" '\n\t\t '$status $body_bytes_sent \"$http_referer\" '\n\t\t '\"$http_user_agent\" \"$http_x_forwarded_for\"';" + TraceLogFormat = "'$remote_addr - $remote_user [$time_local] \"$request\" $status '\n\t\t '$body_bytes_sent \"$http_referer\" \"$http_user_agent\" '\n\t\t '\"$http_x_forwarded_for\" $request_id $msec $request_time '\n\t\t '$upstream_connect_time $upstream_header_time $upstream_response_time';" + KeepaliveTimeout = "75s" + ClientMaxBodySize = "32m" + ClientBodyBufferSize = "8k" + ClientHeaderBufferSize = "1k" + LargeClientHeaderBuffers = "4 8k" + ClientBodyTimeout = "60s" + UnderscoresInHeaders = false +``` + +## Core configurations + +These are the configurations used for the `ucp-interlock` service. The following +options are available: + +| 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. | +| `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 proxy service upon creation. | +| `ProxyLabels` | map[string]string | Labels to add to the proxy service. | +| `ProxyServiceName` | string | Name of the proxy service. | +| `ProxyConfigPath` | string | Path in the service for the generated proxy configuration. | +| `ServiceCluster` | string | Name of the cluster this extension services. | +| `PublishMode` | string | Publish mode for the proxy service. Supported values are `ingress` or `host`. | +| `PublishedPort` | int | Port where the proxy service serves non-TLS traffic. | +| `PublishedSSLPort` | int | Port where the proxy service serves TLS traffic. | +| `Template` | string | Docker configuration object that is used as the extension template. | +| `Config` | Config | Proxy configuration used by the extensions as listed below. | + +## Proxy configuration + +By default NGINX is used as a proxy, so the following NGINX options are +available for the proxy service: + +| Option | Type | Description | +|:------------------------|:-------|:-----------------------------------------------------------------------------------------------------| +| `User` | string | User to be used in the proxy. | +| `PidPath` | string | Path to the pid file for the proxy service. | +| `MaxConnections` | int | Maximum number of connections for proxy service. | +| `ConnectTimeout` | int | Timeout in seconds for clients to connect. | +| `SendTimeout` | int | Timeout in seconds for the service to send a request to the proxied upstream. | +| `ReadTimeout` | int | Timeout in seconds for the service to read a response from the proxied upstream. | +| `IPHash` | bool | Specifies that requests are distributed between servers based on client IP addresses. | +| `SSLOpts` | string | Options to be passed when configuring SSL. | +| `SSLDefaultDHParam` | int | Size of DH parameters. | +| `SSLDefaultDHParamPath` | string | Path to DH parameters file. | +| `SSLVerify` | string | SSL client verification. | +| `WorkerProcesses` | string | Number of worker processes for the proxy service. | +| `RLimitNoFile` | int | Number of maxiumum open files for the proxy service. | +| `SSLCiphers` | string | SSL ciphers to use for the proxy service. | +| `SSLProtocols` | string | Enable the specified TLS protocols. | +| `AccessLogPath` | string | Path to use for access logs (default: `/dev/stdout`). | +| `ErrorLogPath` | string | Path to use for error logs (default: `/dev/stdout`). | +| `MainLogFormat` | string | [Format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) to use for main logger. | +| `TraceLogFormat` | string | [Format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) to use for trace logger. | + + +{% endif %} diff --git a/ee/ucp/interlock/deploy/configure.md b/ee/ucp/interlock/deploy/configure.md new file mode 100644 index 0000000000..f3da5a6a81 --- /dev/null +++ b/ee/ucp/interlock/deploy/configure.md @@ -0,0 +1,63 @@ +--- +title: Configure the layer 7 routing service +description: Learn about Interlock, an application routing and load balancing system + for Docker Swarm. +keywords: ucp, interlock, load balancing +ui_tabs: +- version: ucp-3.0 + orhigher: false +--- + +{% if include.version=="ucp-3.0" %} + +[When enabling the layer 7 routing solution](index.md) from the UCP web UI, +you can configure the ports for incoming traffic. If you want to further +customize the layer 7 routing solution, you can do it by updating the +`ucp-interlock` service with a new Docker configuration object. + +Here's how it works: + +1. Find out what configuration is currently being used for the `ucp-interlock` +service and save it to a file: + +{% raw %} +```bash +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 +``` +{% endraw %} + +2. Make the necessary changes to the `config.toml` file. +[Learn about the configuration options available](configuration-reference.md). +3. Create a new Docker configuration object from the file you've edited: + +``` +NEW_CONFIG_NAME="com.docker.ucp.interlock.conf-$(( $(cut -d '-' -f 2 <<< "$CURRENT_CONFIG_NAME") + 1 ))" +docker config create $NEW_CONFIG_NAME config.toml +``` + +3. 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 \ + --stop-signal SIGQUIT \ + --stop-grace-period 5s \ + ucp-interlock +``` + +By default the `ucp-interlock` service is configured to pause if something +goes wrong with the configuration update. The service won't do any updates +without manual intervention. + +If you want the service to automatically rollback to a previous stable +configuration, you can update the service with: + +``` +docker service update \ + --update-failure-action rollback \ + ucp-interlock +``` + +{% endif %} diff --git a/ee/ucp/interlock/extensions/haproxy.md b/ee/ucp/interlock/extensions/haproxy.md deleted file mode 100644 index 8f14acd3d9..0000000000 --- a/ee/ucp/interlock/extensions/haproxy.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Use HAProxy with Interlock -description: Learn about Interlock, an application routing and load balancing system - for Docker Swarm. -keywords: ucp, interlock, load balancing -ui_tabs: -- version: ucp-3.0 - orhigher: false ---- - -{% if include.version=="ucp-3.0" %} - -The following configuration options are available: - -| Option | Type | Description | -|:--------------------|:-------|:--------------------------------------------------------------------------------| -| `PidPath` | string | path to the pid file for the proxy service | -| `MaxConnections` | int | maximum number of connections for proxy service | -| `ConnectTimeout` | int | timeout in seconds for clients to connect | -| `ClientTimeout` | int | timeout in seconds for the service to send a request to the proxied upstream | -| `ServerTimeout` | int | timeout in seconds for the service to read a response from the proxied upstream | -| `AdminUser` | string | username to be used with authenticated access to the proxy service | -| `AdminPass` | string | password to be used with authenticated access to the proxy service | -| `SSLOpts` | string | options to be passed when configuring SSL | -| `SSLDefaultDHParam` | int | size of DH parameters | -| `SSLVerify` | string | SSL client verification | -| `SSLCiphers` | string | SSL ciphers to use for the proxy service | -| `SSLProtocols` | string | enable the specified TLS protocols | - -## Notes - -When using SSL termination the certificate and key must be combined into a single certificate (i.e. `cat cert.pem key.pem > combined.pem`). The HAProxy extension -will use the certificate label only to configure SSL. - -{% endif %} diff --git a/ee/ucp/interlock/extensions/nginx.md b/ee/ucp/interlock/extensions/nginx.md deleted file mode 100644 index b4889329eb..0000000000 --- a/ee/ucp/interlock/extensions/nginx.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Use NGINX with Interlock -description: Learn about Interlock, an application routing and load balancing system - for Docker Swarm. -keywords: ucp, interlock, load balancing -ui_tabs: -- version: ucp-3.0 - orhigher: false ---- - -{% if include.version=="ucp-3.0" %} - -The following configuration options are available for the Nginx extension: - -| Option | Type | Description | -|:------------------------|:-------|:----------------------------------------------------------------------------------------------------| -| `User` | string | user to be used in the proxy | -| `PidPath` | string | path to the pid file for the proxy service | -| `MaxConnections` | int | maximum number of connections for proxy service | -| `ConnectTimeout` | int | timeout in seconds for clients to connect | -| `SendTimeout` | int | timeout in seconds for the service to send a request to the proxied upstream | -| `ReadTimeout` | int | timeout in seconds for the service to read a response from the proxied upstream | -| `IPHash` | bool | specifies that requests are distributed between servers based on client IP addresses | -| `SSLOpts` | string | options to be passed when configuring SSL | -| `SSLDefaultDHParam` | int | size of DH parameters | -| `SSLDefaultDHParamPath` | string | path to DH parameters file | -| `SSLVerify` | string | SSL client verification | -| `WorkerProcesses` | string | number of worker processes for the proxy service | -| `RLimitNoFile` | int | number of maxiumum open files for the proxy service | -| `SSLCiphers` | string | SSL ciphers to use for the proxy service | -| `SSLProtocols` | string | enable the specified TLS protocols | -| `AccessLogPath` | string | Path to use for access logs (default: `/dev/stdout`) | -| `ErrorLogPath` | string | Path to use for error logs (default: `/dev/stdout`) | -| `MainLogFormat` | string | [Format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) to use for main logger | -| `TraceLogFormat` | string | [Format](http://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) to use for trace logger | - -{% endif %}