Vagrant Plugin

Version: vagrant-profitbricks v4.0.0

Table of Contents

• Description
• Getting Started
• Installation
• Usage
• Vagrant Actions
  • Create a Vagrant Machine
  • Add Vagrant Box
  • SSH Into Vagrant Machine
  • Vagrant Provisioner
  • Stop Vagrant Machine
  • Start Vagrant Machine
  • Reboot Vagrant Machine
• Vagrant Commands
  • Datacenters
  • Flavors
  • Images
  • Locations
  • Snapshots
• Vagrantfile Reference
• Examples
• Support
• Testing
• Contributing

Description

Vagrant is a tool that allows users to automatically deploy and configure local and cloud infrastructure using a consistent, declarative configuration file. The ProfitBricks plugin for Vagrant leverages the Cloud API to deploy servers directly onto the ProfitBricks platform.

Getting Started

Before you begin you will need to have signed-up for a ProfitBricks account. The credentials you establish during sign-up will be used to authenticate against the ProfitBricks Cloud API.

Installation

Vagrant must first be installed. Please review the installation documentation for details on downloading and installing Vagrant.

Then install the ProfitBricks plugin using the standard Vagrant plugin installation method.

$ vagrant plugin install vagrant-profitbricks

Overview

A list of available operations can be accessed directly from the command line.

vagrant profitbricks -h

Usage: vagrant [options] <command> [<args>]

    -v, --version                    Print the version and exit.
    -h, --help                       Print this help.

Common commands:
     box             manages boxes: installation, removal, etc.
     connect         connect to a remotely shared Vagrant environment
     destroy         stops and deletes all traces of the vagrant machine
     global-status   outputs status Vagrant environments for this user
     halt            stops the vagrant machine
     help            shows the help for a subcommand
     init            initializes a new Vagrant environment by creating a Vagrantfile
     login           log in to HashiCorp's Vagrant Cloud
     package         packages a running vagrant environment into a box
     plugin          manages plugins: install, uninstall, update, etc.
     port            displays information about guest port mappings
     powershell      connects to machine via powershell remoting
     provision       provisions the vagrant machine
     push            deploys code in this environment to a configured destination
     rdp             connects to machine via RDP
     reload          restarts vagrant machine, loads new Vagrantfile configuration
     resume          resume a suspended vagrant machine
     share           share your Vagrant environment with anyone in the world
     snapshot        manages snapshots: saving, restoring, etc.
     ssh             connects to machine via SSH
     ssh-config      outputs OpenSSH valid configuration to connect to the machine
     status          outputs status of the vagrant machine
     suspend         suspends the machine
     up              starts and provisions the vagrant environment
     validate        validates the Vagrantfile
     version         prints current and latest Vagrant version

For help on any individual command run `vagrant COMMAND -h`

Additional subcommands are available, but are either more advanced
or not commonly used. To see all subcommands, run the command
`vagrant list-commands`.

If you want to retrieve list of plugin specific subcommands then run:

vagrant profitbricks

Usage: vagrant profitbricks <subcommand> [<args>]

Available subcommands:
     datacenters
     flavors
     images
     locations
     snapshots

For help on any individual subcommand run `vagrant profitbricks <subcommand> -h`

You will need a Vagrantfile in order to properly create and configure remote servers. You can generate a sample Vagrantfile with vagrant init. Here is an example of the ProfitBricks configuration:

config.ssh.private_key_path = '/path/to/.ssh/id_rsa'

config.vm.provider :profitbricks do |profitbricks|
  profitbricks.username = ENV['PROFITBRICKS_USERNAME']
  profitbricks.password = ENV['PROFITBRICKS_PASSWORD']
  profitbricks.profitbricks_url = 'https://api.profitbricks.com/cloudapi/v4/'
  profitbricks.datacenter_id = 'f98e9d49-e33b-4d59-9ac3-484f7f749b78'
  profitbricks.location = 'de/fkb'
  profitbricks.image_alias = 'ubuntu:latest'
  profitbricks.cores = 4
  profitbricks.profitbricks_ram = 4096
  profitbricks.image_password = 'secretpassword123'
  # Allows SSH authentication (Works with ProfitBricks supplied Linux images)
  profitbricks.public_ssh_keys = [File.read('/path/to/.ssh/id_rsa.pub')]
end

Vagrant Actions

