1. devstack
  2. Commit baa35d06e106a74365051bf26c56faf92ec92f88
Browse code

Add guide on running devstack in lxc container

Running OpenStack in a container can be a useful workflow for developers.
The primary benefits are faster performance and lower memory overhead
while still providing a suitable level of isolation.

The guide walks the user through procedure for configuring an LXC container
and deploying OpenStack in it using devstack. It also discusses the limitations
of this setup - particularly related to cinder.

Change-Id: I2e0921fd118cfe98cef86ba110a94b3edccf9a29

Cody A.W. Somerville authored on 2016/02/11 15:23:14
Showing 2 changed files
doc/source/guides/lxc.rst
History View file @ baa35d0
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,164 @@
0 
+================================
1 
+All-In-One Single LXC Container
2 
+================================
3 
+
4 
+This guide walks you through the process of deploying OpenStack using devstack
5 
+in an LXC container instead of a VM.
6 
+
7 
+The primary benefits to running devstack inside a container instead of a VM is
8 
+faster performance and lower memory overhead while still providing a suitable
9 
+level of isolation. This can be particularly useful when you want to simulate
10 
+running OpenStack on multiple nodes.
11 
+
12 
+.. Warning:: Containers do not provide the same level of isolation as a virtual
13 
+   machine.
14 
+
15 
+.. Note:: Not all OpenStack features support running inside of a container. See
16 
+   `Limitations`_ section below for details. :doc:`OpenStack in a VM <single-vm>`
17 
+   is recommended for beginners.
18 
+
19 
+Prerequisites
20 
+==============
21 
+
22 
+This guide is written for Ubuntu 14.04 but should be adaptable for any modern
23 
+Linux distribution.
24 
+
25 
+Install the LXC package::
26 
+
27 
+   sudo apt-get install lxc
28 
+
29 
+You can verify support for containerization features in your currently running
30 
+kernel using the ``lxc-checkconfig`` command.
31 
+
32 
+Container Setup
33 
+===============
34 
+
35 
+Configuration
36 
+---------------
37 
+
38 
+For a successful run of ``stack.sh`` and to permit use of KVM to run the VMs you
39 
+launch inside your container, we need to use the following additional
40 
+configuration options. Place the following in a file called
41 
+``devstack-lxc.conf``::
42 
+
43 
+  # Permit access to /dev/loop*
44 
+  lxc.cgroup.devices.allow = b 7:* rwm
45 
+
46 
+  # Setup access to /dev/net/tun and /dev/kvm
47 
+  lxc.mount.entry = /dev/net/tun dev/net/tun none bind,create=file 0 0
48 
+  lxc.mount.entry = /dev/kvm dev/kvm none bind,create=file 0 0
49 
+
50 
+  # Networking
51 
+  lxc.network.type = veth
52 
+  lxc.network.flags = up
53 
+  lxc.network.link = lxcbr0
54 
+
55 
+
56 
+Create Container
57 
+-------------------
58 
+
59 
+The configuration and rootfs for LXC containers are created using the
60 
+``lxc-create`` command.
61 
+
62 
+We will name our container ``devstack`` and use the ``ubuntu`` template which
63 
+will use ``debootstrap`` to build a Ubuntu rootfs. It will default to the same
64 
+release and architecture as the host system. We also install the additional
65 
+packages ``bsdmainutils`` and ``git`` as we'll need them to run devstack::
66 
+
67 
+  sudo lxc-create -n devstack -t ubuntu -f devstack-lxc.conf -- --packages=bsdmainutils,git
68 
+
69 
+The first time it builds the rootfs will take a few minutes to download, unpack,
70 
+and configure all the necessary packages for a minimal installation of Ubuntu.
71 
+LXC will cache this and subsequent containers will only take seconds to create.
72 
+
73 
+.. Note:: To speed up the initial rootfs creation, you can specify a mirror to
74 
+   download the Ubuntu packages from by appending ``--mirror=`` and then the URL
75 
+   of a Ubuntu mirror. To see other other template options, you can run
76 
+   ``lxc-create -t ubuntu -h``.
77 
+
78 
+Start Container
79 
+----------------
80 
+
81 
+To start the container, run::
82 
+
83 
+  sudo lxc-start -n devstack
84 
+
85 
+A moment later you should be presented with the login prompt for your container.
86 
+You can login using the username ``ubuntu`` and password ``ubuntu``.
87 
+
88 
+You can also ssh into your container. On your host, run
89 
+``sudo lxc-info -n devstack`` to get the IP address (e.g.
90 
+``ssh ubuntu@$(sudo lxc-info -n p2 | awk '/IP/ { print $2 }')``).
91 
+
92 
+Run Devstack
93 
+-------------
94 
+
95 
+You should now be logged into your container and almost ready to run devstack.
96 
+The commands in this section should all be run inside your container.
97 
+
98 
+.. Tip:: You can greatly reduce the runtime of your initial devstack setup by
99 
+   ensuring you have your apt sources.list configured to use a fast mirror.
100 
+   Check and update ``/etc/apt/sources.list`` if necessary and then run
101 
+   ``apt-get update``.
102 
+
103 
+#. Download DevStack
104 
+
105 
+   ::
106 
+
107 
+       git clone https://git.openstack.org/openstack-dev/devstack
108 
+
109 
+#. Configure
110 
+
111 
+   Refer to :ref:`minimal-configuration` if you wish to configure the behaviour
112 
+   of devstack.
113 
+
114 
+#. Start the install
115 
+
116 
+   ::
117 
+
118 
+       cd devstack
119 
+       ./stack.sh
120 
+
121 
+Cleanup
122 
+-------
123 
+
124 
+To stop the container::
125 
+
126 
+  lxc-stop -n devstack
127 
+
128 
+To delete the container::
129 
+
130 
+  lxc-destroy -n devstack
131 
+
132 
+Limitations
133 
+============
134 
+
135 
+Not all OpenStack features may function correctly or at all when ran from within
136 
+a container.
137 
+
138 
+Cinder
139 
+-------
140 
+
141 
+Unable to create LVM backed volume
142 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
143 
+
144 
+  In our configuration, we have not whitelisted access to device-mapper or LVM
145 
+  devices. Doing so will permit your container to have access and control of LVM
146 
+  on the host system. To enable, add the following to your
147 
+  ``devstack-lxc.conf`` before running ``lxc-create``::
148 
+
149 
+    lxc.cgroup.devices.allow = c 10:236 rwm
150 
+    lxc.cgroup.devices.allow = b 252:* rwm
151 
+
152 
+  Additionally you'll need to set ``udev_rules = 0`` in the ``activation``
153 
+  section of ``/etc/lvm/lvm.conf`` unless you mount devtmpfs in your container.
154 
+
155 
+Unable to attach volume to instance
156 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
157 
+
158 
+  It is not possible to attach cinder volumes to nova instances due to parts of
159 
+  the Linux iSCSI implementation not being network namespace aware. This can be
160 
+  worked around by using network pass-through instead of a separate network
161 
+  namespace but such a setup significantly reduces the isolation of the
162 
+  container (e.g. a ``halt`` command issued in the container will cause the host
163 
+  system to shutdown).
doc/source/index.rst
History View file @ baa35d0
... ... 
@@ -76,6 +76,7 @@ Walk through various setups used by stackers
76 76
77 77 
    guides/single-vm
78 78 
    guides/single-machine
79 
+   guides/lxc
79 80 
    guides/multinode-lab
80 81 
    guides/neutron
81 82 
    guides/devstack-with-nested-kvm
... ... 
@@ -96,6 +97,13 @@ Run :doc:`OpenStack on dedicated hardware <guides/single-machine>`  This can inc
96 96 
 server-class machine or a laptop at home.
97 97 
 :doc:`[Read] <guides/single-machine>`
98 98
99 
+All-In-One LXC Container
100 
+-------------------------
101 
+
102 
+Run :doc:`OpenStack in a LXC container <guides/lxc>`. Beneficial for intermediate
103 
+and advanced users. The VMs launched in this cloud will be fully accelerated but
104 
+not all OpenStack features are supported. :doc:`[Read] <guides/lxc>`
105 
+
99 106 
 Multi-Node Lab
100 107 
 --------------
101 108