1. docker
  2. Commit 937f52aef98ac61bca75ef25c16b79b5fafa58ff
Browse code

docker in-container process management with CFEngine

Eystein Måløy Stenberg authored on 2013/11/23 09:06:15
Showing 2 changed files
docs/sources/examples/cfengine_process_management.rst
History View file @ 937f52a
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,137 @@
0 
+:title: Process Management with CFEngine
1 
+:description: Managing containerized processes with CFEngine
2 
+:keywords: cfengine, process, management, usage, docker, documentation
3 
+
4 
+Process Management with CFEngine
5 
+================================
6 
+
7 
+Create Docker containers with managed processes.
8 
+
9 
+Docker monitors one process in each running container and the container lives or dies with that process.
10 
+By introducing CFEngine inside Docker containers, we can alleviate a few of the issues that may arise:
11 
+
12 
+* It is possible to easily start multiple processes within a container, all of which will be managed automatically, with the normal ``docker run`` command.
13 
+* If a managed process dies or crashes, CFEngine will start it again within 1 minute.
14 
+* 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.
15 
+
16 
+
17 
+How it works
18 
+------------
19 
+
20 
+CFEngine, together with the cfe-docker integration policies, are installed as part of the Dockerfile. This builds CFEngine into our Docker image.
21 
+
22 
+The Dockerfile's ``ENTRYPOINT`` takes an arbitrary amount of commands (with any desired arguments) as parameters.
23 
+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.
24 
+
25 
+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.
26 
+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.
27 
+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.
28 
+The check on the process table happens every minute.
29 
+
30 
+Note that it is therefore important that the command to start your application leaves a process with the basename of the command.
31 
+This can be made more flexible by making some minor adjustments to the CFEngine policies, if desired.
32 
+
33 
+
34 
+Usage
35 
+-----
36 
+
37 
+This example assumes you have Docker installed and working.
38 
+We will install and manage ``apache2`` and ``sshd`` in a single container.
39 
+
40 
+There are three steps:
41 
+
42 
+1. Install CFEngine into the container.
43 
+2. Copy the CFEngine Docker process management policy into the containerized CFEngine installation.
44 
+3. Start your application processes as part of the ``docker run`` command.
45 
+
46 
+
47 
+Building the container image
48 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
49 
+
50 
+The first two steps can be done as part of a Dockerfile, as follows.
51 
+
52 
+.. code-block:: bash
53 
+
54 
+    FROM ubuntu
55 
+    MAINTAINER Eystein Måløy Stenberg <eytein.stenberg@gmail.com>
56 
+
57 
+    RUN apt-get -y install wget lsb-release unzip
58 
+
59 
+    # install latest CFEngine
60 
+    RUN wget -qO- http://cfengine.com/pub/gpg.key | apt-key add -
61 
+    RUN echo "deb http://cfengine.com/pub/apt $(lsb_release -cs) main" > /etc/apt/sources.list.d/cfengine-community.list
62 
+    RUN apt-get update
63 
+    RUN apt-get install cfengine-community
64 
+
65 
+    # install cfe-docker process management policy
66 
+    RUN wget --no-check-certificate https://github.com/estenberg/cfe-docker/archive/master.zip -P /tmp/ && unzip /tmp/master.zip -d /tmp/
67 
+    RUN cp /tmp/cfe-docker-master/cfengine/bin/* /var/cfengine/bin/
68 
+    RUN cp /tmp/cfe-docker-master/cfengine/inputs/* /var/cfengine/inputs/
69 
+    RUN rm -rf /tmp/cfe-docker-master /tmp/master.zip
70 
+
71 
+    # apache2 and openssh are just for testing purposes, install your own apps here
72 
+    RUN apt-get -y install openssh-server apache2
73 
+    RUN mkdir -p /var/run/sshd
74 
+    RUN echo "root:password" | chpasswd  # need a password for ssh
75 
+
76 
+    ENTRYPOINT ["/var/cfengine/bin/docker_processes_run.sh"]
77 
+
78 
+
79 
+By saving this file as ``Dockerfile`` to a working directory, you can then build your container with the docker build command,
80 
+e.g. ``docker build -t managed_image``.
81 
+
82 
+Testing the container
83 
+~~~~~~~~~~~~~~~~~~~~~
84 
+
85 
+Start the container with ``apache2`` and ``sshd`` running and managed, forwarding a port to our SSH instance:
86 
+
87 
+.. code-block:: bash
88 
+
89 
+    docker run -p 127.0.0.1:222:22 -d managed_image "/usr/sbin/sshd" "/etc/init.d/apache2 start"
90 
+
91 
+We now clearly see one of the benefits of the cfe-docker integration: it allows to start several processes
92 
+as part of a normal ``docker run`` command.
93 
+
94 
+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
95 
+"password" in the Dockerfile above and can use that to log in with ssh:
96 
+
97 
+.. code-block:: bash
98 
+
99 
+    ssh -p222 root@127.0.0.1
100 
+
101 
+    ps -ef
102 
+    UID        PID  PPID  C STIME TTY          TIME CMD
103 
+    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
104 
+    root        18     1  0 07:48 ?        00:00:00 /var/cfengine/bin/cf-execd -F
105 
+    root        20     1  0 07:48 ?        00:00:00 /usr/sbin/sshd
106 
+    root        32     1  0 07:48 ?        00:00:00 /usr/sbin/apache2 -k start
107 
+    www-data    34    32  0 07:48 ?        00:00:00 /usr/sbin/apache2 -k start
108 
+    www-data    35    32  0 07:48 ?        00:00:00 /usr/sbin/apache2 -k start
109 
+    www-data    36    32  0 07:48 ?        00:00:00 /usr/sbin/apache2 -k start
110 
+    root        93    20  0 07:48 ?        00:00:00 sshd: root@pts/0
111 
+    root       105    93  0 07:48 pts/0    00:00:00 -bash
112 
+    root       112   105  0 07:49 pts/0    00:00:00 ps -ef
113 
+
114 
+
115 
+If we stop apache2, it will be started again within a minute by CFEngine.
116 
+
117 
+.. code-block:: bash
118 
+
119 
+    service apache2 status
120 
+     Apache2 is running (pid 32).
121 
+    service apache2 stop
122 
+             * Stopping web server apache2 ... waiting    [ OK ]
123 
+    service apache2 status
124 
+     Apache2 is NOT running.
125 
+    # ... wait up to 1 minute...
126 
+    service apache2 status
127 
+     Apache2 is running (pid 173).
128 
+
129 
+
130 
+Adapting to your applications
131 
+-----------------------------
132 
+
133 
+To make sure your applications get managed in the same manner, there are just two things you need to adjust from the above example:
134 
+
135 
+* In the Dockerfile used above, install your applications instead of ``apache2`` and ``sshd``.
136 
+* When you start the container with ``docker run``, specify the command line arguments to your applications rather than ``apache2`` and ``sshd``.
docs/sources/examples/index.rst
History View file @ 937f52a
... ... 
@@ -25,3 +25,4 @@ to more substantial services like those which you might find in production.
25 25 
    mongodb
26 26 
    running_riak_service
27 27 
    using_supervisord
28 
+   cfengine_process_management