droplets

Creates, updates, deletes, gets or lists a droplets resource.

Overview

Name	droplets
Type	Resource
Id	digitalocean.compute.droplets

Fields

The following fields are returned by SELECT queries:

droplets_get

The response will be a JSON object with a key called droplet. This will be
set to a JSON object that contains the standard Droplet attributes.

Name	Datatype	Description
id	integer	A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
name	string	The human-readable name set for the Droplet instance. (example: example.com)
backup_ids	array	An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. Requires image:read scope.
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the Droplet was created. (example: 2020-07-21T18:37:44Z)
disk	integer	The size of the Droplet's disk in gigabytes.
disk_info	array	An array of objects containing information about the disks available to the Droplet.
features	array	An array of features enabled on this Droplet.
gpu_info	object	An object containing information about the GPU capabilities of Droplets created with this size.
image	object	The Droplet's image. Requires image:read scope.
kernel	object	Note: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to null. The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
locked	boolean	A boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory	integer	Memory of the Droplet in megabytes.
networks	object	The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
next_backup_window	object	The details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
region	object
size	object
size_slug	string	The unique slug identifier for the size of this Droplet. (example: s-1vcpu-1gb)
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the Droplet instance. Requires image:read scope.
status	string	A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". (example: active)
tags	array	An array of Tags the Droplet has been tagged with. Requires tag:read scope.
vcpus	integer	The number of virtual CPUs.
volume_ids	array	A flat array including the unique identifier for each Block Storage volume attached to the Droplet. Requires block_storage:read scope.
vpc_uuid	string	A string specifying the UUID of the VPC to which the Droplet is assigned. Requires vpc:read scope. (example: 760e09ef-dc84-11e8-981e-3cfdfeaae000)

droplets_list

A JSON object with a key of droplets.

Name	Datatype	Description
id	integer	A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
name	string	The human-readable name set for the Droplet instance. (example: example.com)
backup_ids	array	An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. Requires image:read scope.
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the Droplet was created. (example: 2020-07-21T18:37:44Z)
disk	integer	The size of the Droplet's disk in gigabytes.
disk_info	array	An array of objects containing information about the disks available to the Droplet.
features	array	An array of features enabled on this Droplet.
gpu_info	object	An object containing information about the GPU capabilities of Droplets created with this size.
image	object	The Droplet's image. Requires image:read scope.
kernel	object	Note: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to null. The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
locked	boolean	A boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory	integer	Memory of the Droplet in megabytes.
networks	object	The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
next_backup_window	object	The details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
region	object
size	object
size_slug	string	The unique slug identifier for the size of this Droplet. (example: s-1vcpu-1gb)
snapshot_ids	array	An array of snapshot IDs of any snapshots created from the Droplet instance. Requires image:read scope.
status	string	A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". (example: active)
tags	array	An array of Tags the Droplet has been tagged with. Requires tag:read scope.
vcpus	integer	The number of virtual CPUs.
volume_ids	array	A flat array including the unique identifier for each Block Storage volume attached to the Droplet. Requires block_storage:read scope.
vpc_uuid	string	A string specifying the UUID of the VPC to which the Droplet is assigned. Requires vpc:read scope. (example: 760e09ef-dc84-11e8-981e-3cfdfeaae000)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
droplets_get	select	droplet_id		To show information about an individual Droplet, send a GET request to /v2/droplets/$DROPLET_ID.
droplets_list	select		per_page, page, tag_name, name, type	To list all Droplets in your account, send a GET request to /v2/droplets. The response body will be a JSON object with a key of droplets. This will be set to an array containing objects each representing a Droplet. These will contain the standard Droplet attributes. ### Filtering Results by Tag It's possible to request filtered results by including certain query parameters. To only list Droplets assigned to a specific tag, include the tag_name query parameter set to the name of the tag in your GET request. For example, /v2/droplets?tag_name=$TAG_NAME. ### GPU Droplets By default, only non-GPU Droplets are returned. To list only GPU Droplets, set the type query parameter to gpus. For example, /v2/droplets?type=gpus.
droplets_create	insert	data__name		To create a new Droplet, send a POST request to /v2/droplets setting the required attributes. A Droplet will be created using the provided information. The response body will contain a JSON object with a key called droplet. The value will be an object containing the standard attributes for your new Droplet. The response code, 202 Accepted, does not indicate the success or failure of the operation, just that the request has been accepted for processing. The actions returned as part of the response's links object can be used to check the status of the Droplet create event. ### Create Multiple Droplets Creating multiple Droplets is very similar to creating a single Droplet. Instead of sending name as a string, send names as an array of strings. A Droplet will be created for each name you send using the associated information. Up to ten Droplets may be created this way at a time. Rather than returning a single Droplet, the response body will contain a JSON array with a key called droplets. This will be set to an array of JSON objects, each of which will contain the standard Droplet attributes. The response code, 202 Accepted, does not indicate the success or failure of any operation, just that the request has been accepted for processing. The array of actions returned as part of the response's links object can be used to check the status of each individual Droplet create event.
droplets_destroy	delete	droplet_id		To delete a Droplet, send a DELETE request to /v2/droplets/$DROPLET_ID. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
droplets_destroy_by_tag	delete	tag_name		To delete all Droplets assigned to a specific tag, include the tag_name query parameter set to the name of the tag in your DELETE request. For example, /v2/droplets?tag_name=$TAG_NAME. This endpoint requires tag:read scope. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
droplet_id	integer	A unique identifier for a Droplet instance. (example: 3164444)
tag_name	string	Specifies Droplets to be deleted by tag. (example: env:test)
name	string	Used to filter list response by Droplet name returning only exact matches. It is case-insensitive and can not be combined with tag_name. (example: web-01)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)
tag_name	string	Used to filter Droplets by a specific tag. Can not be combined with name or type. Requires tag:read scope. (example: env:prod)
type	string	When type is set to gpus, only GPU Droplets will be returned. By default, only non-GPU Droplets are returned. Can not be combined with tag_name. (example: droplets)

