Give Feedback

droplets

Generated on 16 Feb 2026 from digitalocean.cloud version v1.2.1

Synopsis

Droplets dynamic inventory plugin.

Parameters

Parameter	Choices / Defaults	Configuration	Comments
`api_filters` dict			Server-side API filters to limit droplets fetched from the DigitalOcean API. Reduces API response size and improves performance for large infrastructures. Applied before droplets are retrieved, minimizing network transfer and processing time.
`name` str Suboption of `api_filters`			Filter droplets by name. Matches droplets with this exact name.
`tag_name` str Suboption of `api_filters`			Filter droplets by tag name. Only droplets with this exact tag will be returned.
`attributes` list / elements=str			Droplet attributes to include as host variables. Consult the API documentation https://docs.digitalocean.com/reference/api/api-reference/#operation/droplets_create for attribute examples. Note: The `tags` attribute will be automatically renamed to `do_tags` to avoidconflicting with Ansible's reserved `tags` variable used for task tagging.
`cache` bool		INI entries: `[inventory] cache = VALUE` Environment variables: `ANSIBLE_INVENTORY_CACHE`	Toggle to enable/disable the caching of the inventory's source data, requires a cache plugin setup to work.
`cache_connection` str		INI entries: `[defaults] fact_caching_connection = VALUE [inventory] cache_connection = VALUE` Environment variables: `ANSIBLE_CACHE_PLUGIN_CONNECTION` `ANSIBLE_INVENTORY_CACHE_CONNECTION`	Cache connection data or path, read cache plugin documentation for specifics.
`cache_plugin` str	Default: `memory`	INI entries: `[defaults] fact_caching = VALUE [inventory] cache_plugin = VALUE` Environment variables: `ANSIBLE_CACHE_PLUGIN` `ANSIBLE_INVENTORY_CACHE_PLUGIN`	Cache plugin to use for the inventory's source data.
`cache_prefix`	Default: `ansible_inventory_`	INI entries: `[defaults] fact_caching_prefix = VALUE [inventory] cache_prefix = VALUE` Environment variables: `ANSIBLE_CACHE_PLUGIN_PREFIX` `ANSIBLE_INVENTORY_CACHE_PLUGIN_PREFIX`	Prefix to use for cache plugin files/tables.
`cache_timeout` int	Default: `3600`	INI entries: `[defaults] fact_caching_timeout = VALUE [inventory] cache_timeout = VALUE` Environment variables: `ANSIBLE_CACHE_PLUGIN_TIMEOUT` `ANSIBLE_INVENTORY_CACHE_TIMEOUT`	Cache duration in seconds.
`client_override_options` dict			Client override options (developer use). For example, can be used to override the DigitalOcean API endpoint for an internal test suite. If provided, these options will knock out existing options.
`compose` dict			Create vars from jinja2 expressions.
`filters` list / elements=str			Client-side filters using Jinja2 templates. Applied after droplets are retrieved from the API. All filter expressions must evaluate to true for a host to be included. Use this for complex filtering logic not supported by API filters (e.g., region filtering).
`groups` dict			Add hosts to group based on Jinja2 conditionals.
`keyed_groups` list / elements=dict			Add hosts to group based on the values of a variable.
`default_value` str Suboption of `keyed_groups`			The default value when the host variable's value is `None` or an empty string. This option is mutually exclusive with `keyed_groups[].trailing_separator`.
`key` str Suboption of `keyed_groups`			The key from input dictionary used to generate groups.
`parent_group` str Suboption of `keyed_groups`			parent group for keyed group.
`prefix` str Suboption of `keyed_groups`			A keyed group name will start with this prefix.
`separator` str Suboption of `keyed_groups`	Default: `_`		separator used to build the keyed group name.
`trailing_separator` bool Suboption of `keyed_groups`	Default: `true`		Set this option to `false` to omit the `keyed_groups[].separator` after the host variable when the value is `None` or an empty string. This option is mutually exclusive with `keyed_groups[].default_value`.
`leading_separator` boolean	Default: `true`		Use in conjunction with `keyed_groups`. By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore. This is because the default prefix is `""` and the default separator is `"_"`. Set this option to `false` to omit the leading underscore (or other separator) if no prefix is given. If the group name is derived from a mapping the separator is still used to concatenate the items. To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
`plugin` required	Choices: `digitalocean.cloud.droplets`		The name of the this inventory plugin `digitalocean.cloud.droplets`.
`strict` bool			If `yes` make invalid entries a fatal error, otherwise skip and continue. Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
`token` str			DigitalOcean API token. There are several environment variables which can be used to provide this value. `DIGITALOCEAN_ACCESS_TOKEN`, `DIGITALOCEAN_TOKEN`, `DO_API_TOKEN`, `DO_API_KEY`, `DO_OAUTH_TOKEN` and `OAUTH_TOKEN`
`use_extra_vars` bool		INI entries: `[inventory_plugins] use_extra_vars = VALUE` Environment variables: `ANSIBLE_INVENTORY_USE_EXTRA_VARS`	Merge extra vars into the available variables for composition (highest precedence).

