Vagrant SoftLayer Provider
This is a Vagrant plugin that adds a SoftLayer 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 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
andSL_USERNAME
.
DNS Management
If the DNS zone of the configured domain is hosted by SoftLayer, 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.
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.
Development
To work on the vagrant-softlayer
plugin, clone this repository out, and use
Bundler 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 branch/workflow management. Please
submit any pull requests to the develop
branch.
Credits
Emiliano Ticci (@emyl) Julio Lajara (@ju2wheels)