SELECT examples

droplets_get

To show information about an individual Droplet, send a GET request to
/v2/droplets/$DROPLET_ID.

SELECT
id,
name,
backup_ids,
created_at,
disk,
disk_info,
features,
gpu_info,
image,
kernel,
locked,
memory,
networks,
next_backup_window,
region,
size,
size_slug,
snapshot_ids,
status,
tags,
vcpus,
volume_ids,
vpc_uuid
FROM digitalocean.compute.droplets
WHERE droplet_id = '{{ droplet_id }}' -- required
;

droplets_list

To list all Droplets in your account, send a GET request to /v2/droplets.

The response body will be a JSON object with a key of droplets. This will be
set to an array containing objects each representing a Droplet. These will
contain the standard Droplet attributes.

### Filtering Results by Tag

It's possible to request filtered results by including certain query parameters.
To only list Droplets assigned to a specific tag, include the tag_name query
parameter set to the name of the tag in your GET request. For example,
/v2/droplets?tag_name=$TAG_NAME.

### GPU Droplets

By default, only non-GPU Droplets are returned. To list only GPU Droplets, set
the type query parameter to gpus. For example, /v2/droplets?type=gpus.

SELECT
id,
name,
backup_ids,
created_at,
disk,
disk_info,
features,
gpu_info,
image,
kernel,
locked,
memory,
networks,
next_backup_window,
region,
size,
size_slug,
snapshot_ids,
status,
tags,
vcpus,
volume_ids,
vpc_uuid
FROM digitalocean.compute.droplets
WHERE per_page = '{{ per_page }}'
AND page = '{{ page }}'
AND tag_name = '{{ tag_name }}'
AND name = '{{ name }}'
AND type = '{{ type }}'
;

INSERT examples

droplets_create

To create a new Droplet, send a POST request to /v2/droplets setting the
required attributes.

A Droplet will be created using the provided information. The response body
will contain a JSON object with a key called droplet. The value will be an
object containing the standard attributes for your new Droplet. The response
code, 202 Accepted, does not indicate the success or failure of the operation,
just that the request has been accepted for processing. The actions returned
as part of the response's links object can be used to check the status
of the Droplet create event.

### Create Multiple Droplets

