This article is deprecated and no longer maintained.
This article relies on a project, dopy, which is no longer maintained.
This article may still be useful as a reference, but may not work or follow best practices. We strongly recommend using a recent article written for the operating system you are using.
Ansible 2.0 provides support for version 2 of the DigitalOcean API, which means that you can use Ansible to not only provision your web applications, but also to provision and manage your Droplets automatically.
While DigitalOcean provides a simple web interface for setting up SSH keys and creating Droplets, it is a manual process that you need to go through each time you want to provision a new server. When your application expands to include a larger number of servers and needs the ability to grow and shrink on demand, you don’t want to have to deal with creating and configuring the application deployment scripts for each server by hand.
The benefit of using a provisioning tool like Ansible is that it allows you to completely automate this process, and initiating it is as simple as running a single command. This tutorial will show by example how to use Ansible’s support of the DigitalOcean API v2.
In particular, this tutorial will cover the process of setting up a new SSH key on a DO account and provisioning two different Droplets so they are ready to use for deploying your web applications. After following this tutorial, you’ll be able to modify and integrate these tasks into your existing application deployment scripts.
This tutorial builds on basic Ansible knowledge, so if you are new to Ansible, you can read this section of the Ansible installation tutorial first.
To follow this tutorial, you will need:
One Ubuntu 16.04 Droplet with a sudo non-root user.
Ansible installed on your server, which you can set up by following this step from a previous Ansible tutorial.
A read and write Personal Access Token for the API. Make sure you write down the token in a safe place; you’ll need it later on in this tutorial.
In this step, we will configure Ansible to communicate with the DigitalOcean API.
Typically, Ansible just uses SSH to connect to different servers and run commands. This means that the configuration necessary start using Ansible is generally standard for all modules. However, because communicating with the DigitalOcean API is not simply an SSH shell command, we’ll need to do a little additional setup. The dopy
(DigitalOcean API Python Wrapper) Python module is what will allow Ansible to communicate with the API.
In order to install dopy
, first install the Python package manager pip
.
- sudo apt-get install python-pip
Then, install dopy
using pip
.
- sudo pip install dopy
Next, we’ll create a new directory to work in to keep things neat, and we’ll set up a basic Ansible configuration file.
By default, Ansible uses a hosts file located at /etc/ansible/hosts
, which contains all of the servers it is managing. While that file is fine for some use cases, it’s global. This is a global configuration, which is fine in some uses cases, but we’ll use a local hosts file in this tutorial. This way, we won’t accidentally break any existing configurations you might have while learning about and testing Ansible’s DO API support.
Create and move into a new directory, which we will use for the rest of this tutorial.
- mkdir ~/ansible-do-api
- cd ~/ansible-do-api/
When you run Ansible, it will look for an ansible.cfg
file in the directory where it is run, and if it finds one, it’ll apply those configuration settings. This means we can easily override options, such as the hostfile
option, for each individual use case.
Create a new file called ansible.cfg
and open it for editing using nano
or your favorite text editor.
- nano ansible.cfg
Paste the following into ansible.cfg
, then save and close the file.
[defaults]
hostfile = hosts
Setting the hostfile
option in the [defaults]
group tells Ansible to use a particular hosts file instead of the global one. This ansible.cfg
tells Ansible to look for a hostfile called hosts
in the same directory.
Next, we’ll create the hosts
file.
- nano hosts
Because we will only be dealing with the DigitalOcean API in this tutorial, we can tell Ansible to run on localhost
, which keeps things simple and will remove the need to connect to a remote host. This can be done by telling Ansible to use localhost
, and specifying the ansible_connection
as local
. Paste the code below into hosts
, then save and close the file.
[digitalocean]
localhost ansible_connection=local
Finally, we will use the API token created in the prerequisites to allow Ansible to communicate with the DigitalOcean API. There are three ways we can tell Ansible about the API token:
api_token
parameter.api_token
parameter.DO_API_TOKEN
or DO_API_KEY
.Option 1 is the most direct approach and may sound appealing if you do not wish to create variables. However, it means that the API token will need to be copied into each task it is being used for. More importantly, this means that if it ever changes, you’ll need to find all instances of it and replace them all.
Option 2 allows us to set the API token directly within our playbook, like option 1. Unlike option 1, we only define it in a single place by using a variable, which is more convenient and easier to update. We will be using option 2 for this tutorial because it is the simplest approach.
However, it’s worth nothing that option 3 is the best method to use to protect your API token because it makes it a lot harder for you to accidentally commit the API token into a repository (which might be shared with anyone). It allows the token to be configured on the system level, and to work across different playbooks without having to include the token in each.
Create a basic playbook called digitalocean.yml
.
- nano digitalocean.yml
Paste the following code into the file, making sure to substitute in your API token.
---
- hosts: digitalocean
vars:
do_token: your_API_token
tasks:
You can leave this file open in your editor as we’ll continue working with it in the next step.
In this step, we will create a new SSH key on your server and add it to your DigitalOcean account using Ansible.
The first thing we need to do is ensure the user has a SSH key pair, which we can push to DigitalOcean so it can be installed by default on your new Droplets. Although this is easy to do this via the command line, we can do it just as easily with the users module in Ansible. Using Ansible also has the benefit of ensuring the key exists before it is used, which can avoid issues when running the playbook on different hosts.
In your playbook, add in the user
task below, which we can use to ensure an SSH key exists, then save and close the file.
---
- hosts: digitalocean
vars:
do_token: your_API_token
tasks:
- name: ensure ssh key exists
user: >
name={{ ansible_user_id }}
generate_ssh_key=yes
ssh_key_file=.ssh/id_rsa
You can change the name of the key if you would like to use something other than ~/.ssh/id_rsa
.
Run your playbook.
- ansible-playbook digitalocean.yml
The output should look like this:
PLAY ***************************************************************************
TASK [setup] *******************************************************************
ok: [localhost]
TASK [ensure ssh key exists] ***************************************************
changed: [localhost]
PLAY RECAP *********************************************************************
localhost : ok=2 changed=1 unreachable=0 failed=0
When that has finished, you can manually verify the key exists by running:
- ls -la ~/.ssh/id_rsa*
It will list all files that match id_rsa*
. You should see id_rsa
and id_rsa.pub
listed, indicating that your SSH key exists.
Next, we’ll push the key into your DigitalOcean account, so open your playbook for editing again.
- nano digitalocean.yml
We’ll be using the digital_ocean Ansible module to upload your SSH key.We will also register the output of the task as the my_ssh_key
variable because we’ll need it for a later step.
Add the task to the bottom of the file, then save and close the file.
---
. . .
- name: ensure ssh key exists
user: >
name={{ ansible_user_id }}
generate_ssh_key=yes
ssh_key_file=.ssh/id_rsa
- name: ensure key exists at DigitalOcean
digital_ocean: >
state=present
command=ssh
name=my_ssh_key
ssh_pub_key={{ lookup('file', '~/.ssh/id_rsa.pub') }}
api_token={{ do_token }}
register: my_ssh_key
If you named your key something other than id_rsa
, make sure to update the name is the ssh_pub_key
line in this task.
We’re using a number of different options from the digital_ocean
module here:
present
, because we want the SSH key to be present in the account.ssh
, which allows us to manage the state of SSH keys within the account.do_token
, defined in the vars
section).Now, run your playbook.
- ansible-playbook digitalocean.yml
The output should look like this:
. . .
TASK [ensure key exists at digital ocean] **************************************
changed: [localhost]
PLAY RECAP *********************************************************************
localhost : ok=3 changed=1 unreachable=0 failed=0
When that has finished, you can manually check that your SSH key exists in your DigitalOcean account by going to the control panel, clicking Settings (from the gear menu), then Security (in the User category on the left sidebar). You should see your new key listed under SSH Keys.
In this step, we will create a new Droplet.
We briefly touched on the digital_ocean
module in Step 2. We will be using a different set of options for this module in this step:
; this time, we'll use it with
droplet` to manage Droplets via this module.present
.ubuntu-16-04-x64
.NYC3
.512mb
.There are many more options than just the ones that we are covering in this tutorial (all of which can be found on the Ansible documentation page), but using these options as a guide, we can write your new task.
Open your playbook for editing.
- nano digitalocean.yml
Update your playbook to with the new task highlighted in red below, then save and close the file. You can change options like size, region, and image to suit your application. The options below will create a 512MB Ubuntu 16.04 server named droplet-one using the SSH key we created in the previous step.
. . .
api_token={{ do_token }}
register: my_ssh_key
- name: ensure droplet one exists
digital_ocean: >
state=present
command=droplet
name=droplet-one
size_id=512mb
region_id=sgp1
image_id=ubuntu-16-04-x64
ssh_key_ids={{ my_ssh_key.ssh_key.id }}
api_token={{ do_token }}
register: droplet_one
- debug: msg="IP is {{ droplet_one.droplet.ip_address }}"
Note that we are using {{ my_ssh_key.ssh_key.id }}
to retrieve the ID of the previously set up SSH key and pass it into your new Droplet. This works if the SSH key is newly created or if it already exists.
Now, run your playbook. This will take a little longer to execute than it did previously because it will be creating a Droplet.
- ansible-playbook digitalocean.yml
The output should look like this:
. . .
TASK [ensure key exists at DigitalOcean] **************************************
ok: [localhost]
TASK [ensure droplet one exists] ******************************************************
changed: [localhost]
TASK [debug] *******************************************************************
ok: [localhost] => {
"msg": "IP is 111.111.111.111"
}
PLAY RECAP *********************************************************************
localhost : ok=5 changed=1 unreachable=0 failed=0
Ansible has provided us with the IP address of the new Droplet in the return message. To verify that it’s running, you can log into it directly using SSH.
- ssh root@111.111.111.111
This should connect you to your new server (using the SSH key we created on your Ansible server in step 2). You can then exit back to your Ansible server by pressing CTRL+D
.
In this step, we will discuss the concept of idempotence and how to relates to provisioning Droplets with Ansible.
Ansible aims to operate using the concept of idempotence. This means that you can run the same tasks multiple times, and changes should only be made when they are needed — which is usually the first time it’s run. This idea maps well to provisioning servers, installing packages, and other server administration.
If you run your playbook again (don’t do it yet!), given the current configuration, it will go ahead and provision a second Droplet also called droplet-one
. Run it again, and it will make a third Droplet. This is due to the fact that DigitalOcean allows multiple Droplets with the same name. To avoid this, we can use the unique_name
parameter.
The unique_name
parameter tells Ansible and DigitalOcean that you want unique hostnames for your servers. This means that when you run your playbook again, it will honor idempotence and consider the Droplet already provisioned, and therefore won’t create a second server with the same name.
Open your playbook for editing:
- nano digitalocean.yml
Add in the unique_name
parameter:
. . .
- name: ensure droplet one exists
digital_ocean: >
state=present
command=droplet
name=droplet-one
unique_name=yes
size_id=512mb
. . .
Save and run your playbook:
- ansible-playbook digitalocean.yml
The output should result in no changed tasks, but you will notice the debug output with the IP address is still displayed. If you check your DigitalOcean account, you will notice only a single droplet-one Droplet was provisioned.
In this step, we will replicate our existing configuration to provision a separate Droplet.
In order to provision a separate Droplet, all we need to do is replicate the Ansible task from our first Droplet. To make our playbook a little more robust, however, we will convert it to using a list of Droplets to provision, which allows us to easily scale out our fleet as required.
First, we need to define our list of Droplets.
Open your playbook for editing:
- nano digitalocean.yml
Add in a list of Droplet names to be provisioned in the vars
section.
---
- hosts: digitalocean
vars:
do_token: <digitalocean_token>
droplets:
- droplet-one
- droplet-two
tasks:
. . .
Next, we need to update our task to loop through the list of Droplets, check if they exist, and then save the results into a variable. Following that, we also need to modify our debug
tasks to output the information stored in the variable for each item.
To do this, update the ensure droplet one exists task in your playbook as below:
. . .
- name: ensure droplets exist
digital_ocean: >
state=present
command=droplet
name={{ item }}
unique_name=yes
size_id=512mb
region_id=sgp1
image_id=ubuntu-16-04-x64
ssh_key_ids={{ my_ssh_key.ssh_key.id }}
api_token={{ do_token }}
with_items: droplets
register: droplet_details
- debug: msg="IP is {{ item.droplet.ip_address }}"
with_items: droplet_details.results
Save and run your playbook.
- ansible-playbook digitalocean.yml
The results should look like this:
. . .
TASK [ensure droplets exists] **************************************************
ok: [localhost] => (item=droplet-one)
changed: [localhost] => (item=droplet-two)
TASK [debug] *******************************************************************
. . .
"msg": "IP is 111.111.111.111"
. . .
"msg": "IP is 222.222.222.222"
}
PLAY RECAP *********************************************************************
localhost : ok=5 changed=1 unreachable=0 failed=0
You might notice that the the debug
output has a lot more information in it than it did the first time. This is because the debug
module prints additional information for help with debugging; this is a small downside of using registered variables with this module.
Apart from that, you will see that our second Droplet has been provisioned, while our first was already running. You have now provisioned two DigitalOcean Droplets using only Ansible!
Deleting your Droplets is just as simple. The state parameter in the task tells Ansible what state the Droplet should be in. Setting it to present
ensures that the Droplet exists, and it will be created if it doesn’t already exist; setting it to absent
ensures the Droplet with the specified name not exist, and it will delete any Droplets matching the specified name (as long as unique_name
is set).
If you want to delete the two example Droplets you created in this tutorial, just change the state in the creation task to absent
and rerun your playbook.
. . .
- name: ensure droplets exist
digital_ocean: >
state=absent
command=droplet
. . .
You may also want to remove the debug line before you rerun your playbook. If you don’t, your Droplets will still be deleted, but you’ll see an error from the debug command (because there are no IP addresses to return).
- ansible-playbook digitalocean.yml
Now your two example Droplets will be deleted.
Ansible is an incredibly powerful and very flexible provisioning tool. You have seen how easy it is to provision (and deprovision) Droplets using the DigitalOcean API using only standard Ansible concepts and the built-in modules.
The state parameter, which was set to present
, tells Ansible what state the Droplet should be in. Setting it to present
ensures that the Droplet exists, and it will be created if it doesn’t already exist; setting it to absent
tells Ansible to ensure the Droplet with the specified name not exist, and it will delete any Droplets matching the specified name (as long as unique_name
is set).
As your number of Droplets you manage increases, the ability to automate the process will save you time in creating, setting up, and destroying Droplets as part of a automated process. You can adapt and expand the examples in this tutorial to improve your provisioning scripts custom to your setup.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.
Due to Ansible updates the configuration file should actually be
[defaults] inventory = hosts
instead of
[defaults] hostfile = hosts
Step 3 breaks badly for me; Ansible claims
dopy >= 0.3.2
isn’t installed even though I’ve explicitly, manuallyReferences:
ansible/ansible-modules-core#360
, where I describe my environment and describe having tried the workarounds discovered thus far;ansible/ansible-modules-core#2509
, titled Digital Ocean doesn’t work with dopy 0.3.7 (which is the current version);Any help would be greatly appreciated.
A curated slugs list of images, regions, etc. would be handy. I could not find any available list over DO docs, guides or api docs.
That deprecated notice at the top scares me away from trying this… Is there nothing more up-to-date?
Is it possible to use ansible or vagrant to update the DNS records when creating these droplets? I’d love to have a script that builds droplets and adds the hostname to an existing domain hosted with DigitalOcean.
This is a great great tutorial. Tremendous attention to detail. I really like this.
Is it possible to run through this tutorial without One Ubuntu 16.04 Droplet with a
sudo
non-root user.? I mean, if Ansible’s cntrol machine is NOT an Ansible droplet but is instead a local host (eg. desktop/server with Ubuntu desktop/server edition installed) then how does the tutorial change?In such a scenario, this concerns me (there may be other problems besides this): This can be done by telling Ansible to use
localhost
, and specifying theansible_connection
aslocal
.As an example, one specific question I have regarding such a run: Assuming
ansible.cfg
is unchanged, can this tutorial be run on the local host with the followinghosts
file:Would other changes be needed for running through this tutorial this from a local machine?
Very well described. Impressive support to manage droplets.
Curious, is there a way now to insert the new IP for the host into the Ansible hosts ini file, so future playbooks (not defined in the file) can start building up the droplet?
When I try step 5, I’m getting the following:
And it created a droplet named “droplets”. I have checked, double checked, and triple checked and I have it typed exactly the way the example shows.
Thanks in advance for any and all help! Jeff B.
This is a great writeup, sad to see it hasn’t had much love. I’m going to try out a few things on DO with ansible. What would be great is seeing a way to automate and cap the number of servers without manual intervention from Ansible. I Know DO has limits, it would be nice to see how ansible handles reaching those limits, or how one would raise the theoretical limit
Thanks for the write up, though looks like ansible is in transition of dumping dopy?https://github.com/ansible/ansible-modules-core/issues/4219