jpetazzo/pipeworkReadme / Intro / Install / Usage / Examples / Config
Configuration of pipework is performed by setting environment variables. There are 2 kinds of configuration:
- Environment variables which are set on your master pipwork container. i.e. Global options.
- Environment variables which you set on each of your app / service containers.
Environment variables can be set by appending the docker run command with successive -e switches. Or by adding them to the existing service definitions in your orchestration tool's .yml file.
When a kvaps/pipework container is run, it will boot up, then docker inspect other running containers on the same docker host. As dictated by the user-specified run_mode and certain other kinds of configurable filter criteria 1, and 2. For any inspected container, if an environment variable matching the globbing battern of pipework_cmd= is encountered. Then those command line arguments are passed on to @jpetazzo's pipework script for processing.
The environment variable sets a configuration option which affects all of the containers for which pipework commands are being appled to.
The environment variable sets a local configuration option which affects only to that specific container upon which the environment variable has been set. I.e. only when pipework commands are being applied to that specific container.
Some configuration variables have a globbing pattern. For these variables, you may add any arbitrary string prefix or suffix to the environment variable name. And they will all be matched / found by regex.
Add a custom prefix or suffix (or both) to declare multiple pipework cmds. For example:
pipework_cmd_for_eth0=eth0 @CONTAINER_NAME@ dhcp # host NIC 1
pipework_cmd_for_eth1=eth1 @CONTAINER_NAME@ dhcp # host NIC 2
Will result in both commands being executed on the same container. To set up multiple networking interfaces with pipework. Each command in the sequence will be processed serially (one at a time). Commands are run in alphabetical order, according to the unix sort program. Thefore pipework_cmd_A=will always be executed beforepipework_cmd_B=`.
Another example:
apache_pipework_cmd=eth0 -i eth1 @CONTAINER_NAME@ dhcp # bound to host NIC
mysql__pipework_cmd=br1 -i eth2 @CONTAINER_NAME@ dhcp # bound to private bridge
You may also use the same prefix or suffix to selectively specify the host_route option for only certain interfaces. For example, if we then set:
apache_host_route=true
It would mean that the Docker Host can now access the container's eth1 interface. But not it's private br1 link.
- Setting environment variables on the
kvaps/pipeworkcontainer is how you set global configuration options. - You may omit the optional prefix
pipework_at the beginning of any environment variable names. - For example:
debug=trueis the same aspipework_debug=true. Enabling either option will have the same effect. - Most users only need to set the
run_modeandhost_routesoptions. - Other global configuration options can largely be ignored.
Default value: manual - Sets: Run Mode(s) - Scope: Global
A comma seperated list of the run mode(s) to launch. See the [Run Modes](2. Usage.md#run-modes) usage section for more information about each run mode. This example shows the recommended configuration for any orchestration tool (e.g. Compose, Crane, Kubernetes):
pipework_run_mode=batch,daemon
The allowed values are:
pipework_run_mode="manual,batch,daemon,both,all"
You can specify any combination of run modes in any order. However they will always be executed in the following order: manual, then batch, then daemon.
Default value: false - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
If set to true (or any value). Sets up networking to allow the host computer to see and communicate over pipework networking with the application containers. It creates for the host a L2 macvlan bridge to each app / client container that has had a pipework_cmd invoked upon it. Example:
pipework_host_routes=true
Default value: false - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
If set to true (or any value) will ensure that the more rigorous arping command is used to determine network liveness. Only use if this container's ipv4 address (or if other hosts in highest subnet ipv4 ranges) will not respond to regular ICMP ping requests. Example:
pipework_host_route_arping=true
Disabled by default because it introduces an substantial delay of 2 additional seconds per ipv4 host route. This variable has no effect, and is not needed for ipv6 addresses.
Default value: inet - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
This variable has no effect, and is not needed for ipv4 only addresses.
If set to inet, or left as nothing / null string, then inet is the default value. Which means IPV4. Only host routes are setup for a container's IPV4 address. This is to avoid any potential bugs related to this entrypoint.sh script's IPV6 functionality. The OS may itself auto-generate an IPV6 address for the host route bridge interface, but we will not add a path to the container's IPV6 address (if it has one). Other possible settings are: inet inet6, and just inet6. The IPV6 functionality is considered to be untested. Example:
pipework_host_route_protocols="inet inet6"
This is a global setting and cannot be configured on a per-container basis.
Globbing pattern: .*cmd.*= - Default value:* none - Affects: [Manual Mode](2. Usage.md#manual) - Scope: Local
If set on the master pipework container, then will be used instead of the extra cmd line arguments during single-instance invokation (for run manual). The @TEMPLATE@ macro expansion placeholders cannot be used with this run mode.
pipework_cmd="eth0 7fe4d4dc916c dhcp"
Default value: none - Affects: [Batch Mode](2. Usage.md#batch),[Daemon Mode](2. Usage.md#daemon) - Scope: Global
When pipework_key is set on the master pipework container, then any application or service container wishing to be configured by pipework must also have the variable pipework_key set to the same value. Or else it will be ignored / not recognised. Example:
pipework_key="APScQYDITSrNt+9YS13INVP6m/3oH/iSlh4Gc7R or any un-guessable string"
Default value: 0 - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
The number of seconds to sleep before executing the specified run mode(s). It is not necessary to ever set this variable, except under certain very special conditions. Example:
pipework_sleep=3
Not to be confused with the forever-blocking pipework --wait cmdline option to be used within your client containers.
Default value: false - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
Turns on extra shell script debugging / trace output with set -x / sh -x.
Default value: none - Affects: [Daemon Mode](2. Usage.md#daemon) - Scope: Global
Comma seperated list of event filtering argumends. Can be used to restrict the set of containers which pipework inspects. And containers which do not match the criteria will be ignored. For example:
pipework_event_filters="image=redis,container=myapp,container=7fe4d4dc916c"
Will generate the following extra arguments to docker events command:
-f 'image=redis' -f 'container=myapp' -f 'container=7fe4d4dc916c'
Affects daemon mode only. The allowed syntax is documented in the Docker manual. See: Docker Commandline Reference - 'events'
Default value: none (infinity) - Affects: [Daemon Mode](2. Usage.md#daemon) - Scope: Global
Number of seconds to stay active in daemon mode. After which time, the daemon mode will quit. By default, this variable is not set to anything. And daemon mode continues listening forever. Until the pipework container is stopped. Example:
pipework_up_time=60
Default value: none (disabled) - Affects: [Daemon Mode](2. Usage.md#daemon) - Scope: Global
Wait N seconds after a container has dies before running next pipework command. By default, this variable is set to a value of 0 seconds for the default dhcp client busybox udhcpc. Example:
pipework_cleanup_wait=30
Default value: none (disabled) - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
If pipework fails, then wait N seconds and retry the same pipework command. By default, this variable is not set to anything. And pipework will be run only once, regardless of it's success / failure exit code. The pipework command will be re-tried only once. Example:
pipework_retry_delay=5
Default value: none (disabled) - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
Wait N seconds in-between the running of successive pipework commands. By default, this variable is not set to anything. And pipework will not wait. Example:
pipework_inter_delay=5
Default value: none (disabled) - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Global
Wait N seconds after creating a host route macvlan bridge, before adding the route to the container's IP address. By default, this variable is not set to anything. And pipework will not wait. Example:
pipework_route_add_delay=1
Note:
This setting might not be needed. However it was found necessary during my testing with the pipework v1.1.3 image (or higher) while running on an ubuntu 15.04 host machine. Just a 1 second delay was enough time to give the new bridge to settle down before adding the container's host route onto it.
Without introducing the artificial delay, the command would appear to succeed inside the container. While outside no new entry to be seen on the routing table / no ping.
Set these on each of your individual application / service containers. Which are the clients of your pipework instance. Each container found by the pipework instance will be inspected and acted upon, providing that other filtering critera are also met. You must always to use the pipework_ prefix on your application containers, at all times. All other environment variables will be ignored / not recognised.
Default value: none - Affects: [Batch Mode](2. Usage.md#batch),[Daemon Mode](2. Usage.md#daemon) - Scope: Local
When pipework_key is set on the master pipework container, then any application or service container wishing to be configured by pipework must also have the variable pipework_key set to the same value. Or else it will be ignored / not recognised. Example:
pipework_key="APScQYDITSrNt+9YS13INVP6m/3oH/iSlh4Gc7R or any un-guessable string"
Globbing pattern: .*pipework_cmd.*= - Default value: none - Affects: [Batch Mode](2. Usage.md#batch),[Daemon Mode](2. Usage.md#daemon) - Scope: Local
The pipework command to run for this container. Any @TEMPLATE@ macro placeholders will be expanded / substituted for real values before the pipework command is executed. Example:
pipework_cmd="eth0 @CONTAINER_NAME@ dhcp"
Globbing pattern: .*pipework_host_route.*= - Default value: false - Affects: [Batch Mode](2. Usage.md#batch),[Daemon Mode](2. Usage.md#daemon) - Scope: Local
If set to true (or any value) will allow the host computer can see and communicate with the container. Creates for the host a macvlan bridge on an individual per-interface and per-container basis (rather than globally or at the whole container level). Example:
pipework_host_route=true
This variable has no effect, and is not needed if you already set the other option pipework_host_routes=true on either the app container or the pipework container.
Default value: false - Affects: [Batch Mode](2. Usage.md#batch),[Daemon Mode](2. Usage.md#daemon) - Scope: Local
If set to true (or any value). Same as pipework_host_route except applys to all pipework_cmds on the same container. Example:
pipework_host_routes=true
This variable has no effect, and is not needed if you already set the global option pipework_host_routes=true on the pipework container.
Default value: false - Affects: [Batch Mode](2. Usage.md#batch),[Daemon Mode](2. Usage.md#daemon) - Scope: Local
If set to true (or any value) will ensure that the more rigorous arping command is used to determine network liveness. Only use if this container's ipv4 address (or if other hosts in highest subnet ipv4 ranges) will not respond to regular ICMP ping requests. Example:
pipework_host_route_arping=true
Disabled by default because it introduces an substantial delay of 2 additional seconds per ipv4 host route. This variable has no effect, and is not needed for ipv6 addresses.
Default value: none (disabled) - Affects: [Daemon Mode](2. Usage.md#daemon) - Scope: Local
Wait N seconds after a container has dies before running next pipework command. By default, this variable is set to a value of 0 seconds for the default dhcp client busybox udhcpc. Example:
pipework_cleanup_wait=30
Default value: none (disabled) - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Local
If pipework fails, then wait N seconds and retry the same pipework command. By default, this variable is not set to anything. And pipework will be run only once, regardless of it's success / failure exit code. The pipework command will be re-tried only once. Example:
pipework_retry_delay=5
Default value: none (disabled) - Affects: [All Run Modes](2. Usage.md#run-modes) - Scope: Local
Wait N seconds in-between the running of successive pipework commands. By default, this variable is not set to anything. And pipework will not wait. Example:
pipework_inter_delay=5