The vagrant-lxc plugin allows LXC to be a (custom) provider for Vagrant. This allows Vagrant boxes to be spun up as LXC containers on the host machine.
Depending on your distro and host OS installation add-ons, it may not be enough to just install the plugin as it relies on additional packages for it to work. In this post, I will go through how to set up the vagrant-lxc plugin for a clean installation of Ubuntu Server.
- Host OS: Ubuntu Server 18.04.3
- LXC Client/Server Version: 3.0.3
- Vagrant Version: 2.2.7 (latest version at time of this post)
- Vagrant Box: debian/jessie64 version 8.7.0 (or any supported box for the LXC provider at https://app.vagrantup.com/boxes/search?provider=lxc)
Step 1: Install Required Packages
Starting from a clean installation of the host OS, install the following packages:
$ sudo apt-get install lxc-utils lxc-templates
The Ubuntu Server 18.04.3 distro should already come with LXC installed. If the distro you are using does not have it, install it as well.
Quick explanation on why these packages are needed:
- lxc-utils – This package provides the lxc-* tools that the vagrant-lxc plugin uses (e.g. lxc-create)
- lxc-templates – This package contains the necessary shell scripts to configure and create the LXC container. The templates can be found at
Step 2: Initialize LXD
We need to setup LXD (the defaults should be okay for purposes of testing):
$ lxd init (press enter for all prompts to accept defaults)
Step 3: Install Vagrant
The Vagrant Installation guide recommends installing directly from the website instead of the distribution package manager, as “typically these packages are missing dependencies or include very outdated versions of Vagrant”.
So let’s get the
.deb file from their download page and install with with
$ wget (the respective release package for your OS and architecture) $ sudo dpkg -i (the downloaded .deb file) $ vagrant version Installed Version: 2.2.7 Latest Version: 2.2.7 You're running an up-to-date version of Vagrant!
Step 4: Add the vagrant-lxc Plugin
We need this plugin to allow Vagrant to communicate with LXC as a provider. Otherwise, the default supported providers are only hyperv, docker, and virtualbox.
$ vagrant plugin install vagrant-lxc Installing the 'vagrant-lxc' plugin. This can take a few minutes... Fetching: vagrant-lxc-1.4.3.gem (100%) Installed the plugin 'vagrant-lxc (1.4.3)'!
Step 5: Create Vagrantfile
Navigate to your (presumably clean) project directory and create your Vagrantfile. I like to create a minimal (
-m flag) Vagrantfile without the comments for simplicity:
$ cd (your-project-directory) $ vagrant init -m debian/jessie64 --box-version 8.7.0 A `Vagrantfile` has been placed in this directory. You are now ready to `vagrant up` your first virtual environment! Please read the comments in the Vagrantfile as well as documentation on `vagrantup.com` for more information on using Vagrant.
Step 6: Vagrant Up
Its time to spin up a LXC container of our box! If its your first time using this box, vagrant will need to spend some time downloading it. Below are some important stdout lines that you would expect to see:
$ vagrant up --provider=lxc Bringing machine 'default' up with 'lxc' provider... ==> default: Box 'debian/jessie64' could not be found. Attempting to find and install... ==> default: Loading metadata for box 'debian/jessie64' ==> default: Adding box 'debian/jessie64' (v8.7.0) for provider: lxc ==> default: Successfully added box 'debian/jessie64' (v8.7.0) for 'lxc'! ==> default: Importing base box 'debian/jessie64'... ==> default: Checking if box 'debian/jessie64' version '8.7.0' is up to date... ==> default: Setting up mount entries for shared folders... ==> default: Starting container... ==> default: Waiting for machine to boot. This may take a few minutes... default: SSH address: 10.0.3.69:22 default: SSH username: vagrant default: SSH auth method: private key default: default: Vagrant insecure key detected. Vagrant will automatically replace default: this with a newly generated keypair for better security. default: default: Inserting generated public key within guest... default: Removing insecure key from the guest if it's present... default: Key inserted! Disconnecting and reconnecting using new SSH key... ==> default: Machine booted and ready!
If there are issues with starting up the container, run
vagrant up --provider=lxc --debug to see more verbose information about the error.
vagrant up was successful with:
$ vagrant status Current machine states: default running (lxc) <-- shows that the LXC ... $ vagrant ssh ... vagrant@jessie:~$ <-- this is the vagrant user in the LXC container
Step 7: Vagrant Halt
Due to this issue, halting a Debian (and its derivatives) container freezes indefinitely. According to the issue discussion, other guest containers work fine. So specifically for this Debian container, use the
-f flag to force it:
$ vagrant halt -f ==> default: Forcing shutdown of container...
And we are done!
- It is important to choose a box and version combination that supports the provider you want. For example, the debian/jessie64 vagrant box page shows that only versions 8.7.0 and 8.6.1 are supported by LXC. Choosing an unsupported version will give you an error message similar to the following:
The box you're attempting to add has no available version that matches the constraints you requested. Please double-check your settings. Also verify that if you specified version constraints, that the provider you wish to use is available for these constraints. Box: debian/jessie64 Address: https://vagrantcloud.com/debian/jessie64 Constraints: 8.8.0 Available versions: (insert list of supported versions)