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
andkey.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 (forca.pem
,cert.pem
andkey.pem
) that point to the actual certificate files. If a non-existing path is used ascert-path
, traffic will not be encrypted; the default value forcert-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 ofhttp
orhttps
; if not set, the protocol is derived from theurl
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 ofport-range-start
will be the port assigned to the first container that is started; by default the first port will be20000
(second20001
, third20002
etc.).port-range-max
: maximum port number to be handled by ContainerProxy (e.g.20099
, which allows to run a maximum of 100 containers ifport-range-start
is set to the default value20000
); 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 ofport-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 totrue
if ContainerProxy will run as a container on the same Docker host; default value isfalse
.
Note:
- when
internal-networking
istrue
, no ports will be allocated per proxy and the port range settings are ignored (port-range-start
andport-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
istrue
, no ports will be allocated per proxy and the port range settings are ignored (port-range-start
andport-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 apiserverproxy.kubernetes.cert-path
: the path to a dir containingca.pem
,cert.pem
andkey.pem
to be used if url is httpsproxy.kubernetes.namespace
: the namespace to create pods in; the default value isdefault
proxy.kubernetes.api-version
: the API version to use; the default value isv1
proxy.kubernetes.image-pull-policy
: the pull policy for images; the default value isIfNotPresent
proxy.kubernetes.image-pull-secret
: the name of a secret to use for pulling images from a registryproxy.kubernetes.image-pull-secrets
: see above, but for multiple secretsproxy.kubernetes.privileged
: run all containers with extended privileges (true
) or not (false
; default value);proxy.kubernetes.internal-networking
: set this totrue
if ContainerProxy will run inside the cluster itself; default value isfalse
proxy.kubernetes.container-protocol
: the protocol to use when accessing a container; can be one ofhttp
(default) orhttps
proxy.kubernetes.port
: the TCP port to access on the container; the default port is3838
An example configuration is:
proxy: container-backend: kubernetes kubernetes: cert-path: /etc/certs url: https://1.2.3.4
Note:
- when
internal-networking
istrue
, no ports will be allocated per proxy and the proxy target URLs will use the Pod IP.