displague / vagrant-linode

A Vagrant plugin that adds a Linode provider to Vagrant, allowing Vagrant to control and provision Linodes.
MIT License
124 stars 23 forks source link

Linode Vagrant Provider

vagrant-linode is a provider plugin for Vagrant that supports the management of Linode linodes (instances).

Current features include:

The provider has been tested with Vagrant 1.6.3+ using Ubuntu 14.04 LTS and Debian 7.5+ guest operating systems.

Install

Installation of the provider couldn't be easier:

vagrant plugin install vagrant-linode

Configure

Once the provider has been installed, you will need to configure your project to use it. The most basic Vagrantfile to create a linode on Linode is shown below (with most of the available options included but commented out):

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

  config.vm.provider :linode do |provider, override|
    override.ssh.private_key_path = '~/.ssh/id_rsa'
    override.vm.box = 'linode/ubuntu1404'

    provider.api_key = 'API_KEY'
    provider.distribution = 'Ubuntu 18.04 LTS'
    provider.datacenter = 'newark'
    provider.plan = 'Linode 2GB' # This will work
    # provider.plan = 'Linode 2048' # This will still work
    # provider.plan = 'Linode 2' # This may work, but may be ambiguous
    # provider.planid = <int>
    # provider.paymentterm = <*1*,12,24>
    # provider.datacenterid = <int>
    # provider.image = <string>
    # provider.imageid = <int>
    # provider.kernel = <string>
    # provider.kernelid = <int>
    # provider.private_networking = <boolean>
    # provider.stackscript = <string> # Not Supported Yet
    # provider.stackscriptid = <int> # Not Supported Yet
    # provider.distributionid = <int>
  end
end

Please note the following:

Supported Configuration Attributes

The following attributes are available to further configure the provider:

The provider will create a new user account with the specified SSH key for authorization if config.ssh.username is set and the provider.setup attribute is true.

provider.plan

Each Linode Tier has been assigned a Plan Identification Number. Current (April 2019) Plan-ID table follows:

Plan ID Plan Name
1 Nanode 1GB
2 Linode 2GB
3 Linode 4GB
4 Linode 8GB
5 Linode 16GB
6 Linode 32GB
7 Linode 64GB
8 Linode 96GB
9 Linode 128GB
10 Linode 192GB
11 Linode 24GB
12 Linode 48GB
13 Linode 90GB
14 Linode 150GB
15 Linode 300GB
16 Dedicated 4GB
17 Dedicated 8GB
18 Dedicated 16GB
19 Dedicated 32GB
20 Dedicated 64GB
21 Dedicated 96GB

This can be obtained through vagrant with:

vagrant linode plans <machine_name>

Or using curl:

curl -X POST "https://api.linode.com/?api_action=avail.linodeplans" \
     --data-ascii api_key="$LINODE_API_KEY" \
     2>/dev/null | jq '.DATA [] | .PLANID,.LABEL'

More detail: Linode API - Plans

provider.datacenter

Each region has been specified with a Data Center ID. Current (Feb 2017) Datacenter-ID table is:

DatacenterID Datacenter Location
4 atlanta Atlanta, GA, USA
2 dallas Dallas, TX, USA
3 fremont Fremont, CA, USA
7 london London, England, UK
6 newark Newark, NJ, USA
8 tokyo Tokyo, JP
9 singapore Singapore, SGP
10 frankfurt Frankfurt, DE
  11         shinagawa1 Tokyo 2, JP

You can find latest datacenter ID number using Vagrant subcommands:

vagrant linode datacenters

Or directly through the API:

curl -X POST "https://api.linode.com/?api_action=avail.datacenters" \
     --data-ascii api_key="$LINODE_API_KEY" \
     2>/dev/null | jq '.DATA [] | .DATACENTERID,.ABBR,.LOCATION'

More detail: Linode API - Datacenters

provider.kernel

The kernel can be specified using the kernelid provider parameter, or with kernel which will use a partial text match.

curl -X POST "https://api.linode.com/?api_action=avail.kernels" \
     --data-ascii api_key="$LINODE_API_KEY" \
     2>/dev/null | jq '.DATA [] | .KERNELID,.LABEL'

More detail: Linode API - Kernels

provider.volumes - Volume Handling

The plugin can create and attach additional volumes when creating Linodes. vagrant rebuild calls will rebuild the VM only and reattach the volume afterwards without losing the contents.

config.vm.provider :linode do |linode|
  linode.plan = "Linode 2048"
  linode.volumes = [
    {label: "extra_volume", size: 1},
  ]
end

NOTES:

nfs.functional

The sync provider, NFS, has been disabled to make rsync easier to use. To enable NFS, run Vagrant with an environment variable LINODE_NFS_FUNCTIONAL=1. This will require a bit more configuration between the Linode and the Vagrant host.

Run

After creating your project's Vagrantfile with the required configuration attributes described above, you may create a new linode with the following command:

$ vagrant up --provider=linode

This command will create a new linode, setup your SSH key for authentication, create a new user account, and run the provisioners you have configured.

The environment variable VAGRANT_DEFAULT_PROVIDER can be set to linode to avoid sending --provider=linode on each vagrant up.

Supported Commands

The provider supports the following Vagrant sub-commands:

More Docs and Tools

Linode Guides and Tutorials - Using Vagrant to Manage Linode Environments Puphpet - Online Vagrantfile Generator

Contribute

To contribute, clone the repository, and use Bundler to install dependencies:

$ bundle

To run the provider's tests, first install vagrant as shown here and then use rake:

$ bundle exec rake test

You can now make modifications. Running vagrant within the Bundler environment will ensure that plugins installed in your Vagrant environment are not loaded.

Building and Publishing

vi lib/vagrant-linode/version.rb
vi CHANGELOG.md
git commit -m 'version 0.1.2' lib/vagrant-linode/version.rb CHANGELOG.md
git tag -s v0.1.2
git push --tags origin master
gem build vagrant-linode.gemspec
gem push vagrant-linode-0.1.2.gem

Join the chat at https://gitter.im/displague/vagrant-linode Code Climate Test Coverage Gem Version Dependency Status MIT Licensed