From 937f52aef98ac61bca75ef25c16b79b5fafa58ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eystein=20M=C3=A5l=C3=B8y=20Stenberg?= Date: Fri, 22 Nov 2013 16:06:15 -0800 Subject: [PATCH] docker in-container process management with CFEngine --- .../examples/cfengine_process_management.rst | 137 ++++++++++++++++++ docs/sources/examples/index.rst | 1 + 2 files changed, 138 insertions(+) create mode 100644 docs/sources/examples/cfengine_process_management.rst diff --git a/docs/sources/examples/cfengine_process_management.rst b/docs/sources/examples/cfengine_process_management.rst new file mode 100644 index 0000000000..9d7681f556 --- /dev/null +++ b/docs/sources/examples/cfengine_process_management.rst @@ -0,0 +1,137 @@ +:title: Process Management with CFEngine +:description: Managing containerized processes with CFEngine +:keywords: cfengine, process, management, usage, docker, documentation + +Process Management with CFEngine +================================ + +Create Docker containers with managed processes. + +Docker monitors one process in each running container and the container lives or dies with that process. +By introducing CFEngine inside Docker containers, we can alleviate a few of the issues that may arise: + +* It is possible to easily start multiple processes within a container, all of which will be managed automatically, with the normal ``docker run`` command. +* If a managed process dies or crashes, CFEngine will start it again within 1 minute. +* The container itself will live as long as the CFEngine scheduling daemon (cf-execd) lives. With CFEngine, we are able to decouple the life of the container from the uptime of the service it provides. + + +How it works +------------ + +CFEngine, together with the cfe-docker integration policies, are installed as part of the Dockerfile. This builds CFEngine into our Docker image. + +The Dockerfile's ``ENTRYPOINT`` takes an arbitrary amount of commands (with any desired arguments) as parameters. +When we run the Docker container these parameters get written to CFEngine policies and CFEngine takes over to ensure that the desired processes are running in the container. + +CFEngine scans the process table for the ``basename`` of the commands given to the ``ENTRYPOINT`` and runs the command to start the process if the ``basename`` is not found. +For example, if we start the container with ``docker run "/path/to/my/application parameters"``, CFEngine will look for a process named ``application`` and run the command. +If an entry for ``application`` is not found in the process table at any point in time, CFEngine will execute ``/path/to/my/application parameters`` to start the application once again. +The check on the process table happens every minute. + +Note that it is therefore important that the command to start your application leaves a process with the basename of the command. +This can be made more flexible by making some minor adjustments to the CFEngine policies, if desired. + + +Usage +----- + +This example assumes you have Docker installed and working. +We will install and manage ``apache2`` and ``sshd`` in a single container. + +There are three steps: + +1. Install CFEngine into the container. +2. Copy the CFEngine Docker process management policy into the containerized CFEngine installation. +3. Start your application processes as part of the ``docker run`` command. + + +Building the container image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first two steps can be done as part of a Dockerfile, as follows. + +.. code-block:: bash + + FROM ubuntu + MAINTAINER Eystein Måløy Stenberg + + RUN apt-get -y install wget lsb-release unzip + + # install latest CFEngine + RUN wget -qO- http://cfengine.com/pub/gpg.key | apt-key add - + RUN echo "deb http://cfengine.com/pub/apt $(lsb_release -cs) main" > /etc/apt/sources.list.d/cfengine-community.list + RUN apt-get update + RUN apt-get install cfengine-community + + # install cfe-docker process management policy + RUN wget --no-check-certificate https://github.com/estenberg/cfe-docker/archive/master.zip -P /tmp/ && unzip /tmp/master.zip -d /tmp/ + RUN cp /tmp/cfe-docker-master/cfengine/bin/* /var/cfengine/bin/ + RUN cp /tmp/cfe-docker-master/cfengine/inputs/* /var/cfengine/inputs/ + RUN rm -rf /tmp/cfe-docker-master /tmp/master.zip + + # apache2 and openssh are just for testing purposes, install your own apps here + RUN apt-get -y install openssh-server apache2 + RUN mkdir -p /var/run/sshd + RUN echo "root:password" | chpasswd # need a password for ssh + + ENTRYPOINT ["/var/cfengine/bin/docker_processes_run.sh"] + + +By saving this file as ``Dockerfile`` to a working directory, you can then build your container with the docker build command, +e.g. ``docker build -t managed_image``. + +Testing the container +~~~~~~~~~~~~~~~~~~~~~ + +Start the container with ``apache2`` and ``sshd`` running and managed, forwarding a port to our SSH instance: + +.. code-block:: bash + + docker run -p 127.0.0.1:222:22 -d managed_image "/usr/sbin/sshd" "/etc/init.d/apache2 start" + +We now clearly see one of the benefits of the cfe-docker integration: it allows to start several processes +as part of a normal ``docker run`` command. + +We can now log in to our new container and see that both ``apache2`` and ``sshd`` are running. We have set the root password to +"password" in the Dockerfile above and can use that to log in with ssh: + +.. code-block:: bash + + ssh -p222 root@127.0.0.1 + + ps -ef + UID PID PPID C STIME TTY TIME CMD + root 1 0 0 07:48 ? 00:00:00 /bin/bash /var/cfengine/bin/docker_processes_run.sh /usr/sbin/sshd /etc/init.d/apache2 start + root 18 1 0 07:48 ? 00:00:00 /var/cfengine/bin/cf-execd -F + root 20 1 0 07:48 ? 00:00:00 /usr/sbin/sshd + root 32 1 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start + www-data 34 32 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start + www-data 35 32 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start + www-data 36 32 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start + root 93 20 0 07:48 ? 00:00:00 sshd: root@pts/0 + root 105 93 0 07:48 pts/0 00:00:00 -bash + root 112 105 0 07:49 pts/0 00:00:00 ps -ef + + +If we stop apache2, it will be started again within a minute by CFEngine. + +.. code-block:: bash + + service apache2 status + Apache2 is running (pid 32). + service apache2 stop + * Stopping web server apache2 ... waiting [ OK ] + service apache2 status + Apache2 is NOT running. + # ... wait up to 1 minute... + service apache2 status + Apache2 is running (pid 173). + + +Adapting to your applications +----------------------------- + +To make sure your applications get managed in the same manner, there are just two things you need to adjust from the above example: + +* In the Dockerfile used above, install your applications instead of ``apache2`` and ``sshd``. +* When you start the container with ``docker run``, specify the command line arguments to your applications rather than ``apache2`` and ``sshd``. diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index 9b993f3768..cd08107e7a 100644 --- a/docs/sources/examples/index.rst +++ b/docs/sources/examples/index.rst @@ -25,3 +25,4 @@ to more substantial services like those which you might find in production. mongodb running_riak_service using_supervisord + cfengine_process_management