Actions are Vagrant actions that allow interaction with Vagrant managed machines.

Create a Vagrant Machine

Once the plugin is installed and Vagrantfile configured properly, you bring build a new machine with vagrant up:

$ vagrant up

Add Vagrant Box

You may be required to use a box depending on your version of Vagrant. If necessary, you can add the "dummy" box with the command:

$ vagrant box add dummy https://github.com/profitbricks/vagrant-profitbricks/raw/master/dummy.box

Then add a line containing config.vm.box = "dummy" to the Vagrantfile.

SSH Into Vagrant Machine

The user can log into the machine via SSH after server creation:

$ vagrant ssh

Vagrant Provisioner

Any Vagrant provisioner can be run on the Vagrant managed machine.

A simple shell provisioner can be can be added to the Vagrantfile similar to the following.

config.vm.provision 'shell' do |s|
  s.inline = 'apt-get update && apt-get install -y'
end

Then run the provisioner:

$ vagrant provision

Stop Vagrant Machine

In order to stop a Vagrant managed machine:

vagrant halt

Start Vagrant Machine

To start a Vagrant managed machine:

vagrant up

Reboot Vagrant Machine

To reboot a Vagrant managed machine:

vagrant reload

Vagrant Commands

Commands are plugin specific subcommands which allow users to retrieve a list of ProfitBricks resources.

To get list of available subcommands run:

vagrant profitbricks

Currently the following resources are available to view.

• datacenters
• flavors
• images
• locations
• snapshots

Datacenters

To retrieve list of available ProfitBricks Virtual Data Center run:

vagrant profitbricks datacenters

+--------------------------------------+--------------------------+
| ID                                   | Name                     |
+--------------------------------------+--------------------------+
| f98e9d49-e33b-4d59-9ac3-484f7f749b78 | Vagrant Example          |
+--------------------------------------+--------------------------+

Flavors

To retrieve list of available flavors:

vagrant profitbricks flavors

+--------------------------------------+-------------------------+
| ID                                   | Name                    |
+--------------------------------------+-------------------------+
| 0052db40-f1dd-4ecf-a711-5980081b7059 | Extra Large             |
| 00db4c8f-5e83-49b0-a70b-ac4aad786163 | Micro                   |
| 1d22436d-d958-4151-b144-43a8e180c4c4 | Memory Intensive Large  |
| 45c28f8b-6a67-4f69-8c94-231d371da2b6 | Memory Intensive Medium |
| 8b2b835d-be09-48cf-aae2-7e35aafe92d6 | Memory Intensive Small  |
| a5a4389f-54b6-4f47-b6e8-1c5c55976b94 | Large                   |
| b37d000e-b347-4592-b572-df13ef8f68e1 | Medium                  |
| dc64957b-be9d-431e-91cd-9e217f94d3de | Small                   |
+--------------------------------------+-------------------------+

Images

To list all available ProfitBricks images:

vagrant profitbricks images

+--------------------------------------+-------------------------------------------+----------+
| ID                                   | Name                                      | Location |
+--------------------------------------+-------------------------------------------+----------+
| 19556107-46b5-11e7-9645-525400f64d8d | grml64-full_2017.05.iso                   | de/fkb   |
...
...
| 3b53e0bd-84d2-11e6-9d61-52540005ab80 | windows-2008-r2-server-setup.iso          | us/las   |
| 6261e8bb-84a6-11e6-9d61-52540005ab80 | windows-2012-r2-server-setup.iso          | de/fra   |
| 6d00c53d-76b3-11e7-98fa-525400f64d8d | Fedora-Server-netinst-x86_64-26-1.5.iso   | us/las   |
+--------------------------------------+-------------------------------------------+----------+

Locations

A list of all ProfitBricks locations is available:

vagrant profitbricks locations

+--------+-----------+
| ID     | Name      |
+--------+-----------+
| de/fkb | karlsruhe |
| de/fra | frankfurt |
| us/ewr | newark    |
| us/las | lasvegas  |
+--------+-----------+

Snapshots

To retrieve list of all snapshots within user account you can use this subcommand:

vagrant profitbricks snapshots

