Skip to content

Latest commit

 

History

History
263 lines (192 loc) · 9.5 KB

README.md

File metadata and controls

263 lines (192 loc) · 9.5 KB
Raw

Vagrant SoftLayer Provider

[![Gem Version](https://badge.fury.io/rb/vagrant-softlayer.png)](http://badge.fury.io/rb/vagrant-softlayer) [![Code Climate](https://codeclimate.com/github/audiolize/vagrant-softlayer.png)](https://codeclimate.com/github/audiolize/vagrant-softlayer)

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/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)