search

ggiamarchi / vagrant-openstack-provider

Use Vagrant to manage OpenStack Cloud instances.
MIT License
247 stars 101 forks source link
cloud devops devops-tools iaas openstack vagrant vagrant-plugin vagrant-providers virtual-machine

readme

Vagrant OpenStack Cloud Provider

Build Status Gem Version

This is a Vagrant 1.6+ plugin that adds an OpenStack Cloud provider to Vagrant, allowing Vagrant to control and provision machines within OpenStack cloud.

Note: This plugin was originally forked from mitchellh/vagrant-rackspace

Features

Usage

Install using standard Vagrant 1.1+ plugin installation methods. After installing, vagrant up and specify the openstack provider. An example is shown below.

$ vagrant plugin install vagrant-openstack-provider
...
$ vagrant up
...

Make sure you have a recent version of vagrant (>1.7.1).

Quick Start

After installing the plugin (instructions above), the quickest way to get started is to specify all the details manually within a config.vm.provider block in the Vagrantfile

Create a Vagrantfile that looks like the following, filling in your information where necessary.

This Vagrantfile shows the minimal needed configuration.

require 'vagrant-openstack-provider'

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

  config.ssh.username = 'stack'

  config.vm.provider :openstack do |os|
    os.openstack_auth_url = 'http://keystone-server.net/v2.0/tokens'
    os.username           = 'openstackUser'
    os.password           = 'openstackPassword'
    os.tenant_name        = 'myTenant'
    os.flavor             = 'm1.small'
    os.image              = 'ubuntu'
    os.floating_ip_pool   = 'publicNetwork'
  end
end

And then run vagrant up.

NB.

See more examples in the samples directory.

Configuration reference

This provider exposes quite a few provider-specific configuration options:

Credentials

Machine Configuration

Floating IPs

floating_ip_pool attribute can be either a string or an array. In case of an array, if an IP can't be allocated from the first pool for any reason, it will try with the second one and so on. Finally, if it does not manage to allocate a floating IP from any pools of the list, it will fail.

config.vm.provider :openstack do |os|
  ...
  os.floating_ip_pool = ['External-Network-01', 'External-Network-02']
  ...
end

N.B.

If the instance have a floating IP, this IP will be used to SSH into the instance.

Networks

Networking features in the form of config.vm.network are not supported with vagrant-openstack, currently. If any of these are specified, Vagrant will emit a warning, but will otherwise boot the OpenStack server.

You can provide network id or name. However, in OpenStack a network name is not unique, thus if there are two networks with the same name in your project the plugin will fail. If so, you have to use only ids. Optionally, you can specify the IP address that will be assigned to the instance if you need a static address or if DHCP is not enable for this network.

Here's an example which connect the instance to six Networks :

config.vm.provider :openstack do |os|
  ...
  os.networks = [
    'net-name-01',
    '287132f0-57e6-4c31-a1ee-4823e9786ff2',
    {
      name: 'net-name-03',
      address: '192.168.22.43'
    },
    {
      id: '7dfdcf01-5177-4774-9473-2ae92a6447d4',
      address: '192.168.43.76'
    },
    {
      name: 'net-name-05'
    },
    {
      id: '01e0950f-c668-4efe-821b-93ff6e427562'
    }
  ]
  ...
end

N.B.

If the instance does not have a floating IP, the IP of the first network in the list will be used to SSH into the instance

Volumes

Here comes an example that show six volumes attached to a server :

config.vm.provider :openstack do |os|
  ...
  os.volumes = [
    '619e027c-f4a9-493d-8c15-c89de81cb949',
    'vol-name-02',
    {
      id: '410096ff-ef71-4ca4-8006-e5bd9e99239a',
      device: '/dev/vdc'
    },
    {
      name: 'vol-name-04',
      device: '/dev/vde'
    },
    {
      name: 'vol-name-05'
    },
    {
      id: '9e419e91-8f66-4803-bc45-4600182cfd8d'
    }
  ]
  ...
end

Orchestration Stacks

Here comes an example that show two stacks :

config.vm.provider :openstack do |os|
 ...
os.stacks = [
  {
    name: 'mystack1',
    template: 'heat_template.yml'
  }, {
    name: 'mystack2',
    template: '/path/to//my/heat_template.yml'
  }]
end

SSH authentication

If neither keypair_name nor public_key_path are set, vagrant will generate a new ssh key and automatically import it in OpenStack, unless config.ssh.insert_key is false.

Synced folders

