search

ansible-collections / community.digitalocean

This Ansible collection contains modules for assisting in the automation of the DigitalOcean cloud.
https://galaxy.ansible.com/community/digitalocean/
GNU General Public License v3.0
141 stars 57 forks source link
ansible-collection digitalocean hacktoberfest

readme

DigitalOcean Community Collection

coverage black integration sanity unit

This collection contains modules and plugins to assist in automating DigitalOcean infrastructure and API interactions with Ansible.

Communication

For more information about communication, see the Ansible communication guide.

Included content

Installation and Usage

Requirements

The collection is tested and supported with:

Installing the Collection from Ansible Galaxy

Before using the DigitalOcean collection, you need to install it with the Ansible Galaxy CLI:

ansible-galaxy collection install community.digitalocean

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: community.digitalocean

Using modules from the DigitalOcean Collection in your playbooks

It's preferable to use content in this collection using their Fully Qualified Collection Namespace (FQCN), for example community.digitalocean.digital_ocean_droplet:

---
- hosts: localhost
  gather_facts: false
  connection: local

  vars:
    oauth_token: "{{ lookup('ansible.builtin.env', 'DO_API_TOKEN') }}"

  # You can also default the value of a variable for every DO module using module_defaults
  # module_defaults:
  #   group/community.digitalocean.all:
  #     oauth_token: "{{ lookup('ansible.builtin.env', 'DO_API_TOKEN') }}"

  tasks:
    - name: Create SSH key
      community.digitalocean.digital_ocean_sshkey:
        oauth_token: "{{ oauth_token }}"
        name: mykey
        ssh_pub_key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example"
        state: present
      register: my_ssh_key

    - name: Create a new Droplet
      community.digitalocean.digital_ocean_droplet:
        oauth_token: "{{ oauth_token }}"
        state: present
        name: mydroplet
        unique_name: true
        size: s-1vcpu-1gb
        region: sfo3
        image: ubuntu-20-04-x64
        wait_timeout: 500
        ssh_keys:
          - "{{ my_ssh_key.data.ssh_key.id }}"
      register: my_droplet

    - name: Show Droplet info
      ansible.builtin.debug:
        msg: |
          Droplet ID is {{ my_droplet.data.droplet.id }}
          First Public IPv4 is {{ (my_droplet.data.droplet.networks.v4 | selectattr('type', 'equalto', 'public')).0.ip_address | default('<none>', true) }}
          First Private IPv4 is {{ (my_droplet.data.droplet.networks.v4 | selectattr('type', 'equalto', 'private')).0.ip_address | default('<none>', true) }}

    - name: Tag a resource; creating the tag if it does not exist
      community.digitalocean.digital_ocean_tag:
        oauth_token: "{{ oauth_token }}"
        name: "{{ item }}"
        resource_id: "{{ my_droplet.data.droplet.id }}"
        state: present
      loop:
        - staging
        - dbserver

If upgrading older playbooks which were built prior to Ansible 2.10 and this collection's existence, you can also define collections in your play and refer to this collection's modules as you did in Ansible 2.9 and below, as in this example:

---
- hosts: localhost
  gather_facts: false
  connection: local

  collections:
    - community.digitalocean

  tasks:
    - name: Create ssh key
      digital_ocean_sshkey:
        oauth_token: "{{ oauth_token }}"
        ...

Testing and Development

If you want to develop new content for this collection or improve what's already here, the easiest way to work on the collection is to clone it into one of the configured COLLECTIONS_PATHS, and work on it there.

Alternatively, to develop completely out of ~/src/ansible-dev, one could:

mkdir -p ~/src/ansible-dev
cd ~/src/ansible-dev
python3 -m venv venv
source venv/bin/activate
git clone https://github.com/ansible/ansible.git
pip install --requirement ansible/requirements.txt
pip install kubernetes
source ansible/hacking/env-setup
export ANSIBLE_COLLECTIONS_PATHS="~/src/ansible-dev/ansible_collections"
ansible-galaxy collection install community.digitalocean community.general

This gives us a self-contained environment in ~/src/ansible-dev consisting of Python, Ansible, and this collection (located in ~/src/ansible-dev/ansible_collections/community/digitalocean). This collection requires functionality from community.general, and as such, we install it as well.

If you would like to contribute any changes which you have made to the collection, you will have to push them to your fork. If you do not have a fork yet, you can create one here. Once you have a fork:

cd ~/src/ansible-dev/ansible_collections/community/digitalocean
git remote add origin git@github.com:{your fork organization}/community.digitalocean.git
git checkout -b my-awesome-fixes
git commit -am "My awesome fixes"
git push -u origin my-awesome-fixes

Now, you should be ready to create a Pull Request.

Testing with ansible-test

The tests directory inside the collection root contains configuration for running unit, sanity, and integration tests using ansible-test.

You can run the collection's test suites with the commands:

ansible-test units --venv --python 3.9
ansible-test sanity --venv --python 3.9
ansible-test integration --venv --python 3.9

Replace --venv with --docker if you'd like to use Docker for the testing runtime environment.

Note: To run integration tests, you must add an tests/integration/integration_config.yml file with a valid DigitalOcean API Key (variable do_api_key), AWS Access ID and Secret Key (variables aws_access_key_id and aws_secret_access_key, respectively). The AWS variables are used for the DigitalOcean Spaces and CDN Endpoints integration tests.

Release notes

See the changelog.

Release process

Releases are automatically built and pushed to Ansible Galaxy for any new tag. Before tagging a release, make sure to do the following:

  1. Update galaxy.yml and this README's requirements.yml example with the new version for the collection. Make sure all new modules have references above.
  2. Update the CHANGELOG:
    1. Make sure you have antsibull-changelog installed.
    2. Make sure there are fragments for all known changes in changelogs/fragments.
    3. Run antsibull-changelog release.
    4. Don't forget to add new folks to galaxy.yml.
  3. Commit the changes and create a PR with the changes. Wait for tests to pass, then merge it once they have.
  4. Tag the version in Git and push to GitHub.
    1. Determine the next version (collections follow semver semantics) by listing tags or looking at the releases.
    2. List tags with git tag --list
    3. Create a new tag with git tag 1.2.3
    4. Push tags upstream with git push upstream --tags

After the version is published, verify it exists on the DigitalOcean Collection Galaxy page.

More information

Licensing

GNU General Public License v3.0 or later.

See COPYING to see the full text.