Skip to content

Latest commit

 

History

History
510 lines (350 loc) · 16.6 KB

vagrant.mkd

File metadata and controls

510 lines (350 loc) · 16.6 KB

Vagrant eases a VM instanciation followed by OBM installation. The idea behind it is to create a VM then install OBM on it using obm-deploy. Vagrant will do all that automatically for you.

Table of contents


Vagrant documentation [▲](#top-page "back to top") =====================

Official documentation

Vagrant official documentation is a good place to start.


Installation [▲](#top-page "back to top") ============

This installation is played on the machine from which the user deploys the VM.

Installation on Debian based distros

A Debian package is available from the Vagrant website :

$ wget https://dl.bintray.com/mitchellh/vagrant/vagrant_1.6.5_x86_64.deb
$ sudo dpkg -i vagrant_1.6.5_x86_64.deb

Installation on CentOS based distros

A CentOS package is available from the Vagrant website :

$ wget https://dl.bintray.com/mitchellh/vagrant/vagrant_1.6.5_x86_64.rpm
$ sudo rpm -ivh vagrant_1.6.5_x86_64.rpm


Boxes [▲](#top-page "back to top") =====

We provide some boxes to use with obm-deploy. You can download them from download.obm.org. For example :

$ wget http://download.obm.org/vagrant-centos-66-virtualbox.box

Once you have downloaded your image, you need to add it to your local vagrant repository :

$ vagrant box add vagrant-centos-66-virtualbox.box --name centos66


First deployment (Virtualbox) [▲](#top-page "back to top") =============================

Pre-requisites

Declare your hosts in /etc/hosts

Target VMs need to be declared in /etc/hosts. Example :

192.168.56.201 obm.example.com

Put your SSH key in the dedicated directory

Your must place your SSH key in vagrant/pubkeys directory to make bootstrap.sh deploy it on your future VM. Otherwise obm-deploy will not be able to connect to your VM as root. All the public keys you put on this folder need to end with a .pub extension to be deployed on your VM

Activate your obm-deploy virtualenv

Your obm-deploy virtualenv must be activated in order to provision your VM after its creation. How to do it depends on the method you use to install obm-deploy. Here is the command to activate your virtualenv using virtualenvwrapper :

$ workon obm-deploy-env

Vagrantfile

Here is a simple example Vagrantfile wich allows you to deploy a single VM using the obmfull-example inventory and the box you downloaded at the previous step.

The IP address is configured to match Virtualbox default configuration. You can change it but it must always match your virtualbox networking configuration. By default, Host-Only networking will be used but it can be customized (please refer to Vagrant documentation).

As you can see, your VM will be provisionned first by a shell script then by Ansible/obm-deploy. The shell script will configure SSH and place your SSH key in the root account's authorized_keys file.

Vagrant.configure("2") do |config|

  ## VM definition
  config.vm.define "obm.example.com" do |centos66|
    centos66.vm.box = "centos66"
    centos66.vm.hostname = "obm.example.com"
    centos66.vm.network :private_network,
                        :ip => "192.168.56.201"

    ## Shell script provisionning
    centos66.vm.provision "shell" do |shell|
      shell.path = "vagrant/bootstrap.sh"
    end

    ## Ansible/obm-deploy provisionning
    centos66.vm.provision :ansible do |ansible|
      ansible.inventory_path = "obmfull-example"
      ansible.playbook = "obm.yml"
      ansible.extra_vars = { ansible_ssh_user: 'root' }
      # Disable default limit (required with Vagrant 1.5+)
      ansible.limit = 'all'
    end

  end

  ## synced folder configuration 
  config.vm.synced_folder "vagrant", "/vagrant", type: "rsync"

end

Running Vagrant

To deploy your VM, the only thing you need to do is to run the up command as below :

$ vagrant up

Connect to your VM

To connect to your VM, run the following command :

$ vagrant ssh


Vagrant-libvirt [▲](#top-page "back to top") ===============

Using the vagrant-libvirt plugin, you can easily deploy kvm VMs to any remote hypervisor running the libvirt daemon.

Documentation

The Vagrant-libvirt documentation can be found on pradel's vagrant-libvirt github page.

Pre-requisites for Debian based distributions

$ sudo apt-get install build-essential libvirt-dev

Pre-requisites for CentOS based distributions

$ sudo yum groupinstall "Development Tools"
$ sudo yum install libvirt-devel libxslt-devel libxml2-devel

Installation

Install the plugin:

$ vagrant plugin install vagrant-libvirt

Boxes

$ wget http://download.obm.org/vagrant-centos-66-libvirt.box
$ vagrant box add vagrant-centos-66-libvirt.box --name centos66

Networking

Networking with vagrant-libvirt is composed of two elements.

Management network

The first interface of the VM is always bound to a management network. This network must have been created beforehand and DHCP must be enabled. You probably want to make this network private but it's not mandatory. Vagrant-libvirt will use dnsmasq to retrieve the IP addresses of the VM when you run vagrant ssh.

By default, the name of the vagrant-libvirt management network is vagrant-libvirt. You should be able to rename it but we can't recommend it, because it is not supported.

The management network can be configured globally for all VMs in your Vagrantfile.

User network(s)

In addition to this network, you need to specify user network(s), especially if you want to access your servcies from the outside.

In Vagrant, there are two types of user networks, private and public. Private networks are shared only between the hypervisor and the VMs. Public networks are used to make VMs reachable from the outside.

On user networks, you can statically set IP adresses or use DHCP.

For more details about networking, please refer to the following links :

Network features in vagrant-libvirt makes use of macvtap driver which is only present in kernel >= 2.6.24

Vagrantfile (simple example)

Here is an example Vagrantfile you can use with the twohosts-example inventory file. This Vagrantfile can easily replace the virtualbox example above if you have kvm and libvirt installed on your local host. Note that you'll need to customize network configuration and hypervisor configuration. I'll give more details about this point on next chapter.

Notice the parameters given to the bootstrap.sh script. They are used to change the default gateway and set it to the user network

Vagrant.configure("2") do |config|

  ## VM definition
  config.vm.define "obm.example.com" do |centos66|
    centos66.vm.box = "centos66"
    centos66.vm.hostname = "obm.example.com"
    centos66.vm.network :private_network,
                        :libvirt__network_name => "default",
                        :ip => "192.168.122.201",
                        :libvirt__netmask => "255.255.255.0",
                        :libvirt__forward_mode => "nat"
    ## Shell provisionning
    centos66.vm.provision "shell" do |shell|
      shell.path = "vagrant/bootstrap.sh"
      shell.args = "10.75.250.129 eth1"
    end
    ## Ansible/obm-deploy provisionning
    centos66.vm.provision :ansible do |ansible|
      ansible.inventory_path = "obmfull-example"
      ansible.playbook = "obm.yml"
      ansible.extra_vars = { ansible_ssh_user: 'root' }
      # Disable default limit (required with Vagrant 1.5+)
      ansible.limit = 'all'
    end
  end

  ## Libvirt provider global configuration
  config.vm.provider :libvirt do |libvirt|
    libvirt.driver = "kvm"
    libvirt.memory = 2048
    libvirt.graphics_type = "spice"
    libvirt.connect_via_ssh = false
    libvirt.management_network_name = "vagrant-libvirt"
    libvirt.management_network_address = "10.2.0.0/24"
  end

  ## synced folder configuration
  config.vm.synced_folder "vagrant", "/vagrant", type: "rsync"

end

Vagrantfile (advanced example)

In this more advanced example, we choose to route hypervisor's private network because it is located on a LAN network. We split a C class network into two subnets of 126 addresses, respectively for management and user networks.

On an internet hosting, you'll probably prefer to use bridged networking using your fallback IP address for user network.

Vagrant.configure("2") do |config|

  ## First VM definition
  config.vm.define "obm1.example.com" do |centos661|
    centos661.vm.box = "centos66"
    centos661.vm.hostname = "obm1.example.com"
    centos661.vm.network :private_network,
                         :libvirt__network_name => "default",
                         :ip => "10.75.250.131",
                         :libvirt__netmask => "255.255.255.128",
                         :libvirt__forward_mode => "route"
    ## Shell provisionning
    centos661.vm.provision "shell" do |shell|
      shell.path = "vagrant/bootstrap.sh"
      shell.args = "10.75.250.129 eth1"
    end
  end

  ## Second VM definition
  config.vm.define "obm0.example.com" do |centos662|
    centos662.vm.box = "centos66"
    centos662.vm.hostname = "obm0.example.com"
    centos662.vm.network :private_network,
                         :libvirt__network_name => "default",
                         :ip => "10.75.250.130",
                         :libvirt__netmask => "255.255.255.128",
                         :libvirt__forward_mode => "route"
    ## Shell provisionning
    centos662.vm.provision "shell" do |shell|
      shell.path = "vagrant/bootstrap.sh"
      shell.args = "10.75.250.129 eth1"
    end
    ## Ansible/obm-deploy provisionning
    centos662.vm.provision :ansible do |ansible|
      ansible.inventory_path = "twohosts-example"
      ansible.playbook = "obm.yml"
      ansible.extra_vars = { ansible_ssh_user: 'root' }
      # Disable default limit (required with Vagrant 1.5+)
      ansible.limit = 'all'
    end
  end


  ## Libvirt provider global configuration
  config.vm.provider :libvirt do |libvirt|
    libvirt.driver = "kvm"
    libvirt.memory = 2048
    libvirt.graphics_type = "spice"
    libvirt.host = "yourhypervisor.yourdomain"
    libvirt.connect_via_ssh = true
    libvirt.username = "linagora"
    libvirt.id_ssh_key_file = "id_dsa"
    libvirt.management_network_name = "vagrant-libvirt"
    libvirt.management_network_address = "10.75.250.0/25"
  end

  ## synced folder configuration 
  config.vm.synced_folder "vagrant", "/vagrant", type: "rsync"

end

Libvirt hypervisor configuration

Hypervisor configuration can be set globally like in the above example but you can also set it on a per VM basis.

The most important part of this configuration the part which is about SSH connection :

  • host : hostname of you hypervisor
  • connect_via_ssh : set it to false if your hypervisor is your localhost
  • username : username used to connect to your hypervisor via SSH (comment it for localhost)
  • id_ssh_key_file : name of your private key (relative to ~/.ssh firectory) (comment it for localhost)

Some other options related to your hypervisor can be usefull :

  • memory : amount of memory to allocate to your VMs
  • driver : libvirt driver to use (kvm or qemu are supported)
  • graphics_type : protocol to use to expose guest display (vnc by default)

For the exhaustive list of available parameters, please refer to pradel's vagrant-libvirt github page.

Provisioning

As you have seen in Vagrantfile, Ansible/obm-deploy provisioning is only activated for the last VM. This is done to take advantage of Ansible's parallelism capabilities.

This way, Vagrant will create VMs simultaneously, then Ansible will provision them in parallel.

To disable this, you can append the --no-parallel option to vagrant's command line.

Deployment

To trigger a deployement, start the same command as above but explicitly define the corresponding provider :

$ vagrant up --provider=libvirt

You can make it the default by setting the VAGRANT_DEFAULT_PROVIDER environment variable, for example, in you .bashrc file :

$ export VAGRANT_DEFAULT_PROVIDER=libvirt


Other plugins [▲](#top-page "back to top") =============

There are several other plugins you can use with Vagrant. I'll try to quickly present you some of the most useful.

Install them using following command if you need them :

$ vagrant plugin install `plugin_name`

Vagrant-mutate

Vagrant boxes are provider dependant. Vagrant mutate is very useful to convert them from one provider to another.

For example, to convert a Virtualbox box named centos66 into libvirt's one, please use the following command :

$ vagrant mutate centos66 libvirt

More info on sciurus's vagrant-mutate github page

Sahara

Sahara is another useful plugin wich allows you to work with your VMs in a sandboxed environment.

To enable the sandbox environment :

$ vagrant sandbox on

To permanently apply your changes :

$ vagrant sandbox commit

Otherwise, to revert them :

$ vagrant sandbox rollback

Then, to exit sandbox mode :

$ vagrant sandbox off

Pretty good, no ?

More info on jedi4ever's vagrant-mutate github page

Vagrant-lxc

With vagrant-lxc, you can deploy VMs to your local lxc service.

More info on fgrehm's vagrant-mutate github page