Examples

# Basic example with caching
plugin: digitalocean.cloud.droplets
cache: true
cache_plugin: ansible.builtin.jsonfile
cache_connection: /tmp/digitalocean_droplets_inventory
cache_timeout: 300
#
#  By default, this plugin will consult the following environment variables for the API token:
#  DIGITALOCEAN_ACCESS_TOKEN, DIGITALOCEAN_TOKEN, DO_API_TOKEN, DO_API_KEY, DO_OAUTH_TOKEN, OAUTH_TOKEN
#
#  The API token can also be set statically (but please, avoid committing secrets):
#  token: example-password
#
#  Or, lookup plugins can be used:
#  token: "{{ lookup('ansible.builtin.pipe', '/script/which/echoes/token.sh') }}"
#  token: "{{ lookup('ansible.builtin.env', 'MY_DO_TOKEN') }}"
#
attributes:
  - id
  - memory
  - vcpus
  - disk
  - locked
  - status
  - kernel
  - created_at
  - features
  - backup_ids
  - next_backup_window
  - snapshot_ids
  - image
  - volume_ids
  - size
  - size_slug
  - networks
  - region
  - tags  # Note: Will be available as 'do_tags' to avoid Ansible reserved name
  - vpc_uuid
compose:
  ansible_host: networks.v4 | selectattr("type", "eq", "public") | map(attribute="ip_address") | first
  class: size.description | lower
  distribution: image.distribution | lower
keyed_groups:
  - key: image.slug | default("null", true)
    prefix: image
    separator: "_"
  - key: do_tags  # Use 'do_tags' instead of 'tags' to avoid Ansible reserved variable name
    prefix: tag
    separator: "_"
  - key: region.slug
    prefix: region
    separator: "_"
  - key: status
    prefix: status
    separator: "_"
  - key: vpc_uuid
    prefix: vpc
groups:
  basic: "'basic' in class"
  ubuntu: "'ubuntu' in distribution"

# Example with API-level filtering (server-side)
# This reduces API response size and improves performance
# plugin: digitalocean.cloud.droplets
# api_filters:
#   tag_name: staging  # Only fetch droplets with 'staging' tag
# attributes:
#   - region
#   - tags
#   - status

# Example with client-side filtering (Jinja2 templates)
# Applied after droplets are retrieved from the API
# plugin: digitalocean.cloud.droplets
# attributes:
#   - region
#   - tags
#   - status
# filters:
#   - 'region.slug == "ams3"'  # Only include droplets in AMS3 region
#   - 'status == "active"'      # Only include active droplets

# Example with two-tier filtering (API + client-side)
# Most efficient: API filter reduces network load, client filter adds precision
# plugin: digitalocean.cloud.droplets
# api_filters:
#   tag_name: staging  # API filter: only fetch staging droplets
# attributes:
#   - region
#   - tags
#   - status
#   - networks
# filters:
#   - 'region.slug == "ams3"'  # Client filter: only AMS3 region
#   - '"staging" in do_tags'    # Client filter: verify staging tag
# compose:
#   ansible_host: networks.v4 | selectattr("type", "eq", "public") | map(attribute="ip_address") | first
# keyed_groups:
#   - key: region.slug
#     prefix: region

droplets

Synopsis

Parameters

Examples

We can't find any results for your search.