+--------------------------------------+-----------------------------------+
| ID                                   | Name                              |
+--------------------------------------+-----------------------------------+
| 1e946713-3fec-464d-9fd3-bfc5345f273e | snapshot1                         |
| 8571fda2-57c6-4b73-b827-88cc7e3f7638 | snapshot2                         |
| ad225f22-f154-4c12-aa55-1ec9026c494d | snapshot3                         |
+--------------------------------------+-----------------------------------+

Vagrantfile Reference

This provider exposes some provider-specific configuration options:

NAME	DESCRIPTION
datacenter_id	Virtual Data Center ID where machines will be managed.
username	Your ProfitBricks username.
password	Your ProfitBricks password.
flavor	A predefined server flavor to use. This can be a string matching the exact UUID or name of the server. Or this can be a regular expression to partially match a server flavor name.
cores	The number of server cores to allocate. This is as an alternative to a flavor.
ram	The amount of server memory in MB to allocate. This is as an alternative to a flavor.
volume_size	The size of the volume in GB.
volume_type	Disk volume type (SSD or HDD). Defaults to SSD if not specified.
volume_licence_type	The licence type of the volume. Options: LINUX, WINDOWS, UNKNOWN, OTHER. You will need to provide either the image or the volume_licence_type option.
volume_availability_zone	The storage availability zone assigned to the volume. Valid values: AUTO, ZONE_1, ZONE_2, or ZONE_3. This only applies to HDD volumes. Leave blank or set to AUTO when provisioning SSD volumes. Will default to AUTO if not specified.
image	The server image to boot. This can be a string matching the exact ID or name of the image or this can be a regular expression to partially match some image.
image_alias	The server image to boot. This has to be a string matching the exact name of the image_alias for e.g. ubuntu:latest, coreos:latest
image_password	One-time password is set on the image for the appropriate administrative account. This field may only be set on creation requests. When reading, it always returns null. Password has to contain 8-50 alphanumeric characters.
public_ssh_keys	Public SSH keys to allow server authentication.
profitbricks_url	Allows the ProfitBricks Cloud API URL to be overridden.
server_name	The server name defaults to the name of the Vagrant machine (via config.vm.define), but can be overridden with this option.
location	Specify location for the datacenter if one needs to be created. Defaults to us/las.
cpu_family	Sets the CPU type to "AMD_OPTERON" or "INTEL_XEON". Defaults to AMD_OPTERON.
lan_id	The LAN ID that the network interface (NIC) will connect to. If the LAN ID does not exist it will be created.
nat	Indicates the private IP address has outbound access to the public internet. Defaults to false.

---

Examples

If you wish to create multiple Vagrant machines using the ProfitBricks plugin, you can add the following to your Vagrantfile:

Vagrant.configure('2') do |config|

  config.ssh.private_key_path = '/path/to/.ssh/id_rsa'
  public_ssh_keys = [ File.read('/path/to/.ssh/id_rsa.pub') ]

  config.vm.define :node1 do |node|
    node.vm.provider :profitbricks do |pb|
      pb.datacenter_id = '186d27a5-cda0-44fb-b852-18add4d1a1f5'
      pb.username = ENV['PROFITBRICKS_USERNAME']
      pb.password = ENV['PROFITBRICKS_PASSWORD']
      pb.public_ssh_keys = public_ssh_keys
      pb.cores = 2
      pb.ram = 4096
      pb.image_alias = 'ubuntu:latest'
    end
  end

  config.vm.define :node2 do |node|
    node.ssh.pty = true
    node.vm.provider :profitbricks do |pb|
      pb.datacenter_id = '186d27a5-cda0-44fb-b852-18add4d1a1f5'
      pb.username = ENV['PROFITBRICKS_USERNAME']
      pb.password = ENV['PROFITBRICKS_PASSWORD']
      pb.public_ssh_keys = public_ssh_keys
      pb.flavor = /Micro/
      pb.image_alias  = 'centos:latest'
    end
  end
end

This Vagrantfile will create two Vagrant machines named ubuntu and centos.

Support

• A guide and reference documentation can be found in the repo docs/ directory.
• ProfitBricks REST API documentation.
• Ask a question or discuss at ProfitBricks DevOps Central.
• Report an issue here.

Testing

To work on the vagrant-profitbricks plugin, clone this repository and use Bundler to fetch the dependencies:

$ bundle install

Once you have the dependencies, verify the unit tests pass with:

$ rspec spec/

Contributing

1. Fork it ( https://github.com/[my-github-username]/vagrant-profitbricks/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request