images

Creates, updates, deletes, gets or lists an images resource.

Overview

Name	images
Type	Resource
Id	digitalocean.compute.images

Fields

The following fields are returned by SELECT queries:

images_get

The response will be a JSON object with a key called image. The value of this will be an image object containing the standard image attributes.

Name	Datatype	Description
id	integer	A unique number that can be used to identify and reference a specific image.
name	string	The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. (example: Nifty New Snapshot)
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the image was created. (example: 2020-05-04T22:23:02Z)
description	string	An optional free-form text field to describe an image. (example: )
distribution	string	The name of a custom image's distribution. Currently, the valid values are Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, and Unknown. Any other value will be accepted but ignored, and Unknown will be used in its place. (example: Ubuntu)
error_message	string	A string containing information about errors that may occur when importing a custom image. (example: )
min_disk_size	integer	The minimum disk size in GB required for a Droplet to use this image.
public	boolean	This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account.
regions	array	This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values.
size_gigabytes	number (float)	The size of the image in gigabytes.
slug	string	A uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id. (example: nifty1)
status	string	A status string indicating the state of a custom image. This may be NEW, available, pending, deleted, or retired. (example: NEW)
tags	array	A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. Requires tag:create scope.
type	string	Describes the kind of image. It may be one of base, snapshot, backup, custom, or admin. Respectively, this specifies whether an image is a DigitalOcean base OS image, user-generated Droplet snapshot, automatically created Droplet backup, user-provided virtual machine image, or an image used for DigitalOcean managed resources (e.g. DOKS worker nodes). (example: snapshot)

images_list

The response will be a JSON object with a key called images. This will be set to an array of image objects, each of which will contain the standard image attributes.

Name	Datatype	Description
id	integer	A unique number that can be used to identify and reference a specific image.
name	string	The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. (example: Nifty New Snapshot)
created_at	string (date-time)	A time value given in ISO8601 combined date and time format that represents when the image was created. (example: 2020-05-04T22:23:02Z)
description	string	An optional free-form text field to describe an image. (example: )
distribution	string	The name of a custom image's distribution. Currently, the valid values are Arch Linux, CentOS, CoreOS, Debian, Fedora, Fedora Atomic, FreeBSD, Gentoo, openSUSE, RancherOS, Rocky Linux, Ubuntu, and Unknown. Any other value will be accepted but ignored, and Unknown will be used in its place. (example: Ubuntu)
error_message	string	A string containing information about errors that may occur when importing a custom image. (example: )
min_disk_size	integer	The minimum disk size in GB required for a Droplet to use this image.
public	boolean	This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account.
regions	array	This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values.
size_gigabytes	number (float)	The size of the image in gigabytes.
slug	string	A uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id. (example: nifty1)
status	string	A status string indicating the state of a custom image. This may be NEW, available, pending, deleted, or retired. (example: NEW)
tags	array	A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. Requires tag:create scope.
type	string	Describes the kind of image. It may be one of base, snapshot, backup, custom, or admin. Respectively, this specifies whether an image is a DigitalOcean base OS image, user-generated Droplet snapshot, automatically created Droplet backup, user-provided virtual machine image, or an image used for DigitalOcean managed resources (e.g. DOKS worker nodes). (example: snapshot)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
images_get	select	image_id		To retrieve information about an image, send a GET request to /v2/images/$IDENTIFIER.
images_list	select		type, private, tag_name, per_page, page	To list all of the images available on your account, send a GET request to /v2/images. ## Filtering Results ----- It's possible to request filtered results by including certain query parameters. Image Type Either 1-Click Application or OS Distribution images can be filtered by using the type query parameter. > Important: The type query parameter does not directly relate to the type attribute. To retrieve only distribution images, include the type query parameter set to distribution, /v2/images?type=distribution. To retrieve only application images, include the type query parameter set to application, /v2/images?type=application. User Images To retrieve only the private images of a user, include the private query parameter set to true, /v2/images?private=true. Tags To list all images 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/images?tag_name=$TAG_NAME.
images_create_custom	insert	data__name, data__url, data__region		To create a new custom image, send a POST request to /v2/images. The body must contain a url attribute pointing to a Linux virtual machine image to be imported into DigitalOcean. The image must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.
images_update	replace	image_id		To update an image, send a PUT request to /v2/images/$IMAGE_ID. Set the name attribute to the new value you would like to use. For custom images, the description and distribution attributes may also be updated.
images_delete	delete	image_id		To delete a snapshot or custom image, send a DELETE request to /v2/images/$IMAGE_ID.

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
image_id	integer	A unique number that can be used to identify and reference a specific image. (example: 62137902)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)
private	boolean	Used to filter only user images. (example: true)
tag_name	string	Used to filter images by a specific tag. (example: base-image)
type	string	Filters results based on image type which can be either application or distribution. (example: distribution)

