Skip to content

Latest commit

 

History

History
212 lines (133 loc) · 9.57 KB

2. Usage.md

File metadata and controls

212 lines (133 loc) · 9.57 KB

Pipework reference: jpetazzo/pipework
Readme / Intro / Install / Usage / Examples / Config

Usage

Supported Clients

If you are already using an orchestration tool, then quickest way to familiarize yourself is to look at one of the example .yml files on the [Examples](3. Examples.md) page. After that, you may wish to read further about the various different configuration constructs, which are: [environment variables](4. Config.md#environment-variables), run modes, macro expansions.

Command line usage (single invocation)

Full documentation on the pipework script can be found at jpetazzo/pipework.

Cmdline Usage (docker run):

docker run -v /var/run/docker.sock:/docker.sock --privileged=true --pid=host --net=host \
  kvaps/pipework --help

Docker Compose

To see how to use pipework in compose, take a look at the [example docker-compose.yml](3. Examples.md#compose_example).

Crane

To see how to use pipework in crane, take a look at the [example crane.yml](3. Examples.md#crane_example).

Run modes

The run mode or run modes determine the behaviour of the pipework container, and the ways that it will invoke the pipework command. The default value is manual, if no run_mode= [environment variable](4. Config.md#run_mode) was set. However if your containers are being run from an orchestration tool such as crane, docker compose, or kubernetes. Then it is always best to set the run_mode to be both, or batch,daemon.

Expaination of each of the permitted run modes:

manual

Manually specified commands. Just as you would run pipework script from the command line on your host system. Does not accept @TEMPLATE@ macro expansions.

If you execute docker run kvaps/pipework <args> on the command line:

  • The arguments <args> are passed directly into jpetazzo's pipework script.
  • A [host_route](4. Config.md#host_route) may be set up. If the option -e host_route=true was specified.
  • Then manual mode will exit.

Or in non-interactive environments:

  • You may instead specify multiple arguments as [.*cmd.*=](4. Config.md#cmd) environment variables.
  • If cmd is set by an environment variable, then any command line <args> at the end of docker run will be ignored.

batch

  • Batch mode operates on the output of docker ps -q.
  • Only works on containers which are currently running at the present time.
  • Batch mode is single-shot, and will complete after processing once the current list of running containers.
  • You may use this mode alone, once you are sure all of your application containers have finished starting.
  • Or you may use batch in combination with daemon mode (recommended. To ensure that all of your containers (present and future) are not overlooked.

daemon

  • In daemon mode, the pipework container will never exit.
  • This mode launches a processing loop that listens for output from docker events --filter='event=start'.
  • Once daemon mode is started, then new containers being brought online after that time will checked for a valid pipework_cmd= environment variable.
  • But only if the container also fulfils other user-configurable filtering criteria.
  • If the pipework_cmd is permitted to be executed, then the pipework script will be invoked immediately upon that container. As soon as it can be serviced by the processing loop.
  • daemon mode is recommended in combination with batch mode, for orchestration environments such as docker compose, crane, and kubernetes.
  • You can run pipework's daemon mode continuously from system boot. If you prefer to keep the kvaps/pipework image outside of your orchestration tool's .yml file.
  • Create the pipework container with --restart=always flag to be started automatically at boot time (recommended).
  • Be sure to specify batch mode too, since the container startup order is not guaranteed, and client containers may be started before the pipework container itself has a change to drop into daemon mode and start listening.

both

A synonym for batch,daemon. Batch mode will be executed first, then the container will drop into daemon mode.

all

A synonym for manual,batch,daemon. The single-instance invokation manual mode will be run first. Then batch mode. Then finally daemon mode.

Macro expansions

Only valid for batch and daemon run modes. These macros can be used within the pipework_cmd environment string, and will be expanded / auto-filled from the container's metadata.

@CONTAINER_NAME@

The docker container name. As set by docker run --name=. But minus any leading /.

@CONTAINER_ID@

The docker container id. Shortened to the first 12 characters.

@HOSTNAME@

The container's HOSTNAME. As set by docker run --hostname=.

@INSTANCE@

If the container name contains any numeric components, then the last numeric component in the container name. For example prod_myapp_1 --> is determined to be instance number 1 of prod_myapp.

This variable is primarily useful for specifying some part of an ip address.

@COMPOSE_PROJECT_NAME@

If the container is started by the docker-compose command, it is project name like set in docker-compose --project-name .

This variable is useful for differing the containter by the project. For example, you want to set different internal bridge for each project.

Known Errors

API version mismatch

This is usually because the version of docker inside this container is too different than the veryion of docker you are running it in. For example: Docker v1.7.1 compatibility issue.

For older Docker v1.7.1 compatibility, please use Larry's fork over here ---> larrycai/pipework:1.7.1.

Or to rebuild with any different docker version, may need to rebuild with modification to the Dockerfile. For example something like this.

No output, returns immediately

<no output whatsoever>
<command returns immediately>

If using docker compose run as a single invokation, without pipework_daemon=true. Then Compose may be too slow to attach to a tty in time to grab any output. If this happens, you might not see anything output to the console. You can avoid this problem by setting -e pipework_wait=1.

mount: permission denied

mount: permission denied
Could not make a tmpfs mount. Did you use -privileged?

You didn't use --privileged flag. Or you instead tried to set many individual --cap-add= flags, but not enough of them, or the right ones.

RTNETLINK answers: No such process

RTNETLINK answers: No such process

If you try to run this pipework image without the necessary --pid=host flag, pipework will exit saying 'no such process'. OR if your container is shut down (stopped).

No output, hangs forever

<no output whatsoever>
<command hangs, CTRL+C unresponsive, does not ever exit>

This happens if you try to run pipework cmd without the necessary --net=host flag. Pipework will hang forever and do nothing. Oh dear :( seems like we could really do with some better error handling for that situation.

Other Notes

  • Specifying each capabilities individually with --cap-add= may avoid some of --privileged. But it messier on the command line. Not sure precisely which ones are required for pipework.

  • For reference - in case ipv6 isn't working for you: pipework issue #36 - ipv6 support

_ubuntu_default_ipv6_forwarding ()
{
    # these were the default ipv6 settings on my ubuntu 14.10 desktop
    sysctl net.ipv6.conf.all.accept_ra=1
    sysctl net.ipv6.conf.all.forwarding=0
}

_set_ipv6_forwarding ()
{
    # these are reccommended, at least on linode VPS servers
    sysctl net.ipv6.conf.all.accept_ra=2
    sysctl net.ipv6.conf.all.forwarding=1
}