DigitalOcean Ansible Collection Reference

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.

External Dependencies

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.

Install the Collection from Ansible Galaxy

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.

Using this Collection

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.

Warning
Running sample Ansible playbooks can create real DigitalOcean infrastructure that are billed to your account. Clean up excess resources to avoid unexpected charges.

Account Info Playbook

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

Droplet Creation Playbook

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
Note
The DigitalOcean platform does not require Droplet names to be unique. This functionality is enforced by the 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.

Module Reference

The digitalocean.cloud collection provides the following modules:

Show information about the current user account
Retrieve the balances on a customer’s account
Retrieve a list of all billing history entries
Manage CDN endpoints
List all of the CDN endpoints available on your account
Manage certificates
List all of the certificates available on your account
Get information about your container registry
Create or delete database clusters
List all of the database clusters on your account
Manage domains
Manage domain records
Retrieve a listing of all of the domain records for a domain
Retrieve a list of all of the domains in your account
Create or delete Droplets
Set power states of a Droplet
Resize a Droplet
Take a snapshot of a Droplet
List all Droplets in your account
Create or delete firewalls
List all firewalls on your account
List all of the images available on your account
Create or delete Kubernetes clusters
Retrieve a list of all of the Kubernetes clusters in your account
Create or delete load balancers
Retrieve a list of all of the load balancers in your account
Returns all alert policies that are configured for the given account
Create or delete monitoring alert policy
Install Kubernetes 1-Click applications
List all available 1-Click applications
Create or delete projects
Retrieve a list of all of the project resources in your account
Retrieve a list of all of the projects in your account
List all of the regions that are available
Create or delete reserved IPs
List all reserved IPs on your account
List all of available Droplet sizes
Delete snapshots
Retrieve a list of all of the snapshots in your account
Manage Spaces
List all of the Spaces in your account
Create or delete SSH keys
List all of the keys in your account
tag
Create or delete tags
List all of the tags on your account
Create or delete Uptime checks
List all of the Uptime checks on your account
Get the state of an Uptime check
Create or delete volumes
Attach or detach volumes from Droplets
Create or delete volume snapshots
List all of the block storage volumes available on your account
vpc
Create or delete VPCs
List all of the VPCs on your account

Inventory Plugin Reference

The following inventory plugins are also available:

Droplets dynamic inventory plugin
In this article...