Instances
Triton supports three different types of instances:Docker containers. OS-virtualized instances managed through the Docker client.Infrastructure containers. More traditional OS-virtualized instances
Triton supports three different types of instances:
Docker containers. OS-virtualized instances managed through the Docker client.
Infrastructure containers. More traditional OS-virtualized instances running SmartOS or more Linux distributions.
Hardware-virtualized machines. Hardware-virtualized instances (KVM) for running legacy or special-purpose operating systems.
Infrastructure and Docker containers are lightweight, offering the most performance, observability and operational flexibility. Harware-virtualized machines are useful for non-SmartOS or non-Linux stacks.
ListMachines (GET /:login/machines)
Lists all instances we have on record for your account. If you have a large number of instances, you can filter using the input parameters listed below. Note that deleted instances are returned only if the instance history has not been purged from Triton.
You can paginate this API by passing in offset and limit. HTTP responses will contain the additional headers x-resource-count and x-query-limit. If x-resource-count is less than x-query-limit, you're done, otherwise call the API again with offset set to offset + limit to fetch additional instances.
Note that there is a HEAD /:login/machines form of this API, so you can retrieve the number of instances without retrieving a JSON describing the instances themselves.
Inputs
Field
Type
Description
type
String
(deprecated) The type of instance (virtualmachine or smartmachine)
brand
String
(v8.0+) The type of instance (e.g. lx)
name
String
Machine name to find (will make your list size 1, or 0 if nothing found)
image
String
Image id; returns instances provisioned with that image
state
String
The current state of the instance (e.g. running)
memory
Number
The current size of the RAM deployed for the instance (in MiB)
tombstone
Boolean
Include destroyed and failed instances available in instance history
limit
Number
Return a max of N instances; default is 1000 (which is also the maximum allowable result set size)
offset
Number
Get a limit number of instances starting at this offset
tag.$name
String
An arbitrary set of tags can be used for querying, assuming they are prefixed with "tag."
docker
Boolean
Whether to only list Docker instances, or only non-Docker instances, if present. Defaults to showing all instances.
credentials
Boolean
Whether to include the generated credentials for instances, if present. Defaults to false
Note that if the special input tags=* is provided, any other input will be completely ignored and the response will return all instances with any tag.
Be aware that in the case of instances created with vmadm directly (i.e. not through CloudAPI), ips, networks, primaryIp and package may be in a different format than expected. The ips array can contain the value "dhcp", not just IP strings, the networks array can contain null values for networks that CloudAPI was unable to determine (e.g. as a result of a "dhcp" IP), primaryIp too can have the value of "dhcp", and the package string can be empty instead of a UUID. Unless ops is bypassing CloudAPI and creating instances directly, it is unlikely you need concern yourself with this caveat.
Returns
An array of instance objects, which contain:
Field
Type
Description
id
UUID
Unique id for this instance
name
String
The "friendly" name for this instance
type
String
(deprecated) The type of instance (virtualmachine or smartmachine)
brand
String
(v8.0+) The type of instance (e.g. lx)
state
String
The current state of this instance (e.g. running)
image
String
The image id this instance was provisioned with
memory
Number
The amount of RAM this instance has (in MiB)
disk
Number
The amount of disk this instance has (in MiB)
disks
Array
An array of disk objects (bhyve)
metadata
Object[String => String]
Any additional metadata this instance has
tags
Object[String => String]
Any tags this instance has
created
ISO8601 date
When this instance was created
updated
ISO8601 date
When this instance's details was last updated
docker
Boolean
Whether this instance is a Docker container, if present
ips
Array[String]
The IP addresses this instance has
networks
Array[String]
The network UUIDs of the nics this instance has
primaryIp
String
The IP address of the primary NIC of this instance. The "primary" NIC is used to determine the default gateway for an instance. Commonly it is also on an external network (i.e. accessible on the public internet) and hence usable for SSH'ing into an instance, but not always. (Note: In future Triton versions it will be possible to have multiple IPv4 and IPv6 addresses on a particular NIC, at which point the current definition of primaryIp will be ambiguous and will need to change.)
firewall_enabled
Boolean
Whether firewall rules are enforced on this instance
deletion_protection
Boolean
compute_node
String
UUID of the server on which the instance is located
package
String
The id or name of the package used to create this instance
flexible
Boolean
Whether this instance uses the flexible disk space feature (bhyve)
free_space
Number
The amount of space (MiB) that is not allocated to disks nor in use by snapshots of those disks. If snapshots are present, writes to disks may reduce this value (bhyve)
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login does not exist
InvalidArgument
If one of the input parameters was invalid
CLI Command
Get all instance:
or
Get all LX instance:
or
Get all LX machines that are currently running:
or
Get all LX instances that are currently running, and have 256 MiB of memory:
or
Get all LX instances that are currently running, with 256 MiB of RAM, tagged as 'test':
Get all tagged instances:
Beware that depending on your shell you may need to escape the asterisk character. E.g. Bash requires it escaped.
The CLI has parameters that let you filter on most things in the API, and you can combine them. Run triton instance list --help or sdc-listmachines --help to see all the options.
Example Request
Example Response
GetMachine (GET /:login/machines/:id)
Gets the details for an individual instance.
Deleted instances are returned only if the instance history has not been purged from Triton.
Inputs
Field
Type
Description
credentials
Boolean
Whether to include the generated credentials for instances, if present. Defaults to false.
Returns
Field
Type
Description
id
UUID
Unique id for this instance
name
String
The "friendly" name for this instance
type
String
(deprecated) The type of instance (virtualmachine or smartmachine)
brand
String
(v8.0+) The type of instance (e.g. lx)
state
String
The current state of this instance (e.g. running)
image
String
The image id this instance was provisioned with
memory
Number
The amount of RAM this instance has (in MiB)
disk
Number
The amount of disk this instance has (in MiB)
disks
Array
An array of disk objects (bhyve)
metadata
Object[String => String]
Any additional metadata this instance has
tags
Object[String => String]
Any tags this instance has
created
ISO8601 date
When this instance was created
updated
ISO8601 date
When this instance's details was last updated
docker
Boolean
Whether this instance is a Docker container, if present
ips
Array[String]
The IP addresses this instance has
networks
Array[String]
The network UUIDs of the nics this instance has
primaryIp
String
The IP address of the primary NIC of this instance. The "primary" NIC is used to determine the default gateway for an instance. Commonly it is also on an external network (i.e. accessible on the public internet) and hence usable for SSH'ing into an instance, but not always. (Note: In future Triton versions it will be possible to have multiple IPv4 and IPv6 addresses on a particular NIC, at which point the current definition of primaryIp will be ambiguous and will need to change.)
firewall_enabled
Boolean
Whether firewall rules are enforced on this instance
compute_node
String
UUID of the server on which the instance is located
package
String
The id or name of the package used to create this instance
dns_names
Array[String]
flexible
Boolean
Whether this instance uses the flexible disk space feature (bhyve)
free_space
Number
The amount of space (MiB) that is not allocated to disks nor in use by snapshots of those disks. If snapshots are present, writes to disks may reduce this value (bhyve)
Be aware that in the case of instances created with vmadm directly (i.e. not through CloudAPI), ips, networks, primaryIp and package may be in a different format than expected. The ips array can contain the value "dhcp", not just IP strings, the networks array can contain null values for networks that CloudAPI was unable to determine (e.g. as a result of a "dhcp" IP), primaryIp too can have the value of "dhcp", and the package string can be empty instead of a UUID. Unless ops is bypassing CloudAPI and creating instances directly, it is unlikely you need concern yourself with this caveat.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
CLI Command
Get the details for the instance with id 75cfe125-a5ce-49e8-82ac-09aa31ffdf26:
or
Example Request
Example Response
CreateMachine (POST /:login/machines)
Allows you to provision an instance.
If you do not specify a name, CloudAPI will generate a random one for you. If you have enabled Triton CNS on your account, this name will also be used in DNS to refer to the new instance (and must therefore consist of DNS-safe characters only).
Your instance will initially be not available for login (Triton must provision and boot it); you can poll GetMachine for its status. When the state field is equal to running, you can log in. If the instance is a brand other than kvm or bhyve, you can usually use any of the SSH keys managed under the keys section of CloudAPI to login as any POSIX user on the OS. You can add/remove keys over time, and the instance will automatically work with that set.
If the the instance has a brand kvm or bhyve, and of a UNIX-derived OS (e.g. Linux), you must have keys uploaded before provisioning; that entire set of keys will be written out to /root/.ssh/authorized_keys in the new instance, and you can SSH in using one of those keys. Changing the keys over time under your account will not affect a running hardware virtual machine in any way; those keys are statically written at provisioning-time only, and you will need to manually manage them on the instance itself.
If the image you create an instance from is set to generate passwords for you, the username/password pairs will be returned in the metadata response as a nested object, like so:
You cannot overwrite the credentials key in CloudAPI.
More generally, the metadata keys can be set either at the time of instance creation, or after the fact. You must either pass in plain-string values, or a JSON-encoded string. On metadata retrieval, you will get a JSON object back.
Networks can be specified using the networks attribute. It is possible to have an instance attached to an internal network, external network or both. If the networks attribute is absent from the input, the instance will be attached to one externally-accessible network (i.e. assigned a public IP), and any one of internal/private networks. If the account owns or has access to multiple private networks, it will be important to include the desired network(s) in the request payload instead of letting the system assign the network automatically.
Be aware that CreateMachine does not return IP addresses or networks. To obtain the IP addresses and networks of a newly-provisioned instance, poll GetMachine until the instance state is running.
Typically, Triton will allocate the new instance somewhere reasonable within the cloud. See affinity rules below for options on controlling server placement of new instances.
When Triton CNS is enabled, the DNS search domain of the new VM will be automatically set to the suffix of the "instance" record that is created for that VM. For example, if the full CNS name of the new VM would be "foo.inst.35ad1ec4-2eab-11e6-ac02-8f56c66976a1.us-west-1.triton.zone", its automatic DNS search path would include "inst.35ad1ec4-2eab-11e6-ac02-8f56c66976a1.us-west-1.triton.zone". This can be changed later within the instance, if desired.
Inputs
Field
Type
Description
name
String
Friendly name for this instance; default is the first 8 characters of the machine id. If the name includes the string {{shortId}}, any instances of that tag within the name will be replaced by the first 8 characters of the machine id.
package
String
image
String
networks
Array
affinity
Array
locality
Object
metadata.$name
String
An arbitrary set of metadata key/value pairs can be set at provision time, but they must be prefixed with "metadata."
tag.$name
String
An arbitrary set of tags can be set at provision time, but they must be prefixed with "tag."
firewall_enabled
Boolean
Completely enable or disable firewall for this instance. Default is false
deletion_protection
Boolean
allow_shared_images
Boolean
Whether to allow provisioning from a shared image. Default is false
volumes
Array
A list of objects representing volumes to mount when the newly created machine boots
disks
Array
An array of disk objects to be created (bhyve)
volumes
The volumes input parameter allows users to specify a list of volumes to mount in the new machine when it boots:
"volumes": [ { "name": "volume-name-1", "type": "tritonnfs", "mode": "rw", "mountpoint": "/foo" }, { "name": "volume-name-2", "mode": "ro", "mountpoint": "/bar" } ]
Each object of the volumes array has the following layout:
Field
Type
Description
name
String
The name of the volume to mount
type
String
The type of the volume to mount (currently only "tritonnfs" is supported)
mode
String
Determines the read/write mode for the volume to mount. Accepted values are "ro" (for read-only) and "rw" (for read-write). The default value is "rw".
mountpoint
String
Specifies where the volume is mounted in the newly created machine's filesystem. It must start with a slash ("/") and it must contain at least one character that is not '/'.
disks
The disks input parameter allows users to specify a list of disks to be provisioned when creating a bhyve instance. This parameter can only be specified if the package has its flexible_disk attribute set to true. The sum of the sizes of the disks may be no greater than the package quota.
"disks": [ { "id": "eea4e223-dee6-44dc-a7e1-71f996e534f0", "boot": true }, { "id": "dea91a7f-5fe3-4408-b25a-994c97a7975e", "size": 512 }, { "id": "c41ce11e-bed2-45d2-bdb8-8dc889ed8ced", "size": "remaining" } ]
Each object of the disks array has the following layout
Field
Type
Description
id
UUID
Unique id for this disk
boot
Boolean
If true, this is the boot disk
image
UUID
The image from which the disk was created
size
Integer
The size of the disk in mebibytes or "remaining". If "remaining", size will be set to the difference between the package quota and sum of the other disks.
Returns
Field
Type
Description
id
UUID
Unique id for this instance
name
String
The "friendly" name for this instance
type
String
(deprecated) The type of instance (virtualmachine or smartmachine)
brand
String
(v8.0+) The type of instance (e.g. lx)
state
String
The current state of this instance (e.g. running)
memory
Number
The amount of RAM this instance has (in MiB)
disk
Number
The amount of disk this instance has (in MiB)
disks
Array
(v9.4.0+) One disk object per disk in the VM (bhyve only)
ips
Array[String]
The IP addresses this instance has
metadata
Object[String => String]
Any additional metadata this instance has
package
String
The id or name of the package used to create this instance
image
String
The image id this instance was provisioned with
docker
Boolean
Whether this instance is a Docker container, if present
flexible
Boolean
Whether this instance uses the flexible disk space feature (bhyve)
free_space
Number
The amount of space (MiB) that is not allocated to disks nor in use by snapshots of those disks. If snapshots are present, writes to disks may reduce this value (bhyve)
created
ISO8601 date
When this instance was created
updated
ISO8601 date
When this instance's details was last updated
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login does not exist
InsufficientCapacity
There isn't enough capacity in this datacenter
InvalidArgument
If one of the input parameters was invalid
MissingParameter
If one of the input parameters was missing
CLI Command
or
Example Request
Example Response
More Examples
Create instance with multiple nics
or
Create instance with tags
or
Network objects
As of CloudAPI v8.5.0 the networks parameter to CreateMachine takes an array of network objects to add flexibility and more control. It is also still possible to pass in an array of network UUID strings instead of the new network object format.
At a minimum the network object must contain an ipv4_uuid parameter that is the UUID of the network you wish the machine to have a NIC on. In addition you may pass in a ipv4_ips property that is an array made up of a single IP on that network's subnet.
When specifying an ipv4_ips array, the ipv4_uuid cannot be the UUID of a network pool, or a public network.
Here are some examples of possible network objects:
Affinity rules
As of CloudAPI v8.3.0 an "affinity" field can be specified with CreateMachine. It is an array of "affinity rules" to specify rules (or hints, "soft rules") for placement of the new instance.
By default, Triton makes a reasonable attempt to spread all containers (and non-Docker containers and VMs) owned by a single account across separate physical servers.
Affinity rules are of one of the following forms:
is one of:
==: The new instance must be on the same node as the instance(s) identified by .!=: The new instance must be on a different node to the instance(s) identified by .==~: The new instance should be on the same node as the instance(s) identified by . I.e. this is a best effort or "soft" rule.!=~: The new instance should be on a different node to the instance(s) identified by . I.e. this is a best effort or "soft" rule.
is an exact string, simple *-glob, or regular expression to match against instance names or IDs, or against the named tag's value. Some examples:
Locality hints
(Deprecated in CloudAPI v8.3.0.)
You may want this instance to be placed on the same server as another instance you have, or have it placed on an entirely different server from your existing instances so that you can spread them out. In either case, you can provide locality hints to CloudAPI.
Here is an example of a locality hint:
UUIDs provided should be the ids of instances belonging to you. If there is only a single UUID entry in an array, you can omit the array and provide the UUID string directly as the value to a near/far key.
strict defaults to false, meaning that Triton will attempt to meet all the near and/or far criteria but will still provision the instance when no server fits all the requirements. If strict is set to true, the creation of the new instance will fail if the affinity criteria cannot be met.
User-script
The special value metadata.user-script can be specified to provide a custom script which will be executed by the instance right after creation, and on every instance reboot. This script can be specified using the command-line option --script, which should be an absolute path to the file you want to upload to the instance.
StopMachine (POST /:login/machines/:id?action=stop)
Allows you to shut down an instance. POST to the instance name with an action of stop.
You can poll on GetMachine until the state is stopped.
Inputs
Field
Type
Description
action
String
Use the exact string "stop"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to be stopped
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
CLI Command
or
Example Request
Example Response
StartMachine (POST /:login/machines/:id?action=start)
Allows you to boot up an instance. POST to the instance name with an action of start.
You can poll on GetMachine until the state is running.
Inputs
Field
Type
Description
action
String
Use the exact string "start"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to be started
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
CLI Command
or
Example Request
Example Response
RebootMachine (POST /:login/machines/:id?action=reboot)
Allows you to reboot an instance. POST to the instance name with an action of reboot.
You can poll on GetMachine until the state is running.
Inputs
Field
Type
Description
action
String
Use the exact string "reboot"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to be stopped
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
CLI Command
or
Example Request
Example Response
ResizeMachine (POST /:login/machines/:id?action=resize)
Resize an instance to a new package (a.k.a. instance type).
Note that KVM instances (with brand=kvm) cannot be resized, and bhyve instances (brand=bhyve) only allow resizing to a package that uses flexible_disk.
Resizing is not guaranteed to work, especially when resizing upwards in resources. It is best-effort, and may fail. Resizing downwards will usually succeed.
Inputs
Field
Type
Description
action
String
Use the exact string "resize"
package
String
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to be resized
InvalidArgument
If action was invalid, or package wasn't a valid id or name
MissingParameter
If action or package wasn't provided
CLI Command
Example Request
Example Response
RenameMachine (POST /:login/machines/:id?action=rename)
Allows you to rename an instance. POST to the instance id with an action of rename. You must additionally include a new name for the instance.
Inputs
Field
Type
Description
action
String
Use the exact string "rename"
name
String
The new "friendly" name for this instance
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to be stopped
InvalidArgument
If action was invalid, or name wasn't a valid name
MissingParameter
If action or name wasn't provided
CLI Command
Example Request
Example Response
EnableMachineFirewall (POST /:login/machines/:id?action=enable_firewall)
Allows you to enable the firewall for an instance.
Inputs
Field
Type
Description
action
String
Use the exact string "enable_firewall"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to enable firewall
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
CLI Command
or
Example Request
Example Response
DisableMachineFirewall (POST /:login/machines/:id?action=disable_firewall)
Allows you to completely disable the firewall of an instance.
Inputs
Field
Type
Description
action
String
Use the exact string "disable_firewall"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to disable firewall
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
CLI Command
or
Example Request
Example Response
EnableMachineDeletionProtection (POST /:login/machines/:id?action=enable_deletion_protection)
Enable Deletion Protection on an instance. An instance can no longer be destroyed until the protection is disabled.
Inputs
Field
Type
Description
action
String
Use the exact string "enable_deletion_protection"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to enable firewall
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
Example Request
Example Response
DisableMachineDeletionProtection (POST /:login/machines/:id?action=disable_deletion_protection)
Disable Deletion Protection on an instance. An instance can be destroyed after it is disabled.
Inputs
Field
Type
Description
action
String
Use the exact string "disable_deletion_protection"
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to disable firewall
InvalidArgument
If action was invalid
MissingParameter
If action wasn't provided
Example Request
Example Response
CreateMachineSnapshot (POST /:login/machines/:id/snapshots)
Allows you to take a snapshot of an instance. Once you have one or more snapshots, you can boot the instance from a previous snapshot.
Snapshots are not usable with other instances; they are a point-in-time snapshot of the current instance. Snapshots can be taken of instances that are SmartOS, Docker, and bhyve, but not of brand 'kvm'.
Since instance instances use a copy-on-write filesystem, snapshots take up increasing amounts of space as the filesystem changes over time. There is a limit to how much space snapshots are allowed to take. Plan your snapshots accordingly.
You can poll on GetMachineSnapshot until the state is created.
Inputs
Field
Type
Description
name
String
The name to assign to the new snapshot
Returns
Field
Type
Description
name
String
The name of this snapshot
state
String
The current state of the snapshot
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidArgument
If name was invalid
CLI Command
or
Example Request
Example Response
StartMachineFromSnapshot (POST /:login/machines/:id/snapshots/:name)
If an instance is in the 'stopped' state, you can choose to start the instance from the referenced snapshot. This is effectively a means to roll back instance state.
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :name does not exist
CLI Command
or
Example Request
Example Response
ListMachineSnapshots (GET /:login/machines/:id/snapshots)
Lists all snapshots taken for a given instance. There are no filtration parameters for this API.
Inputs
None
Returns
An array of snapshots:
Field
Type
Description
name
String
The name of this snapshot
state
String
The current state of the snapshot
size
Number
The size of the snapshot (MiB)
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
GetMachineSnapshot (GET /:login/machines/:id/snapshots/:name)
Gets the state of the named snapshot.
Inputs
None
Returns
Field
Type
Description
name
String
The name of this snapshot
state
String
The current state of the snapshot (poll until it's "created")
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :name does not exist
CLI Command
or
Example Request
Example Response
DeleteMachineSnapshot (DELETE /:login/machines/:id/snapshots/:name)
Deletes the specified snapshot of an instance.
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :name does not exist
CLI Command
or
Example Request
Example Response
CreateMachineDisk (POST /:login/machines/:id/disks)
Interface is experimental; details may change in the future
Create a new disk for a bhyve VM.
The sum of all disk sizes on a VM is limited by flexible disk space. This operation only applies for VMs that are currently stopped.
Inputs
Field
Type
Description
pci_slot
String
Optional, PCI slot that the disk will fill
size
Number
Size in MiB, or the string "remaining" to use up all remaining available space
Returns
If no pci_slot argument was provided, then only a 202 (and no object) will be returned. You will need to poll ListMachineDisks until a new disk appears (if successful). pci_slot will be automatically assigned in this case.
If a pci_slot argument was provided, the Location header will be set, and 200 (with object) will be returned:
Field
Type
Description
id
String
This disk's UUID
pci_slot
String
This disk's PCI slot
size
Number
Size in MiB (before resize)
boot
Boolean
If this is the VM's boot disk
state
String
Current state of disk (i.e. 'creating')
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidArgument
If size or pci_slot was invalid
CLI Command
Example Request
Example Response
ResizeMachineDisk (POST /:login/machines/:id/disks/:disk_id)
Interface is experimental; details may change in the future
Asynchronously resize an existing disk on a bhyve VM.
The sum of all disk sizes on a VM is limited by flexible disk space. This operation only applies for VMs that are currently stopped.
When resizing down, dangerous_allow_shrink must be set to true otherwise the resize will be rejected. Since shrinking a disk truncates any data within that disk, it can cause filesystem corruption and data loss if the guest operating system does not handle it appropriately and data on the disk hasn't been prepared properly beforehand.
Since this is an asynchronous operation, resizing may take several seconds. Check the disk's state using GetMachineDisk.
Inputs
Field
Type
Description
size
Number
Size in MiB
dangerous_allow_shrink
Boolean
Optional, whether a disk can reduce size
Returns
Field
Type
Description
id
String
This disk's UUID
pci_slot
String
This disk's PCI slot
size
Number
Size in MiB (before resize)
boot
Boolean
If this is the VM's boot disk
state
String
Current state of disk (i.e. 'resizing')
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id, or :disk_id does not exist
InvalidArgument
If size or dangerous_allow_shrink was invalid
CLI Command
Example Request
Example Response
GetMachineDisk (GET /:login/machines/:id/disks/:disk_id)
Interface is experimental; details may change in the future
Fetch a specific disk on a bhyve VM.
Inputs
None
Returns
Field
Type
Description
id
String
This disk's UUID
pci_slot
String
This disk's PCI slot
size
Number
Size in MiB
boot
Boolean
If this is the VM's boot disk
state
String
Current state of disk
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id, or :disk_id does not exist
CLI Command
Example Request
Example Response
ListMachineDisks (GET /:login/machines/:id/disks)
Interface is experimental; details may change in the future
List all disk on a bhyve VM.
Inputs
None
Returns
Field
Type
Description
id
String
This disk's UUID
pci_slot
String
This disk's PCI slot
size
Number
Size in MiB
boot
Boolean
If this is the VM's boot disk
state
String
Current state of disk
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
DeleteMachineDisk (DELETE /:login/machines/:id/disks/:disk_id)
Interface is experimental; details may change in the future
Asynchronously delete a disk off a bhyve VM.
Since this is an asynchronous operation, deletion may take several seconds. You can check the disk's state using GetMachineDisk.
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :disk_id does not exist
CLI Command
Example Request
Example Response
UpdateMachineMetadata (POST /:login/machines/:id/metadata)
Allows you to update the metadata for a given instance. Note that updating the metadata via CloudAPI will result in the metadata being updated in the running instance.
The semantics of this call are subtly different that the AddMachineTags call -- any metadata keys passed in here are created if they do not exist, and overwritten if they do.
Inputs
Field
Type
Description
$key
String
You can assign any number of metadata keys in this call; the string can be either a plain string, or a JSON-encoded object
Returns
Returns the current set of tags.
Field
Type
Description
$key
Object
Your value(s)
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
ListMachineMetadata (GET /:login/machines/:id/metadata)
Returns the complete set of metadata associated with this instance.
Inputs
Field
Type
Description
credentials
Boolean
Whether or not to return instance credentials. Defaults to false
Returns
Returns the current metadata object
Field
Type
Description
$name
Object
Your metadata
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
GetMachineMetadata (GET /:login/machines/:id/metadata/:key)
Returns a single metadata entry associated with this instance.
Inputs
Field
Type
Description
key
String
Name of metadata value to retrieve
Returns
Returns metadata value as string.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :key does not exist
CLI Command
Example Request
Example Response
DeleteMachineMetadata (DELETE /:login/machines/:id/metadata/:key)
Deletes a single metadata key from this instance.
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :key does not exist
CLI Command
Example Request
Example Response
DeleteAllMachineMetadata (DELETE /:login/machines/:id/metadata)
Deletes all metadata keys from this instance.
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
CLI Command
If you're running in a Unix-like environment, you may need to quote the wildcard to keep the shell from matching files in the current directory.
Example Request
Example Response
AddMachineTags (POST /:login/machines/:id/tags)
Set tags on the given instance. A pre-existing tag with the same name as one given will be overwritten.
Note: This action is asynchronous. You can poll on ListMachineTags to wait for the update to be complete (the triton instance tag set -w,--wait option does this).
Inputs
Tag name/value pairs. Input data is typically as a application/json POST body. However, query params or application/x-www-form-urlencoded-encoded body also works. Tag values may be strings, numbers or booleans.
Returns
Returns the resultant set of tags as a JSON object.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
CLI Command
Using node-triton:
Using node-smartdc:
Example Request
Example Response
ReplaceMachineTags (PUT /:login/machines/:id/tags)
Fully replace all tags on an instance with the given tags.
Note: This action is asynchronous. You can poll on ListMachineTags to wait for the update to be complete (the triton instance tag replace-all -w,--wait option does this).
Inputs
Input data is typically as a application/json POST body. However, query params or application/x-www-form-urlencoded-encoded body also works. Tag values may be strings, numbers or booleans.
Returns
Returns the resultant set of tags as a JSON object.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
CLI Command
Using node-triton:
Using node-smartdc:
Example Request
Example Response
ListMachineTags (GET /:login/machines/:id/tags)
Returns the complete set of tags associated with this instance.
Inputs
None.
Returns
Returns the current set of tags as a JSON object.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
CLI Command
Using node-triton:
Using node-smartdc:
Example Request
Example Response
GetMachineTag (GET /:login/machines/:id/tags/:tag)
Returns the value for a single tag on this instance.
Typically one calls CloudAPI endpoints with Accept: application/json. This endpoint can be called that way, or alternatively with Accept: text/plain to get the non-JSON value in the response.
Inputs
None.
Returns
The tag value.
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :tag does not exist
CLI Command
Using node-triton:
Using node-smartdc:
Example Request/Response
Using application/json, the request:
the response:
Using text/plain, the request:
the response:
DeleteMachineTag (DELETE /:login/machines/:id/tags/:tag)
Deletes a single tag from this instance.
Note: This action is asynchronous. You can poll on ListMachineTags to wait for the update to be complete (the triton instance tag delete -w,--wait option does this).
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login, :id or :tag does not exist
CLI Command
Using node-triton:
Using node-smartdc:
Example Request
Example Response
DeleteMachineTags (DELETE /:login/machines/:id/tags)
Deletes all tags from an instance.
Note: This action is asynchronous. You can poll on ListMachineTags to wait for the update to be complete (the triton instance tag delete -w,--wait option does this).
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
CLI Command
Using node-triton:
Using node-smartdc:
Example Request
Example Response
DeleteMachine (DELETE /:login/machines/:id)
Allows you to completely destroy an instance.
An instance cannot be destroyed so long as Deletion Protection is enabled on that instance.
Inputs
None
Returns
None
Errors
For all possible errors, see CloudAPI HTTP Responses.
Error Code
Description
ResourceNotFound
If :login or :id does not exist
InvalidState
The instance is in the wrong state to be deleted
CannotDestroyMachine
CLI Command
or
Example Request
Example Response
MachineAudit (GET /:login/machines/:id/audit)
Provides a list of an instance's accomplished actions. Results are sorted from newest to oldest action.
Note that the complete audit trail is returned only if the instance history and job records have not been purged from Triton.
Inputs
None
Returns
An array of action objects, which contain:
Field
Type
Description
action
String
The name of the action
success
String
Either "yes" or "no", depending on the action's success
caller
Object
Account requesting the action
time
Date (ISO8601)
When the action finished
Depending on the account requesting the action, caller can have the following members:
Field
Type
Description
type
String
Authentication type for the action request. One of "basic", "operator", "signature" or "token"
user
String
When the authentication type is "basic", this member will be present and include user login
ip
String
The IP addresses this from which the action was requested. Not present if type is "operator"
keyId
String
When authentication type is either "signature" or "token", SSH key identifier
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
Deletion Protection
If you want to decrease the risk of accidental instance destruction, it is possible to make instance destruction (e.g. through DeleteMachine) a two-step process.
Instances that have the attribute deletion_protection set to boolean true cannot be deleted, either through CloudAPI or SDC Docker. In order to delete such an instance, the above attribute needs to be set to false first.
The attribute can be set during instance creation (see CreateMachine), or added later (see EnableMachineDeletionProtection). The instance then cannot be destroyed until the attribute is set to false, although all other operations will still work. To destroy the instance, first call DisableMachineDeletionProtection) on the instance.
CLI Commands
Last updated