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.

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

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:

account_info

Show information about the current user account

balance_info

Retrieve the balances on a customer’s account

billing_history_info

Retrieve a list of all billing history entries

cdn_endpoints

Manage CDN endpoints

cdn_endpoints_info

List all of the CDN endpoints available on your account

certificate

Manage certificates

certificates_info

List all of the certificates available on your account

container_registry_info

Get information about your container registry

database_cluster

Create or delete database clusters

database_clusters_info

List all of the database clusters on your account

domain

Manage domains

domain_record

Manage domain records

domain_records_info

Retrieve a listing of all of the domain records for a domain

domains_info

Retrieve a list of all of the domains in your account

droplet

Create or delete Droplets

droplet_action_power

Set power states of a Droplet

droplet_action_resize

Resize a Droplet

droplet_action_snapshot

Take a snapshot of a Droplet

droplets_info

List all Droplets in your account

firewall

Create or delete firewalls

firewalls_info

List all firewalls on your account

images_info

List all of the images available on your account

kubernetes_cluster

Create or delete Kubernetes clusters

kubernetes_clusters_info

Retrieve a list of all of the Kubernetes clusters in your account

load_balancer

Create or delete load balancers

load_balancers_info

Retrieve a list of all of the load balancers in your account

monitoring_alert_policies_info

Returns all alert policies that are configured for the given account

monitoring_alert_policy

Create or delete monitoring alert policy

one_click

Install Kubernetes 1-Click applications

one_clicks_info

List all available 1-Click applications

project

Create or delete projects

project_resources_info

Retrieve a list of all of the project resources in your account

projects_info

Retrieve a list of all of the projects in your account

regions_info

List all of the regions that are available

reserved_ip

Create or delete reserved IPs

reserved_ips_info

List all reserved IPs on your account

sizes_info

List all of available Droplet sizes

snapshot

Delete snapshots

snapshots_info

Retrieve a list of all of the snapshots in your account

space

Manage Spaces

spaces_info

List all of the Spaces in your account

ssh_key

Create or delete SSH keys

ssh_keys_info

List all of the keys in your account

tag

Create or delete tags

tags_info

List all of the tags on your account

uptime_check

Create or delete Uptime checks

uptime_checks_info

List all of the Uptime checks on your account

uptime_checks_state_info

Get the state of an Uptime check

volume

Create or delete volumes

volume_action

Attach or detach volumes from Droplets

volume_snapshot

Create or delete volume snapshots

volumes_info

List all of the block storage volumes available on your account

vpc

Create or delete VPCs

vpcs_info

List all of the VPCs on your account

Inventory Plugin Reference

The following inventory plugins are also available:

droplets

Droplets dynamic inventory plugin