SELECT examples

images_get

To retrieve information about an image, send a GET request to
/v2/images/$IDENTIFIER.

SELECT
id,
name,
created_at,
description,
distribution,
error_message,
min_disk_size,
public,
regions,
size_gigabytes,
slug,
status,
tags,
type
FROM digitalocean.compute.images
WHERE image_id = '{{ image_id }}' -- required;

images_list

To list all of the images available on your account, send a GET request to /v2/images.

## Filtering Results
-----

It's possible to request filtered results by including certain query parameters.

Image Type

Either 1-Click Application or OS Distribution images can be filtered by using the type query parameter.

> Important: The type query parameter does not directly relate to the type attribute.

To retrieve only distribution images, include the type query parameter set to distribution, /v2/images?type=distribution.

To retrieve only application images, include the type query parameter set to application, /v2/images?type=application.

User Images

To retrieve only the private images of a user, include the private query parameter set to true, /v2/images?private=true.

Tags

To list all images 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/images?tag_name=$TAG_NAME.

SELECT
id,
name,
created_at,
description,
distribution,
error_message,
min_disk_size,
public,
regions,
size_gigabytes,
slug,
status,
tags,
type
FROM digitalocean.compute.images
WHERE type = '{{ type }}'
AND private = '{{ private }}'
AND tag_name = '{{ tag_name }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}';

INSERT examples

images_create_custom

To create a new custom image, send a POST request to /v2/images.
The body must contain a url attribute pointing to a Linux virtual machine
image to be imported into DigitalOcean.
The image must be in the raw, qcow2, vhdx, vdi, or vmdk format.
It may be compressed using gzip or bzip2 and must be smaller than 100 GB after
being decompressed.

INSERT INTO digitalocean.compute.images (
data__name,
data__distribution,
data__description,
data__url,
data__region,
data__tags
)
SELECT 
'{{ name }}' --required,
'{{ distribution }}',
'{{ description }}',
'{{ url }}' --required,
'{{ region }}' --required,
'{{ tags }}'
RETURNING
image
;

Manifest

# Description fields are for documentation purposes
- name: images
  props:
    - name: name
      value: string
      description: >
        The display name that has been given to an image.  This is what is shown in the control panel and is generally a descriptive title for the image in question.
        
    - name: distribution
      value: string
      description: >
        The name of a custom image's distribution. Currently, the valid values are  `Arch Linux`, `CentOS`, `CoreOS`, `Debian`, `Fedora`, `Fedora Atomic`,  `FreeBSD`, `Gentoo`, `openSUSE`, `RancherOS`, `Rocky Linux`, `Ubuntu`, and `Unknown`.  Any other value will be accepted but ignored, and `Unknown` will be used in its place.
        
      valid_values: ['Arch Linux', 'CentOS', 'CoreOS', 'Debian', 'Fedora', 'Fedora Atomic', 'FreeBSD', 'Gentoo', 'openSUSE', 'RancherOS', 'Rocky Linux', 'Ubuntu', 'Unknown']
    - name: description
      value: string
      description: >
        An optional free-form text field to describe an image.
        
    - name: url
      value: string
      description: >
        A URL from which the custom Linux virtual machine image may be retrieved.  The image it points to must be in the raw, qcow2, vhdx, vdi, or vmdk format.  It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.
        
    - name: region
      value: string
      description: >
        The slug identifier for the region where the resource will initially be  available.
        
      valid_values: ['ams1', 'ams2', 'ams3', 'blr1', 'fra1', 'lon1', 'nyc1', 'nyc2', 'nyc3', 'sfo1', 'sfo2', 'sfo3', 'sgp1', 'tor1', 'syd1']
    - name: tags
      value: array
      description: >
        A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. <br><br>Requires `tag:create` scope.
        

REPLACE examples

images_update

To update an image, send a PUT request to /v2/images/$IMAGE_ID.
Set the name attribute to the new value you would like to use.
For custom images, the description and distribution attributes may also be updated.

REPLACE digitalocean.compute.images
SET 
data__name = '{{ name }}',
data__distribution = '{{ distribution }}',
data__description = '{{ description }}'
WHERE 
image_id = '{{ image_id }}' --required
RETURNING
image;

DELETE examples

images_delete

To delete a snapshot or custom image, send a DELETE request to /v2/images/$IMAGE_ID.

DELETE FROM digitalocean.compute.images
WHERE image_id = '{{ image_id }}' --required;