The DigitalOcean Ansible Collection (digitalocean.cloud
) is a rewrite of the community.digitalocean
Ansible collection using the pydo Python library.
Use this collection to manage DigitalOcean infrastructure.
The source code for the digitalocean.cloud
collection is on GitHub at digitalocean/ansible-collection
.
This collection requires three external Python modules: azure-core
, boto3
(for Spaces modules), and pydo
. Install the requirements at the correct versions using pip3
:
pip3 install --user azure-core==1.26.1 boto3==1.28.53 pydo==0.1.7
If you use Poetry, there is also a pyproject.toml
in the digitalocean.cloud
repository.
Before using this collection, install it with the Ansible Galaxy command-line tool:
ansible-galaxy collection install digitalocean.cloud
You can also include it in a requirements.yml
file and install it with ansible-galaxy collection install -r requirements.yml
, using the format:
---
collections:
- name: digitalocean.cloud
If you install the collection from Ansible Galaxy, it is not upgraded automatically when you upgrade the ansible
package. To upgrade the collection to the latest available version, run ansible-galaxy collection install digitalocean.cloud --upgrade
.
You can also install a specific version of the collection, like if you need to downgrade when something is broken in the latest version. For example, to install version 0.5.0
, run ansible-galaxy collection install digitalocean.cloud:==0.5.0
.
See Using Ansible collections for more details.
There are sample playbooks in the playbooks directory of the GitHub repository.
Most modules require authentication, so set the $DIGITALOCEAN_TOKEN
environment variable. We recommend this over using the token
module parameter because token
stores your API token in plaintext within your playbook.
Modules which create, update, or destroy resources in the cloud require an API token with write
permission. Read How to Create a Personal Access Token for more information on API tokens.
This is a sample playbook which returns your DigitalOcean account information:
---
- name: Account info
hosts: localhost
connection: local
gather_facts: false
tasks:
- name: Get account information
digitalocean.cloud.account_info:
Name this playbook file account_info.yml
and run it with ansible-playbook
:
ANSIBLE_STDOUT_CALLBACK=yaml ansible-playbook -i localhost, -c local account_info.yml -v
The output returns your account information:
No config file found; using defaults
PLAY [Account info] **********************************************************************************************
TASK [Get account information] ***********************************************************************************
ok: [localhost] => changed=false
account:
droplet_limit: 25
email: [email protected]
email_verified: true
floating_ip_limit: 1
name: Sammy Shark
reserved_ip_limit: 1
status: active
status_message: ''
team:
name: Sharks
uuid: 3281ad4a-0092-4e6b-abd2-c7a7ed111503
uuid: eab13a8a-99e3-4ffd-a587-b8a7789f0090
volume_limit: 1
msg: Current account information
PLAY RECAP *******************************************************************************************************
localhost : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
This playbook registers an SSH key from the user’s ~/.ssh
directory, then provisions a Droplet with it:
---
- name: Create SSH key and Droplet
hosts: localhost
connection: local
gather_facts: true
vars:
digitalocean_token: "{{ lookup('ansible.builtin.env', 'DIGITALOCEAN_TOKEN') }}"
public_key: "{{ lookup('ansible.builtin.file', ansible_env['HOME'] ~ '/.ssh/sammy.key.pub') }}"
tasks:
- name: Create SSH key
digitalocean.cloud.ssh_key:
state: present
token: "{{ digitalocean_token }}"
public_key: "{{ public_key }}"
name: "sammy"
register: ssh_key
- name: Create Droplet
digitalocean.cloud.droplet:
state: present
token: "{{ digitalocean_token }}"
name: sammy-droplet
region: nyc3
size: s-1vcpu-2gb
image: ubuntu-22-04-x64
ssh_keys: ["{{ ssh_key.ssh_key.id }}"]
unique_name: true
digitalocean.cloud.droplet
module’s unique_name
parameter.Replace /.ssh/sammy.key.pub
in the playbook with the path to an existing key in your ~/.ssh
directory, then run the playbook using ansible-playbook
:
ansible-playbook -i localhost, -c local droplet.yml -v
Ansible prints status updates as it completes each task, similar to the following:
No config file found; using defaults
PLAY [Create SSH key and Droplet] *********************************************************************************
TASK [Gathering Facts] ********************************************************************************************
ok: [localhost]
TASK [Create SSH key] *********************************************************************************************
changed: [localhost] => {"changed": true, "msg": "Created SSH key sammy (ce:1a:f2:41:4d:b8:16:11:d8:1e:22:07:aa:8f:47:b8)", "ssh_key": {"fingerprint": "ce:1a:f2:41:4d:b8:16:11:d8:1e:22:07:aa:8f:47:b8", "id": 41495416, "name": "sammy", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID8m+rcGxqanY8X2/569vMI+YnzEt+eOyIEcEH0nvsWo sammy@host"}}
TASK [Create Droplet] *********************************************************************************************
changed: [localhost] => {"changed": true, "droplet": {"backup_ids": [], "created_at": "2024-04-03T16:29:10Z"
. . .
"status": "active", "tags": [], "vcpus": 1, "volume_ids": []}, "msg": "Created Droplet sammy-droplet (410720588) in nyc3"}
PLAY RECAP ********************************************************************************************************
localhost : ok=3 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
When the playbook run is complete, your DigitalOcean account has a sammy
SSH key and a sammy-droplet
Droplet. Destroy the Droplet when you are done to avoid unexpected charges.
The digitalocean.cloud
collection provides the following modules:
The following inventory plugins are also available: