Images
An image contains the software packages that will be available on newly-provisioned instance. In the case of hardware virtual machines, the image also includes the operating system.
ListImages (GET /:login/images)
Provides a list of images available in this datacenter.
Note: Currently, Docker images are not included in this endpoint's responses. You must use docker images
against the docker service for this datacenter.
Inputs
The following optional query parameters are available to filter the list of images:
Field
Type
Description
name
String
The "friendly" name for this image
os
String
The underlying operating system for this image
version
String
The version for this image
public
Boolean
Filter public/private images
state
String
owner
String
Filter on owner UUID
type
String
Filter on image type. The types changed in v8.0.0
Returns
An array of images. Image objects include the following fields:
Field
Type
Description
id
UUID
Unique id for this image
name
String
The "friendly" name for this image
os
String
The underlying operating system for this image
version
String
The version for this image
type
String
What kind of image this is. The values differ after v8.0.0+
requirements
Object
Contains a grouping of various minimum requirements for provisioning an instance with this image. For example 'password' indicates that a password must be provided
requirements.max_ram
String
Indicates the maximum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.max_memory
String
Indicates the maximum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.min_ram
String
Indicates the minimum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.min_memory
String
Indicates the minimum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.brand
String
Indicates which brand has to be used in the VM manifest to provision a VM based on this image.
homepage
String
The URL for a web page with more detailed information for this image
files
Array
An array of image files that make up each image. Currently only a single file per image is supported
files[0].compression
String
The type of file compression used for the image file. One of 'bzip2', 'gzip', 'none'
files[0].sha1
String
SHA-1 hex digest of the file content. Used for corruption checking
files[0].size
Number
File size in bytes
published_at
ISO8859 date
The time this image has been made publicly available
owner
String
The UUID of the user who owns this image
public
Boolean
Indicates if this image is publicly available
state
String
The current state of the image. One of 'active', 'unactivated', 'disabled', 'creating', 'failed'
tags
Object
An object of key/value pairs that allows clients to categorize images by any given criteria
eula
String
URL of the End User License Agreement (EULA) for the image
acl
Array
Access Control List. An array of account UUIDs given access to a private image. The field is only relevant to private images.
error
Object
error.code
String
error.message
String
A short description of the image creation failure
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If login
does not exist
CLI Command
or
Example Request
Example Response
GetImage (GET /:login/images/:id)
Gets an individual image by id
.
Inputs
None
Returns
Field
Type
Description
id
UUID
Unique id for this image
name
String
The "friendly" name for this image
os
String
The underlying operating system for this image
version
String
The version for this image
type
String
What kind of image this is. The values differ after v8.0.0+
requirements
Object
Contains a grouping of various minimum requirements for provisioning an instance with this image. For example 'password' indicates that a password must be provided
requirements.max_ram
String
Indicates the maximum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.max_memory
String
Indicates the maximum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.min_ram
String
Indicates the minimum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.min_memory
String
Indicates the minimum RAM requirement that must be provided in the VM manifest to provision a VM based on this image.
requirements.brand
String
Indicates which brand has to be used in the VM manifest to provision a VM based on this image.
homepage
String
The URL for a web page with more detailed information for this image
files
Array
An array of image files that make up each image. Currently only a single file per image is supported
files[0].compression
String
The type of file compression used for the image file. One of 'bzip2', 'gzip', 'none'
files[0].sha1
String
SHA-1 hex digest of the file content. Used for corruption checking
files[0].size
Number
File size in bytes
published_at
ISO8859 date
The time this image has been made publicly available
owner
String
The UUID of the user who owns this image
public
Boolean
Indicates if this image is publicly available
state
String
The current state of the image. One of 'active', 'unactivated', 'disabled', 'creating', 'failed'
tags
Object
An object of key/value pairs that allows clients to categorize images by any given criteria
eula
String
URL of the End User License Agreement (EULA) for the image
acl
Array
Access Control List. An array of account UUIDs given access to a private image. The field is only relevant to private images.
error
Object
error.code
String
error.message
String
A short description of the image creation failure
Possible error.code
values:
error.code
Details
PrepareImageDidNotRun
VmHasNoOrigin
Origin image data could not be found for the instance. Typically this is for an instance migrated before image creation support was added
NotSupported
Indicates an error due to functionality that isn't currently supported. One example is that custom image creation of an instance based on a custom image isn't currently supported
InternalError
A catch-all error for unexpected or internal errors
Errors
For all possible errors, see CloudAPI HTTP Responses.
CLI Command
or
Example Request
Example Response
DeleteImage (DELETE /:login/images/:id)
Delete an image. Caller must be the owner of the image to delete it.
Inputs
None
Returns
Responds with HTTP 204 'No Content'.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login
or :id
does not exist
CLI Command
or
Example Request
Example Response
ExportImage (POST /:login/images/:id?action=export)
Exports an image to the specified Manta path. Caller must be the owner of the image, and the correspondent Manta path prefix, in order to export it. Both the image manifest and the image file will be exported, and their filenames will default to the following format when the specified manta path is a directory:
Where NAME is the image name and VER is the image version. FILE-EXT is the file extension of the image file. As an example, exporting a foo-1.0.0 image to /user/stor/cloudapi would result in the following files being exported:
By contrast, if the basename of the given prefix is not a directory, then "MANTA_PATH.imgmanifest" and "MANTA_PATH.zfs[.EXT]" are created. As an example, the following shows how to export foo-1.0.0 with a custom name:
Inputs
Field
Type
Description
manta_path
String
Manta path prefix used when exporting the image
Returns
A Manta location response object. It provides the properties that allow a CloudAPI user to retrieve the image file and manifest from Manta: manta_url, image_path, manifest_path.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login
or :id
does not exist
CLI Command
Example Request
Example Response
CreateImageFromMachine (POST /:login/images)
Create a new custom image from an instance. The typical process is:
Customize an instance the way you want it.
Call this endpoint (CreateImageFromMachine) to create a new image.
Repeat from step 1 if more customizations are desired with different images.
Use the new image(s) for provisioning via CreateMachine.
Inputs
All inputs except machine
are image manifest fields as defined by the IMGAPI docs. Note that not all fields listed there can be specified here.
Field
Type
Required?
Description
machine
UUID
Yes
The prepared and stopped instance UUID from which the image is to be created
name
String
Yes
version
String
Yes
description
String
No
homepage
String
No
eula
String
No
acl
String
No
tags
String
No
Returns
Field
Type
Description
id
UUID
Unique id for this image
name
String
The "friendly" name for this image
os
String
The underlying operating system for this image
version
String
The version for this image
type
String
What kind of image this is. The values differ after v8.0.0+
requirements
Object
Contains a grouping of various minimum requirements for provisioning an instance with this image. For example 'password' indicates that a password must be provided
homepage
String
The URL for a web page with more detailed information for this image
files
Array
An array of image files that make up each image. Currently only a single file per image is supported
files[0].compression
String
The type of file compression used for the image file. One of 'bzip2', 'gzip', 'none'
files[0].sha1
String
SHA-1 hex digest of the file content. Used for corruption checking
files[0].size
Number
File size in bytes
published_at
ISO8859 date
The time this image has been made publicly available
owner
String
The UUID of the user who owns this image
public
Boolean
Indicates if this image is publicly available
state
String
The current state of the image. One of 'active', 'unactivated', 'disabled', 'creating', 'failed'
tags
Object
An object of key/value pairs that allows clients to categorize images by any given criteria
eula
String
URL of the End User License Agreement (EULA) for the image
acl
Array
Access Control List. An array of account UUIDs given access to a private image. The field is only relevant to private images
Errors
For general errors, see CloudAPI HTTP Responses. Some typical and specific errors for this endpoint:
Error Code
Description
InsufficientServerVersionError
The machine
given is running on a server that is too old
NotAvailable
Typically this indicates that image creation is not supported for the OS of the given hardware virtual machine
Example CLI Command
or
Example HTTP Request
Example HTTP Response
ImportImageFromDatacenter (POST /:login/images?action=import-from-datacenter)
This will copy the image with id
from the source datacenter
into this datacenter. The copied image will retain all fields (e.g. id
, published_at
) as the original image. All incremental images in the origin chain will also be copied.
You can use triton datacenters to view the list of datacenter names in the current cloud.
Inputs
The following query parameters are required, these parameters will be used to identify the image to be copied.
Field
Type
Description
datacenter
String
The datacenter name from where the image will be copied from.
id
UUID
The id of the image to be copied.
Returns
On success, an Image object is returned. See GetImage for the fields that are returned in the image object.
Errors
For general errors, see CloudAPI HTTP Responses. Some typical and specific errors for this endpoint:
Error Code
Description
ImageUuidAlreadyExistsError
The image with id
already exists in this datacenter.
UnauthorizedError
If the source image is owned by the admin.
OriginIsNotActiveError
If one of the incremental (origin) images is not activated.
Example CLI Command
Example HTTP Request
Example HTTP Response
UpdateImage (POST /:login/images/:id?action=update)
Updates metadata about an image.
Inputs
Only the image attributes listed below can be updated.
Field
Type
Description
name
String
version
String
description
String
homepage
String
eula
String
acl
String
tags
String
Returns
An updated image object.
Field
Type
Description
id
UUID
Unique id for this image
name
String
The "friendly" name for this image
os
String
The underlying operating system for this image
version
String
The version for this image
type
String
What kind of image this is. The values differ after v8.0.0+
requirements
Object
Contains a grouping of various minimum requirements for provisioning an instance with this image. For example 'password' indicates that a password must be provided
homepage
String
The URL for a web page with more detailed information for this image
files
Array
An array of image files that make up each image. Currently only a single file per image is supported
files[0].compression
String
The type of file compression used for the image file. One of 'bzip2', 'gzip', 'none'
files[0].sha1
String
SHA-1 hex digest of the file content. Used for corruption checking
files[0].size
Number
File size in bytes
published_at
ISO8859 date
The time this image has been made publicly available
owner
String
The UUID of the user who owns this image
public
Boolean
Indicates if this image is publicly available
state
String
The current state of the image. One of 'active', 'unactivated', 'disabled', 'creating', 'failed'
tags
Object
An object of key/value pairs that allows clients to categorize images by any given criteria
eula
String
URL of the End User License Agreement (EULA) for the image
acl
Array
Access Control List. An array of account UUIDs given access to a private image. The field is only relevant to private images
Errors
For general errors, see CloudAPI HTTP Responses. Some typical and specific errors for this endpoint:
Error Code
Description
ResourceNotFound
If :login
or :id
does not exist
Example CLI Command
Example HTTP Request
Example HTTP Response
CloneImage (POST /:login/images/:id?action=clone)
Creates an independent copy of the source image. The login
account must be on the source image ACL to be able to make an image clone.
The resulting cloned image will have the same properties as the source image, but the cloned image will have a different id, it will be owned by the login
account and the image will have an empty ACL.
All incremental images in the image origin chain that are not operator images (i.e. are not owned by admin) will also be cloned, though all cloned incremental images will have state disabled
so that they are not visible in the default image listings.
Inputs
None.
Returns
A cloned image object. See GetImage docs for the image fields returned.
Errors
For general errors, see CloudAPI HTTP Responses. Some typical and specific errors for this endpoint:
Error Code
Description
ResourceNotFound
If :login
or :id
does not exist.
NotImageOwnerError
If your account is not the owner of the image.
ImageNotShared
When the given image is not shared with your account.
Example CLI Command
Example HTTP Request
Example HTTP Response
Last updated