1. devstack
  2. Commit 886410eadeaf5366e51bd31677a3b49b34eb391c
Browse code

Merge "Add guide on running devstack in lxc container"

Jenkins authored on 2016/02/18 00:10:00
Showing 2 changed files
doc/source/guides/lxc.rst
History View file @ 886410e
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 @ 886410e
... ... 
@@ -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