For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

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: