Skip to content

Container Back-ends

Overview

ContainerProxy supports multiple container back-ends to run specs, namely

  • a plain Docker host (default)
  • a Docker Swarm cluster and
  • a Kubernetes cluster

The backend can be configured using

proxy:
  container-backend: docker  

The container-backend can be one of docker (default), docker-swarm or kubernetes. The specific configuration these back-ends is documented below.

Docker

The Docker back-end is the default back-end for ContainerProxy. In order to specify it explicitly, one can set proxy.container-backend to docker.

The configuration of the back-end can be done using the following properties:

  • cert-path: path to the folder that contains the certificate files (ca.pem, cert.pem and key.pem) used for encrypted traffic to the docker daemon; if the files have other names or are located in different folders, symbolic links can be used (for ca.pem, cert.pem and key.pem) that point to the actual certificate files. If a non-existing path is used as cert-path, traffic will not be encrypted; the default value for cert-path is set to /home/none; this property can be omitted when not applicable;
  • url: URL and port on which to connect to the docker daemon; the default value of http://localhost:2375 does not connect over TLS; this is not recommended for production environments;
  • container-protocol: optional setting to indicate the protocol to be used to communicate with the containers; can be one of http or https; if not set, the protocol is derived from the url specified (cf. above);
  • privileged: run all containers with extended privileges (true) or not (false; default value);
  • port-range-start: every docker container will be assigned a port on the docker host to which the ContainerProxy will proxy the traffic of a particular user; the value of port-range-start will be the port assigned to the first container that is started; by default the first port will be 20000 (second 20001, third 20002 etc.).
  • port-range-max: maximum port number to be handled by ContainerProxy (e.g. 20099, which allows to run a maximum of 100 containers if port-range-start is set to the default value 20000); this allows to limit the number of concurrent specs that can be managed by a single ContainerProxy instance or, in case multiple ContainerProxy instances launch docker containers on a shared Docker Swarm, can prevent the same port number being used by multiple such instances; the default value of port-range-max is -1 (no maximum). If the port pool is exhausted, the following error message will appear:
Cannot start container: all allocated ports are currently in use. Please try again later or contact an administrator.
  • internal-networking: set this to true if ContainerProxy will run as a container on the same Docker host; default value is false.

Note:

  • when internal-networking is true, no ports will be allocated per proxy and the port range settings are ignored (port-range-start and port-range-max); also, the proxy target URLs will use the container host name.

Docker Swarm

In order to use a Docker Swarm back-end, set proxy.container-backend to docker-swarm. The configuration of the back-end is not different from the configuration of a plain Docker back-end (cf. supra).

Note:

  • when internal-networking is true, no ports will be allocated per proxy and the port range settings are ignored (port-range-start and port-range-max); also, the proxy target URLs will use the container name.

Kubernetes

In order to use a Kubernetes back-end, set proxy.container-backend to kubernetes. The configuration of the back-end can be done using the following properties:

  • proxy.kubernetes.url: the URL of the apiserver
  • proxy.kubernetes.cert-path: the path to a dir containing ca.pem, cert.pem and key.pem to be used if url is https
  • proxy.kubernetes.namespace: the namespace to create pods in; the default value is default
  • proxy.kubernetes.api-version: the API version to use; the default value is v1
  • proxy.kubernetes.image-pull-policy: the pull policy for images; the default value is IfNotPresent
  • proxy.kubernetes.image-pull-secret: the name of a secret to use for pulling images from a registry
  • proxy.kubernetes.image-pull-secrets: see above, but for multiple secrets
  • proxy.kubernetes.privileged: run all containers with extended privileges (true) or not (false; default value);
  • proxy.kubernetes.internal-networking: set this to true if ContainerProxy will run inside the cluster itself; default value is false
  • proxy.kubernetes.container-protocol: the protocol to use when accessing a container; can be one of http (default) or https
  • proxy.kubernetes.port: the TCP port to access on the container; the default port is 3838

An example configuration is:

proxy:
  container-backend: kubernetes
  kubernetes:
    cert-path: /etc/certs
    url: https://1.2.3.4

Note:

  • when internal-networking is true, no ports will be allocated per proxy and the proxy target URLs will use the Pod IP.