Creating multiple Droplets is very similar to creating a single Droplet.
Instead of sending name as a string, send names as an array of strings. A
Droplet will be created for each name you send using the associated
information. Up to ten Droplets may be created this way at a time.

Rather than returning a single Droplet, the response body will contain a JSON
array with a key called droplets. This will be set to an array of JSON
objects, each of which will contain the standard Droplet attributes. The
response code, 202 Accepted, does not indicate the success or failure of any
operation, just that the request has been accepted for processing. The array
of actions returned as part of the response's links object can be used to
check the status of each individual Droplet create event.

INSERT INTO digitalocean.compute.droplets (
data__name,
data__region,
data__size,
data__image,
data__ssh_keys,
data__backups,
data__backup_policy,
data__ipv6,
data__monitoring,
data__tags,
data__user_data,
data__private_networking,
data__volumes,
data__vpc_uuid,
data__with_droplet_agent
)
SELECT 
'{{ name }}' /* required */,
'{{ region }}',
'{{ size }}',
'{{ image }}',
'{{ ssh_keys }}',
{{ backups }},
'{{ backup_policy }}',
{{ ipv6 }},
{{ monitoring }},
'{{ tags }}',
'{{ user_data }}',
{{ private_networking }},
'{{ volumes }}',
'{{ vpc_uuid }}',
{{ with_droplet_agent }}
;

Manifest

# Description fields are for documentation purposes
- name: droplets
  props:
    - name: name
      value: string
      description: >
        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.
        
    - name: region
      value: string
      description: >
        The slug identifier for the region that you wish to deploy the Droplet in. If the specific datacenter is not 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.
        
    - name: size
      value: string
      description: >
        The slug identifier for the size that you wish to select for this Droplet.
        
    - name: image
      value: string
      description: >
        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.<br>Requires `image:read` scope.
        
    - name: ssh_keys
      value: array
      description: >
        An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation. You must add the keys to your team before they can be embedded on a Droplet.<br>Requires `ssh_key:read` scope.
        
      default: 
    - name: backups
      value: boolean
      description: >
        A boolean indicating whether automated backups should be enabled for the Droplet.
        
      default: false
    - name: backup_policy
      value: object
      description: >
        An object specifying the backup policy for the Droplet. If omitted and `backups` is `true`, the backup plan will default to daily.
        
    - name: ipv6
      value: boolean
      description: >
        A boolean indicating whether to enable IPv6 on the Droplet.
        
      default: false
    - name: monitoring
      value: boolean
      description: >
        A boolean indicating whether to install the DigitalOcean agent for monitoring.
        
      default: false
    - name: tags
      value: array
      description: >
        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.<br>Requires `tag:create` scope.
        
      default: 
    - name: user_data
      value: string
      description: >
        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.
        
    - name: private_networking
      value: boolean
      description: >
        This parameter has been deprecated. Use `vpc_uuid` instead to specify a VPC network for the Droplet. If no `vpc_uuid` is provided, the Droplet will be placed in your account's default VPC for the region.
        
      default: false
    - name: volumes
      value: array
      description: >
        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.<br>Requires `block_storage:read` scpoe.
        
      default: 
    - name: vpc_uuid
      value: string
      description: >
        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.<br>Requires `vpc:read` scope.
        
    - name: with_droplet_agent
      value: boolean
      description: >
        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`.
        

DELETE examples

droplets_destroy

To delete a Droplet, send a DELETE request to /v2/droplets/$DROPLET_ID.

A successful request will receive a 204 status code with no body in response.
This indicates that the request was processed successfully.

DELETE FROM digitalocean.compute.droplets
WHERE droplet_id = '{{ droplet_id }}' --required
;

droplets_destroy_by_tag

To delete all Droplets assigned to a specific tag, include the tag_name
query parameter set to the name of the tag in your DELETE request. For
example, /v2/droplets?tag_name=$TAG_NAME.

This endpoint requires tag:read scope.

A successful request will receive a 204 status code with no body in response.
This indicates that the request was processed successfully.

DELETE FROM digitalocean.compute.droplets
WHERE tag_name = '{{ tag_name }}' --required
;