# Vagrant GQ Provider

This is a [Vagrant](http://www.vagrantup.com) 1.2+ plugin that adds a [GreenQloud](http://www.greenqloud.com)
provider to Vagrant, allowing Vagrant to control and provision machines in GreenQloud.

**NOTE:** This plugin requires Vagrant 1.2+,

## Features

* Boot GreenQloud instances.
* SSH into the instances.
* Provision the instances with any built-in Vagrant provisioner.
* Minimal synced folder support via `rsync`.
* Define region-specifc configurations so Vagrant can manage machines
  in multiple regions.

## Usage

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

```
$ vagrant plugin install vagrant-gq
...
$ vagrant up --provider=gq
...
```

Prior to doing this, you'll need to obtain a GreenQloud compatible
box file for Vagrant. See the Quick Start below for an example using the
greenqloud-generic.box.

## Quick Start

After installing the plugin (instructions above), the quickest way to get
started is to actually use a generic GreenQloud box and specify all the details
manually within a `config.vm.provider` block, in your Vagrantfile:

```
Vagrant.configure("2") do |config|
  config.vm.box = "greenqloud-generic"
  config.vm.box_url = "https://vagrant.s.greenqloud.com/greenqloud-generic.box"

  config.vm.provider :gq do |gq, override|
    gq.access_key_id = "YOUR KEY"
    gq.secret_access_key = "YOUR SECRET KEY"
    gq.keypair_name = "KEYPAIR NAME"

    gq.qmi = "qmi-60ce3bb8"

    override.ssh.username = "ubuntu"
    override.ssh.private_key_path = "PATH TO YOUR PRIVATE KEY"
  end
end
```

And then run `vagrant up --provider=gq`.

This will start a Ubuntu 14.04 instance within your account. Assuming
your SSH information was filled in properly, SSH and provisioning will
work as well.

Note that normally a lot of this boilerplate is encoded within the box
file, but the box file used for the quick start, the "generic" box, has
no preconfigured defaults.

If you have issues with SSH connecting, make sure that the instances
are being launched with a security group that allows SSH access.

## Box Format

Every provider in Vagrant must introduce a custom box format. This
provider introduces `gq` boxes. You can view an example box in
the [example_box/ directory](https://github.com/greenqloud/vagrant-gq/tree/master/example_box).
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.

## Configuration

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

* `access_key_id` - The access key for accessing GreenQloud
* `qmi` - The QMI id to boot, such as "qmi-12345678"
* `instance_ready_timeout` - The number of seconds to wait for the instance
  to become "ready" in GreenQloud. Defaults to 120 seconds.
* `instance_type` - The type of instance, such as "m1.small". The default
  value of this if not specified is "m1.small".
* `keypair_name` - The name of the keypair to use to bootstrap QMIs
   which support it.
* `secret_access_key` - The secret access key for accessing GreenQloud
* `security_groups` - An array of security groups for the instance.

These can be set like typical provider-specific configuration:

```ruby
Vagrant.configure("2") do |config|
  # ... other stuff

  config.vm.provider :gq do |gq|
    gq.access_key_id = "foo"
    gq.secret_access_key = "bar"
  end
end
```

## Networks

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

## Synced Folders

There is minimal support for synced folders. Upon `vagrant up`,
`vagrant reload`, and `vagrant provision`, the GreenQloud 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!

## User data

You can specify user data for the instance being booted.

```ruby
Vagrant.configure("2") do |config|
  # ... other stuff

  config.vm.provider :gq do |gq|
    # Option 1: a single string
    gq.user_data = "#!/bin/bash\necho 'got user data' > /tmp/user_data.log\necho"

    # Option 2: use a file
    gq.user_data = File.read("user_data.txt")
  end
end
```

## Acknowledgements

Vagrant-gq is a fork of vagrant-aws, copyright Mitchell Hashimoto. See the LICENSE file for further details.