README.md
# Vagrant SoftLayer Provider
<span class="badges">
[](http://badge.fury.io/rb/vagrant-softlayer)
[](https://codeclimate.com/github/audiolize/vagrant-softlayer)
</span>
This is a [Vagrant](http://www.vagrantup.com) plugin that adds a [SoftLayer](http://www.softlayer.com)
provider to Vagrant, allowing Vagrant to control and provision SoftLayer CCI instances.
**NOTE:** This plugin work with Vagrant 1.3+, altough Vagrant 1.4+ is strongly advised.
## Features
* Basic lifecycle (boot, halt, reboot, suspend, resume) of SoftLayer CCI instances.
* OS reload on a CCI (`vagrant rebuild`).
* SSH into the instances.
* Provision the instances with any built-in Vagrant provisioner.
* Minimal synced folder support via `rsync`.
## Installation
> **NOTE**
>
> If you're using Vagrant 1.3, you need to [Set the SSL_CERT_FILE environment variable](https://github.com/audiolize/vagrant-softlayer/wiki/The-SSL_CERT_FILE-environment-variable) first.
Installation is performed in the prescribed manner for Vagrant 1.1+ plugins.
After installing, `vagrant up` and specify the `softlayer` provider. An example is
shown below.
```
$ vagrant plugin install vagrant-softlayer
...
$ vagrant up --provider=softlayer
...
```
Of course prior to doing this, you'll need to obtain an SoftLayer-compatible
box file for Vagrant.
## Box File Format
Every provider in Vagrant must introduce a custom box format. This
provider introduces `softlayer` 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.
## Configuration
This provider exposes quite a few provider-specific configuration options:
### Authentication
Parameter | Description | Default | Required
-------------- | ------------------------------------ | ---------------------------------- | --------
`api_key` | The API key for accessing SoftLayer | | yes
`endpoint_url` | The endpoint SoftLayer API url | SoftLayer::API_PUBLIC_ENDPOINT | yes
`username` | The username for accessing SoftLayer | | yes
> **NOTE**
>
> In place of the API key and username you can use environment variables, respectively `SL_API_KEY` and `SL_USERNAME`.
### DNS Management
If the [DNS zone](http://knowledgelayer.softlayer.com/learning/introduction-domain-name-system) of the configured domain is hosted by [SoftLayer](http://knowledgelayer.softlayer.com/topic/dns), you can automatically manage it.
Parameter | Description | Default | Required
------------ | ------------------------------------- | ------- | --------
`manage_dns` | Add/remove A record on create/destroy | false | no
### Join Local Load Balancers
See [Join load balancers](https://github.com/audiolize/vagrant-softlayer/wiki/Join-load-balancers).
### Instance Configuration
Parameter | Description | Default | Required
------------------ | -----------------------------------------------------------| ----------------| --------
`datacenter` | Datacenter shortname | First available | no
`dedicated` | Allocate a dedicated CCI (non-shared host) | false | no
`disk_capacity` | The capacity of each disk | | no **
`domain` | The domain of the instance | | yes
`force_private_ip` | Use private IP for communication even if public IP is set | false | no
`hostname` | The hostname of the instance | | yes *
`hourly_billing` | Hourly billing type (false for monthly) | true | no
`image_guid` | The global identifier for the compute or flex image to use | | no **
`local_disk` | Use a local disk (false for SAN) | true | no
`max_memory` | The amount of RAM of the instance in Mb | 1024 | no
`network_speed` | Network port speed in Mbps | 10 | no
`operating_system` | The instance operating system identifier | UBUNTU_LATEST | no **
`post_install` | URI of Post-install script to download | | no
`private_only` | Only create access to the private network | false | no
`ssh_key` | ID or label of the SSH key(s) to provision | | yes
`start_cpus` | The number of processors of the instance | 1 | no
`user_data` | User defined metadata string | | no
`vlan_private` | The ID, name or qualified name of the private VLAN | Auto-generated | no
`vlan_public` | The ID, name or qualified name of the public VLAN | Auto-generated | no
\* The `hostname` could be specified either using `config.vm.hostname` or the provider parameter.
\** When defining the instance you can either specify an `image_guid` or `operating_system` with optional `disk_capacity`.
### Timeouts/Waits
Parameter | Description | Default | Required
------------------- | ------------------------------------------| ----------------| --------
`api_timeout` | SoftLayer API call timeout in seconds | 60 | no
`provision_timeout` | Provisioning wait timeout in seconds | 1200 | no
`rebuild_timeout` | Rebuild wait timeout in seconds | 1200 | no
`transaction_wait` | Wait for order transactions to complete | true | no
These can be set like typical provider-specific configuration:
```
Vagrant.configure("2") do |config|
# ... other stuff
config.vm.provider :softlayer do |sl|
sl.api_key = "foo"
sl.username = "bar"
sl.ssh_key = "Vagrant insecure key"
end
end
```
## OS Reload
Reload of an instance's operating system is performed with the `vagrant rebuild` command.
The primary disk of the instance will be formatted and a fresh copy of the underlying OS
will be applied. Note that only `ssh_key` and `post_install` parameter will be read
during rebuild, all the other parameters will be ignored. Provisioners will always run
after rebuild.
## Synced Folders
There is minimal support for synced folders. Upon `vagrant up`,
`vagrant reload`, and `vagrant provision`, the SoftLayer 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, ansible,
chef, and puppet) to work!
## Other Examples
### Multiple disks
The `disk_capacity` parameter accepts an hash with the following structure:
```
{
disk_id => disk_size,
disk_id => disk_size,
...
}
```
Disk ID 1 is reserved is reserved for swap space, in the following example two disks
of 25Gb and 100Gb will be provisioned:
```
Vagrant.configure("2") do |config|
# ... other stuff
config.vm.provider :softlayer do |sl, override|
# ... other stuff
sl.disk_capacity = { 0 => 25, 2 => 100 }
end
end
```
### Override SSH Username
If you're running Vagrant with an user different from root, probably you need
to override the username used for ssh connection. You can do it using the standard
Vagrant syntax:
```
Vagrant.configure("2") do |config|
# ... other stuff
config.vm.provider :softlayer do |sl, override|
# ... other stuff
override.ssh.username = "root"
end
end
```
### Multiple SSH keys
Multiple SSH keys to be provisioned could be specified using an array:
```
Vagrant.configure("2") do |config|
# ... other stuff
config.vm.provider :softlayer do |sl|
sl.api_key = "foo"
sl.username = "bar"
# ssh_keys is just an alias of ssh_key
sl.ssh_keys = ["Vagrant insecure key", "My personal key"]
end
end
```
Also, a bunch of aliases for the `ssh_key` parameter are provided for better semantic:
* `ssh_keys`
* `ssh_key_id`
* `ssh_key_ids`
* `ssh_key_name`
* `ssh_key_names`
## Quick Start Guide
For those new to Vagrant, see the [Quick Start Guide](https://github.com/audiolize/vagrant-softlayer/blob/master/QUICKSTART.md).
## Development
To work on the `vagrant-softlayer` plugin, clone this repository out, and use
[Bundler](http://gembundler.com) to get the dependencies:
```
$ bundle
```
Once you have the dependencies, verify the unit tests pass with `rake`:
```
$ bundle exec rake
```
If those pass, you're ready to start developing the plugin. You can test
the plugin without installing it into your Vagrant environment by just
creating a `Vagrantfile` in the top level of this directory (it is gitignored)
and add the following line to your `Vagrantfile`:
```
Vagrant.require_plugin "vagrant-softlayer"
```
Use bundler to execute Vagrant:
```
$ bundle exec vagrant up --provider=softlayer
```
## Contributing
`vagrant-softlayer` is following [git-flow](https://github.com/nvie/gitflow) branch/workflow management. Please
submit any pull requests to the `develop` branch.
## Credits
Emiliano Ticci (@emyl)
Julio Lajara (@ju2wheels)