vagrant-digitalocean
is a Vagrant provider plugin that supports the management of DigitalOcean Droplets (virtual machines).
Features include:
- Create and destroy Droplets
- Power on and off Droplets
- Rebuild a Droplet (destroys and ups with same IP address)
- Provision a Droplet with shell
- Setup a SSH public key for authentication
- Create a new user account during Droplet creation
Install the provider plugin using the Vagrant command-line interface:
vagrant plugin install vagrant-digitalocean
Once the provider has been installed, you will need to configure your project to use it. See the following example for a basic multi-machine Vagrantfile
implementation that manages two DigitalOcean Droplets running Ubuntu 18.04 using a single CPU Droplet with 1GB of memory:
Vagrant.configure('2') do |config|
config.vm.define "droplet1" do |config|
config.vm.provider :digital_ocean do |provider, override|
override.ssh.private_key_path = '~/.ssh/id_rsa'
override.vm.box = 'digital_ocean'
override.vm.box_url = "https://github.com/devopsgroup-io/vagrant-digitalocean/raw/master/box/digital_ocean.box"
override.nfs.functional = false
override.vm.allowed_synced_folder_types = :rsync
provider.token = 'YOUR TOKEN'
provider.image = 'ubuntu-18-04-x64'
provider.region = 'nyc1'
provider.size = 's-1vcpu-1gb'
provider.backups_enabled = false
provider.private_networking = false
provider.ipv6 = false
provider.monitoring = false
end
end
config.vm.define "droplet2" do |config|
config.vm.provider :digital_ocean do |provider, override|
override.ssh.private_key_path = '~/.ssh/id_rsa'
override.vm.box = 'digital_ocean'
override.vm.box_url = "https://github.com/devopsgroup-io/vagrant-digitalocean/raw/master/box/digital_ocean.box"
override.nfs.functional = false
override.vm.allowed_synced_folder_types = :rsync
provider.token = 'YOUR TOKEN'
provider.image = 'ubuntu-18-04-x64'
provider.region = 'nyc3'
provider.size = 's-1vcpu-1gb'
provider.backups_enabled = false
provider.private_networking = false
provider.ipv6 = false
provider.monitoring = false
end
end
end
Configuration Requirements
- You must specify the
override.ssh.private_key_path
to enable authentication with the Droplet. The provider will create a new DigitalOcean SSH key using your public key which is assumed to be theprivate_key_path
with a .pub extension. - You must specify your DigitalOcean Personal Access Token at
provider.token
. This may be found on the control panel within the Apps & API section.
Supported Configuration Attributes
The following attributes are available to further configure the provider:
provider.image
- A string representing the image to use when creating a new Droplet. It defaults to
ubuntu-18-04-x64
. List available images with thevagrant digitalocean-list images $DIGITAL_OCEAN_TOKEN
command. Like when using the DigitalOcean API directly, it can be an image ID or slug.
- A string representing the image to use when creating a new Droplet. It defaults to
provider.ipv6
- A boolean flag indicating whether to enable IPv6
provider.region
- A string representing the region to create the new Droplet in. It defaults to
nyc2
. List available regions with thevagrant digitalocean-list regions $DIGITAL_OCEAN_TOKEN
command.
- A string representing the region to create the new Droplet in. It defaults to
provider.size
- A string representing the size to use when creating a new Droplet (e.g.
s-1vcpu-1gb
). It defaults tos-1vcpu-1gb
. List available sizes with thevagrant digitalocean-list sizes $DIGITAL_OCEAN_TOKEN
command.
- A string representing the size to use when creating a new Droplet (e.g.
provider.private_networking
- A boolean flag indicating whether to enable a private network interface (if the region supports private networking). It defaults to
false
.
- A boolean flag indicating whether to enable a private network interface (if the region supports private networking). It defaults to
provider.backups_enabled
- A boolean flag indicating whether to enable backups for the Droplet. It defaults to
false
.
- A boolean flag indicating whether to enable backups for the Droplet. It defaults to
provider.ssh_key_name
- A string representing the name to use when creating a DigitalOcean SSH key for Droplet authentication. It defaults to
Vagrant
.
- A string representing the name to use when creating a DigitalOcean SSH key for Droplet authentication. It defaults to
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 tofalse
.
- A boolean flag indicating whether to setup a new user account and modify sudo to disable tty requirement. It defaults to
provider.monitoring
- A boolean indicating whether to install the DigitalOcean agent for monitoring. It defaults to
false
.
- A boolean indicating whether to install the DigitalOcean agent for monitoring. It defaults to
provider.tags
- A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags.
provider.volumes
- A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
config.vm.synced_folder
- Supports both rsync__args and rsync__exclude, see the Vagrant Docs for more information. rsync__args default to
["--verbose", "--archive", "--delete", "-z", "--copy-links"]
and rsync__exclude defaults to[".vagrant/"]
.
- Supports both rsync__args and rsync__exclude, see the Vagrant Docs for more information. rsync__args default to
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
.
After creating your project's Vagrantfile
with the required configuration
attributes described above, you may create a new Droplet with the following
command:
$ vagrant up --provider=digital_ocean
This command will create a new Droplet, setup your SSH key for authentication, create a new user account, and run the provisioners you have configured.
Supported Commands
The provider supports the following Vagrant sub-commands:
vagrant destroy
- Destroys the Droplet instance.vagrant ssh
- Logs into the Droplet instance using the configured user account.vagrant halt
- Powers off the Droplet instance.vagrant provision
- Runs the configured provisioners and rsyncs any specifiedconfig.vm.synced_folder
.vagrant reload
- Reboots the Droplet instance.vagrant rebuild
- Destroys the Droplet instance and recreates it with the same IP address which was previously assigned.vagrant status
- Outputs the status (active, off, not created) for the Droplet instance.
This DigitalOcean API provider plugin for Vagrant has been tested with the following technology.
Date Tested | Vagrant Version | vagrant-digitalocean Version | Host (Workstation) Operating System | Guest (DigitalOcean) Operating System |
---|---|---|---|---|
03/12/2020 | 2.2.7 | 0.9.4 | OS X 10.14.6 | Ubuntu 18.04, Debian 10, Debian 9, Debian 8, CentOS 7 |
03/22/2016 | 1.8.1 | 0.7.10 | OS X 10.11.4 | CentOS 7.0 |
04/03/2013 | 1.1.5 | 0.1.0 | Ubuntu 12.04 | CentOS 6.3 |
Before submitting a GitHub issue, please ensure both Vagrant and vagrant-digitalocean are fully up-to-date.
-
For the latest Vagrant version, please visit the Vagrant website
-
To update Vagrant plugins, run the following command:
vagrant plugin update
-
vagrant plugin install vagrant-digitalocean
- Installation on OS X may not working due to a SSL certificate problem, and you may need to specify a certificate path explicitly. To do so, run
ruby -ropenssl -e "p OpenSSL::X509::DEFAULT_CERT_FILE"
. Then, add the following environment variable to your.bash_profile
script andsource
it:export SSL_CERT_FILE=/usr/local/etc/openssl/cert.pem
.
- Installation on OS X may not working due to a SSL certificate problem, and you may need to specify a certificate path explicitly. To do so, run
- The Chef provisioner is no longer supported by default (as of 0.2.0). Please use the
vagrant-omnibus
plugin to install Chef on Vagrant-managed machines. This plugin provides control over the specific version of Chef to install.
To contribute, fork then clone the repository, and then the following:
Developing
- Install RVM
- If using MacOS, follow these OpenSSL instructions
- Use Ruby v3.0.0
rvm use 3.0.0
- Run
bundle install
Testing
- Build and package your newly developed code:
rake gem:build
- Then install the packaged plugin:
vagrant plugin install pkg/vagrant-digitalocean-*.gem
- Once you're done testing, roll-back to the latest released version:
vagrant plugin uninstall vagrant-digitalocean
vagrant plugin install vagrant-digitalocean
- Once you're satisfied developing and testing your new code, please submit a pull request for review.
Releasing
To release a new version of vagrant-digitalocean you will need to do the following:
(only contributors of the GitHub repo and owners of the project at RubyGems will have rights to do this)
- First, bump, commit, and push the version in ~/lib/vagrant-digitalocean/version.rb:
- Follow Semantic Versioning.
- Then, create a matching GitHub Release (this will also create a tag):
- Preface the version number with a
v
. - https://github.com/devopsgroup-io/vagrant-digitalocean/releases
- Preface the version number with a
- You will then need to build and push the new gem to RubyGems:
rake gem:build
gem push pkg/vagrant-digitalocean-0.7.6.gem
- Then, when John Doe runs the following, they will receive the updated vagrant-digitalocean plugin:
vagrant plugin update
vagrant plugin update vagrant-digitalocean