Usage¶
Derived Image¶
First usage scenario is when you build a derived image containing your
source (e.g. Ansible playbooks, etc.). An example Dockerfile
:
FROM gimoh/devops-utils
ADD . /opt/app
WORKDIR /opt/app
You may also want to add Ansible roles, or python modules, e.g.:
FROM gimoh/devops-utils
ADD reqs-*[lt] /opt/app/
RUN ansible-galaxy install --role-file /opt/app/reqs-ansible.yml
RUN pip install --requirement /opt/app/reqs-py.txt
ADD . /opt/app
WORKDIR /opt/app
Then to use:
ansible-playbook -i hosts.ini your-playbook.yml
# or
fab -l
See also Extending which may be useful for derived images.
Development / Mounted Source¶
The second usage scenario is when you want to use your development tree as source. This may be done with either the original or derived image:
devops-utils ++dev ansible-playbook -i hosts.ini your-playbook.yml
# or
ansible-playbook ++dev -i hosts.ini your-playbook.yml
This will mount current working directory as /opt/app
and set
WORKDIR
appropriately.
Notice that parameters to the runner itself start with +
instead of
the usual -
, this is to make them easier to differentiate from
parameters to the program being run.
Running¶
You can use the image without installing the runner, but some features will be unavailable (e.g. SSH agent socket, SSH key, SSH config).
The runner uses +
as option prefix character to make it easier to
distinguish between options for the runner and options for the program
being run. You can see usage help with:
devops-utils ++help
# likewise:
fab ++help
# will print the runner help message, vs
fab --help
# which will print Fabric's help message
The default options to docker run
are: -i -t --rm
.
You can pass any docker option to docker run
using the
+O / ++docker-opt
option:
devops-utils +O privileged ++docker-opt net=host bash
As hinted above, ++dev
can be used to mount source in current
working directory in the container instead of using the one baked into
the image (required if not using a derived image).
When starting the container, the SSH agent socket will be passed in if available, to enable SSH authentication using own keys.
Alternatively, you can use ++key FILE
option to pass a specific key
and it will be injected into the container as /root/.ssh/id_rsa
at
runtime.
SSH config file ~/.ssh/config
is also injected into the container
if it exists so that any special configuration for particular hosts is
respected.
Finally, you can pass ++debug
option to see how options are
processed and how arguments to the programs are manipulated.
docker-machine¶
It is possible to run docker-machine
commands within the image.
When using docker-machine
, it is important to pass the ++dev
option, otherwise any changes (like adding new machines) are lost.
docker-machine
saves configuration, like keys for servers, and
in fact the names of what servers are managed in a configuration
directory, in our image this defaults to /opt/app/.docker/machine
.
An example of using docker-machine
is:
devops-utils ++dev docker-machine upgrade fred
which would execute the docker-machine upgrade
command on host
fred
, with /opt/app mounted from current working directory.
Running the above command in your home directory would pick up any
previous docker-machine
configuration, and would save anything
that you change for use at a later date.
You can list machine configurations using:
devops-utils ++dev docker-machine ls
If you build a derived image containing the stored configurations, you
can of course drop the ++dev
option.
docker tools¶
Command line docker client, docker-compose and python code using
docker-py can be used against machines managed using
docker-machine
. To run a command against a specific machine, use
e.g.:
devops-utils ++dm=NAME docker info
This will activate machine NAME
(using docker-machine env NAME
)
before running the command (docker
CLI in this case).
Similarly to deploy containers defined in docker compose file (in
current directory) on machine NAME
:
devops-utils ++dev ++dm=NAME docker-compose up -d
Python Shell¶
When developing, running or debugging in Python, e.g. Ansible modules
or Fabric tasks, it’s often useful to have a REPL. That’s why the
image includes IPython, ptpython and konch. You can just drop a
.konchrc
python in your source tree, e.g.:
# -*- coding: utf-8 -*-
# vi: set ft=python :
import konch
import fabfile
from fabric import api as fa
konch.config({
'context': {
# fabric
'fa': fa,
'ft': fabfile,
'env': fa.env,
'run': fa.run,
'sudo': fa.sudo,
}
})
and then run:
devops-utils ++dev konch
and you get a Python REPL with syntax highlighting, completion and quick access to some Fabric operations and tasks.
Extending¶
Both the external runner and the init (startup) script can be extended with plugins to support additional options and to modify the environment and arguments of the utilities being run.
The plugins are simple Python files that will be executed in a context
containing mainly the decorators: devops_utils.init.initfunc()
for init plugins, and external_runner.argparse_builder()
and
external_runner.docker_run_builder()
for external runner.
They are used to mark functions to be executed at specific stages in
the startup process.
They should define functions decorated with the above with signatures matching the ones described in API docs for each decorator.
See Modules for details.
Once you have a plugin, in your derived image drop the files into /etc/devops-utils/init_plugins/ or /etc/devops-utils/runner_plugins/ directory for init or runner respectively.