Linode Vagrant Provider

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

Current features include:

• create and destroy linodes
• power on and off linodes
• rebuild a linode
• provision a linode with the shell or other provisioners
• setup a SSH public key for authentication
• create a new user account during linode creation
• setup hostname during creation

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:

• You must specify the override.ssh.private_key_path to enable authentication with the linode. The provider will create a new Linode SSH key using your public key which is assumed to be the private_key_path with a .pub extension.
• You must specify your Linode Personal Access Token. This may be found on the control panel within the my profile > API Keys section.

Supported Configuration Attributes

The following attributes are available to further configure the provider:

• provider.distribution - A string representing the distribution to use when creating a new linode (e.g. Debian 8.1). The available options may be found on Linode's Supported Distributions page. It defaults to Ubuntu 14.04 LTS.
• provider.datacenter - A string representing the datacenter to create the new linode in. It defaults to dallas.
• provider.plan - A string representing the size to use when creating a new linode (e.g. Linode 4096). It defaults to Linode 2048.
• provider.private_networking - A boolean flag indicating whether to enable a private network interface. It defaults to false.
• provider.ssh_key_name - A string representing the name to use when creating a Linode SSH key for linode authentication. It defaults to Vagrant.
• provider.setup - A boolean flag indicating whether to setup a new user account and modify sudo to disable tty requirement. It defaults to true. If you are using a tool like packer to create reusable snapshots with user accounts already provisioned, set to false.
• provider.label - A string representing the Linode label to assign when creating a new linode
• provider.group - A string representing the Linode's Display group to assign when creating a new linode

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:

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:

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:

• The volume needs to be formatted and mounted inside the VM either manually or by a StackScript, etc.
• The plugin doesn't do any volume metadata management. If a volume is renamed the next vagrant up call will create a new one.
• Running vagrant destroy will NOT destroy the volumes.

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:

• vagrant destroy - Destroys the linode instance.
• vagrant ssh - Logs into the linode instance using the configured user account.
• vagrant halt - Powers off the linode instance.
• vagrant provision - Runs the configured provisioners and rsyncs any specified config.vm.synced_folder. (see https://docs.vagrantup.com/v2/synced-folders/rsync.html)
• vagrant reload - Reboots the linode instance.
• vagrant rebuild - Destroys the linode instance and recreates it with the same IP address which was previously assigned.
• vagrant status - Outputs the status (active, off, not created) for the linode instance.
• vagrant linode - Offers Linode resource listing options for datacenters, distributions, images, networks, plans, and servers

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