droplet

Generated on 23 May 2025 from digitalocean.cloud version v1.2.1

Synopsis

Creates or deletes Droplets. View the create API documentation at https://docs.digitalocean.com/reference/api/api-reference/#operation/droplets_create.

Requirements

  • pydo >= 0.1.3
  • azure-core >= 1.26.1

Parameters

Parameter Choices / Default Description
backups
bool
A boolean indicating whether automated backups should be enabled for the Droplet.
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.
droplet_id
int
The Droplet ID which can be used for state=absent when there are more than one Droplet with the same name within the same region
image
str
The image ID of a public or private image or the slug identifier for a public image. This image will be the base image for your Droplet.
ipv6
bool
A boolean indicating whether to enable IPv6 on the Droplet.
module_override_options
dict
Module override options (developer use). Can be used to override module options to support experimental or future options. If provided, these options will knock out existing options.
monitoring
bool
A boolean indicating whether to install the DigitalOcean agent for monitoring.
name
str
The human-readable string you wish to use when displaying the Droplet name. The name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. The name set during creation will also determine the hostname for the Droplet in its internal configuration.
region
str
The slug identifier for the region that you wish to deploy the Droplet in. If the specific datacenter is not important, a slug prefix (e.g. nyc) can be used to deploy the Droplet in any of the that region’s locations (nyc1, nyc2, or nyc3). If the region is omitted from the create request completely, the Droplet may deploy in any region.
resize
bool
Resize the Droplet to a larger size if size is larger than the current size. If a permanent resize with disk changes included is desired, set the resize_disk attribute to true.
resize_disk
bool
Resize the Droplet to a larger size if size is larger than the current size. If a permanent resize with disk changes included is desired, set this attribute to true.
size
str
The slug identifier for the size that you wish to select for this Droplet. Required if state=present. If resize is set to true, this will be the new size of the Droplet. If resize_disk is also set to true, this will be the new size of the Droplet disk.
ssh_keys
list / elements=str
An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet’s root account upon creation.
state
str
Choices:
  • present (default)
  • absent
State of the resource, present to create, absent to destroy.
tags
list / elements=str
A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags.
timeout
int
Default: 300 Polling timeout in seconds.
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
unique_name
bool
When true for state=present the Droplet will only be created if it is uniquely named in the region and the region is specified. When true for state=absent the Droplet will only be destroyed if it is uniquely named in the region and the region is specified.
user_data
str
A string containing ‘user data’ which may be used to configure the Droplet on first boot, often a ‘cloud-config’ file or Bash script. It must be plain text and may not exceed 64 KiB in size.
volumes
list / elements=str
An array of IDs for block storage volumes that will be attached to the Droplet once created. The volumes must not already be attached to an existing Droplet.
vpc_uuid
str
A string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, the Droplet will be assigned to your account’s default VPC for the region.
with_droplet_agent
bool
A boolean indicating whether to install the DigitalOcean agent used for providing access to the Droplet web console in the control panel. By default, the agent is installed on new Droplets but installation errors (i.e. OS not supported) are ignored. To prevent it from being installed, set to false. To make installation errors fatal, explicitly set it to true.

Examples

- name: Create Droplet
  digitalocean.cloud.droplet:
    token: "{{ token }}"
    state: present
    name: example.com
    region: nyc3
    size: s-1vcpu-1gb
    image: ubuntu-20-04-x64

Return Values

KeyReturnedDescription
droplet
dict
always Droplet information.
Sample:
{
  "droplet": {
    "backup_ids": [],
    "created_at": "2020-07-21T18:37:44Z",
    "disk": 25,
    "features": [
      "backups",
      "private_networking",
      "ipv6",
      "monitoring"
    ],
    "id": 3164444,
    "image": {
      "created_at": "2020-05-15T05:47:50Z",
      "description": "",
      "distribution": "Ubuntu",
      "error_message": "",
      "id": 63663980,
      "min_disk_size": 20,
      "name": "20.04 (LTS) x64",
      "public": true,
      "regions": [
        "ams2",
        "ams3",
        "blr1",
        "fra1",
        "lon1",
        "nyc1",
        "nyc2",
        "nyc3",
        "sfo1",
        "sfo2",
        "sfo3",
        "sgp1",
        "tor1"
      ],
      "size_gigabytes": 2.36,
      "slug": "ubuntu-20-04-x64",
      "status": "available",
      "tags": [],
      "type": "snapshot"
    },
    "kernel": null,
    "locked": false,
    "memory": 1024,
    "name": "example.com",
    "networks": {
      "v4": [],
      "v6": []
    },
    "next_backup_window": null,
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "name": "New York 3",
      "sizes": [
        "s-1vcpu-1gb",
        "s-1vcpu-2gb",
        "s-1vcpu-3gb",
        "s-2vcpu-2gb",
        "s-3vcpu-1gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-24vcpu-128gb",
        "s-32vcpu-192g"
      ],
      "slug": "nyc3"
    },
    "size": {
      "available": true,
      "description": "Basic",
      "disk": 25,
      "memory": 1024,
      "price_hourly": 0.00743999984115362,
      "price_monthly": 5,
      "regions": [
        "ams2",
        "ams3",
        "blr1",
        "fra1",
        "lon1",
        "nyc1",
        "nyc2",
        "nyc3",
        "sfo1",
        "sfo2",
        "sfo3",
        "sgp1",
        "tor1"
      ],
      "slug": "s-1vcpu-1gb",
      "transfer": 1,
      "vcpus": 1
    },
    "size_slug": "s-1vcpu-1gb",
    "snapshot_ids": [],
    "status": "new",
    "tags": [
      "web",
      "env:prod"
    ],
    "vcpus": 1,
    "volume_ids": []
  },
  "links": {
    "actions": [
      {
        "href": "https://api.digitalocean.com/v2/actions/7515",
        "id": 7515,
        "rel": "create"
      }
    ]
  }
}
error
dict
failure DigitalOcean API error.
Sample:
{
  "Message": "Informational error message.",
  "Reason": "Unauthorized",
  "Status Code": 401
}
msg
str
always Droplet result information.
Sample:
[
  "Created Droplet example.com (11223344) in nyc3",
  "Created Droplet example.com (11223344) in nyc3 is not 'active', it is 'new'",
  "Deleted Droplet example.com (11223344) in nyc3",
  "Deleting Droplet example.com (11223344) in nyc3 has failed",
  "Droplet example.com in nyc3 would be created",
  "Droplet example.com (11223344) in nyc3 exists",
  "There are currently 2 Droplets named example.com in nyc3: 11223344, 55667788",
  "Droplet example.com in nyc3 would be created",
  "Droplet example.com not found",
  "Droplet example.com (11223344) in nyc3 would be deleted",
  "Must provide droplet_id when deleting Droplets without unique_name",
  "Droplet with ID 11223344 not found",
  "Droplet with ID 11223344 would be deleted"
]

We can't find any results for your search.

Try using different keywords or simplifying your search terms.