diff --git a/doc/source/guides/lxc.rst b/doc/source/guides/lxc.rst new file mode 100644 index 0000000000..a719d605aa --- /dev/null +++ b/doc/source/guides/lxc.rst @@ -0,0 +1,164 @@ +================================ +All-In-One Single LXC Container +================================ + +This guide walks you through the process of deploying OpenStack using devstack +in an LXC container instead of a VM. + +The primary benefits to running devstack inside a container instead of a VM is +faster performance and lower memory overhead while still providing a suitable +level of isolation. This can be particularly useful when you want to simulate +running OpenStack on multiple nodes. + +.. Warning:: Containers do not provide the same level of isolation as a virtual + machine. + +.. Note:: Not all OpenStack features support running inside of a container. See + `Limitations`_ section below for details. :doc:`OpenStack in a VM ` + is recommended for beginners. + +Prerequisites +============== + +This guide is written for Ubuntu 14.04 but should be adaptable for any modern +Linux distribution. + +Install the LXC package:: + + sudo apt-get install lxc + +You can verify support for containerization features in your currently running +kernel using the ``lxc-checkconfig`` command. + +Container Setup +=============== + +Configuration +--------------- + +For a successful run of ``stack.sh`` and to permit use of KVM to run the VMs you +launch inside your container, we need to use the following additional +configuration options. Place the following in a file called +``devstack-lxc.conf``:: + + # Permit access to /dev/loop* + lxc.cgroup.devices.allow = b 7:* rwm + + # Setup access to /dev/net/tun and /dev/kvm + lxc.mount.entry = /dev/net/tun dev/net/tun none bind,create=file 0 0 + lxc.mount.entry = /dev/kvm dev/kvm none bind,create=file 0 0 + + # Networking + lxc.network.type = veth + lxc.network.flags = up + lxc.network.link = lxcbr0 + + +Create Container +------------------- + +The configuration and rootfs for LXC containers are created using the +``lxc-create`` command. + +We will name our container ``devstack`` and use the ``ubuntu`` template which +will use ``debootstrap`` to build a Ubuntu rootfs. It will default to the same +release and architecture as the host system. We also install the additional +packages ``bsdmainutils`` and ``git`` as we'll need them to run devstack:: + + sudo lxc-create -n devstack -t ubuntu -f devstack-lxc.conf -- --packages=bsdmainutils,git + +The first time it builds the rootfs will take a few minutes to download, unpack, +and configure all the necessary packages for a minimal installation of Ubuntu. +LXC will cache this and subsequent containers will only take seconds to create. + +.. Note:: To speed up the initial rootfs creation, you can specify a mirror to + download the Ubuntu packages from by appending ``--mirror=`` and then the URL + of a Ubuntu mirror. To see other other template options, you can run + ``lxc-create -t ubuntu -h``. + +Start Container +---------------- + +To start the container, run:: + + sudo lxc-start -n devstack + +A moment later you should be presented with the login prompt for your container. +You can login using the username ``ubuntu`` and password ``ubuntu``. + +You can also ssh into your container. On your host, run +``sudo lxc-info -n devstack`` to get the IP address (e.g. +``ssh ubuntu@$(sudo lxc-info -n p2 | awk '/IP/ { print $2 }')``). + +Run Devstack +------------- + +You should now be logged into your container and almost ready to run devstack. +The commands in this section should all be run inside your container. + +.. Tip:: You can greatly reduce the runtime of your initial devstack setup by + ensuring you have your apt sources.list configured to use a fast mirror. + Check and update ``/etc/apt/sources.list`` if necessary and then run + ``apt-get update``. + +#. Download DevStack + + :: + + git clone https://git.openstack.org/openstack-dev/devstack + +#. Configure + + Refer to :ref:`minimal-configuration` if you wish to configure the behaviour + of devstack. + +#. Start the install + + :: + + cd devstack + ./stack.sh + +Cleanup +------- + +To stop the container:: + + lxc-stop -n devstack + +To delete the container:: + + lxc-destroy -n devstack + +Limitations +============ + +Not all OpenStack features may function correctly or at all when ran from within +a container. + +Cinder +------- + +Unable to create LVM backed volume +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + In our configuration, we have not whitelisted access to device-mapper or LVM + devices. Doing so will permit your container to have access and control of LVM + on the host system. To enable, add the following to your + ``devstack-lxc.conf`` before running ``lxc-create``:: + + lxc.cgroup.devices.allow = c 10:236 rwm + lxc.cgroup.devices.allow = b 252:* rwm + + Additionally you'll need to set ``udev_rules = 0`` in the ``activation`` + section of ``/etc/lvm/lvm.conf`` unless you mount devtmpfs in your container. + +Unable to attach volume to instance +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + It is not possible to attach cinder volumes to nova instances due to parts of + the Linux iSCSI implementation not being network namespace aware. This can be + worked around by using network pass-through instead of a separate network + namespace but such a setup significantly reduces the isolation of the + container (e.g. a ``halt`` command issued in the container will cause the host + system to shutdown). diff --git a/doc/source/index.rst b/doc/source/index.rst index 4a1d93d817..3e324adefc 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -76,6 +76,7 @@ Walk through various setups used by stackers guides/single-vm guides/single-machine + guides/lxc guides/multinode-lab guides/neutron guides/devstack-with-nested-kvm @@ -96,6 +97,13 @@ Run :doc:`OpenStack on dedicated hardware ` This can inc server-class machine or a laptop at home. :doc:`[Read] ` +All-In-One LXC Container +------------------------- + +Run :doc:`OpenStack in a LXC container `. Beneficial for intermediate +and advanced users. The VMs launched in this cloud will be fully accelerated but +not all OpenStack features are supported. :doc:`[Read] ` + Multi-Node Lab --------------