NOTE: The settings in this section are deprecated. By default, the OpenStack provider will use standard Vagrant Synced Folders. Vagrant's rsync options can be configured thusly:

Vagrant.configure("2") do |config|
  config.vm.provider :openstack do |provider, override|
    override.vm.synced_folder '.', '/vagrant', type: 'rsync',
      rsync__exclude: ['some/folder/to/exclude']
  end
end

Use of the settings described below will cause the OpenStack provider to fall back to a legacy Rsync implementation that has fewer features. A deprecation warning will also be printed.

There is minimal support for synced folders. Upon vagrant up, vagrant reload, and vagrant provision, the OpenStack provider will use rsync (if available) to uni-directionally sync the folder to the remote machine over SSH.

This is good enough for all built-in Vagrant provisioners (shell, chef, and puppet) to work!

HTTP options

Provisioners meta-args

We call meta-args, dynamic arguments automatically injected by the vagrant OpenStack provider as a provisioner argument. The notation for a meta-arg is its name surrounded by double @ character.

The current implementation supports only shell provisioner.

Available meta-args

Usage example

config.vm.provision "shell", inline: 'echo "$1 : $2" > ~/provision', args: ['IP', '@@ssh_ip@@']

N.B.

Activate meta-args support causes Vagrant to wrap the built-in provisioning middleware into a custom one provided by the OpenStack provider. As a consequence, hooks declared on the built-in provisioning middleware will not be applied (see #248)

Vagrant standard configuration

There are some standard configuration options that this provider takes into account when creating and connecting to OpenStack machines

Box Format

Every provider in Vagrant must introduce a custom box format. This provider introduces openstack boxes. You can view an example box in the example_box/ directory. That directory also contains instructions on how to build a box.

The box format is basically just the required metadata.json file along with a Vagrantfile that does default settings for the provider-specific configuration for this provider.

Custom commands

Custom commands are provided for OpenStack. Type vagrant openstack to show available commands.

$ vagrant openstack

Usage: vagrant openstack command

Available subcommands:
     image-list           List available images
     flavor-list          List available flavors
     network-list         List private networks in project
     subnet-list          List subnets for available networks
     floatingip-list      List floating IP and floating IP pools
     volume-list          List existing volumes
     reset                Reset Vagrant OpenStack provider to a clear state

For instance vagrant openstack image-list lists images available in Glance.

$ vagrant openstack image-list

+--------------------------------------+---------------------+
| ID                                   | Name                |
+--------------------------------------+---------------------+
| 594f1287-9de3-4f3e-b82a-6ad223943ab2 | ubuntu-12.04_x86_64 |
| 3e5aca4a-bf12-4721-87df-7bc8fd1fc36c | debian7_x86_64      |
| 3e561121-d8d0-4328-b319-7076bfb3b18a | ubuntu-14.04_x86_64 |
| 5c576643-7ea3-49db-b1c0-9b245d955ee0 | rhel65_x86_64       |
| d3145dd5-654a-4936-b421-9333f02ae66c | centos6_x86_64      |
+--------------------------------------+---------------------+

Contribute

Development

To work on the vagrant-openstack plugin, clone this repository out, and use Bundler to get the dependencies.

This is actually done automatically using the Vagrantfile at the root of this repository to setup a Virtualbox machine embbeding a Devstack installation and a Ruby development environment.

From this VM, basically run vagrant as usual to test your local source code changes. It is going to run into a bundler context to use sources mounted in /vagrant.

A basic Vagrantfile is present in dev/test in order to ensure your dev environement is operating as expected.

Also, run the following command to launch code style checks and unit tests.

$ bundle exec rake

Troubleshooting

Logging

To enable all Vagrant logs set environment variable VAGRANT_LOG to the desire log level (for instance VAGRANT_LOG=debug). If you want only OpenStack provider logs use the variable VAGRANT_OPENSTACK_LOG. if both variables are set, VAGRANT_LOG takes precedence.

Version checker

Each time Vagrant OpenStack Provider runs it checks the installed plugin version and print a warning on stderr if the plugin is not up-to-date.

If for any reason you need to disable this check, set the environment variable VAGRANT_OPENSTACK_VERSION_CKECK to value DISABLED prior to run vagrant.

CentOS/RHEL/Fedora (sudo: sorry, you must have a tty to run sudo)

The default configuration of the RHEL family of Linux distributions requires a tty in order to run sudo. Vagrant does not connect with a tty by default, so you may experience the error:

sudo: sorry, you must have a tty to run sudo

The best way to take deal with this error is to upgrade to Vagrant 1.4 or later, and enable:

config.ssh.pty = true