Vagrant SoftLayer Provider

Gem Version Code Climate

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 and SL_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

Parameter Description Default Required
provision_timeout Provisioning wait timeout in seconds 1200 no
rebuild_timeout Rebuild wait timeout in seconds 1200 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

Credits

Emiliano Ticci (@emyl) Julio Lajara (@ju2wheels)