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

Whether an instance is destroyable. See Deletion Protection

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:

triton instance list

or

sdc-listmachines

Get all LX instance:

triton instance list brand=lx

or

sdc-listmachines --brand lx

Get all LX machines that are currently running:

triton instance list brand=lx state=running

or

sdc-listmachines --brand lx --state running

Get all LX instances that are currently running, and have 256 MiB of memory:

triton instance list brand=lx state=running memory=256

or

sdc-listmachines --brand lx --state running --memory 256

Get all LX instances that are currently running, with 256 MiB of RAM, tagged as 'test':

sdc-listmachines --brand lx --state running --memory 256 --tag group=test

Get all tagged instances:

sdc-listmachines --tag \*

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

GET /my/machines HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Api-Version: ~8

Example Response

HTTP/1.1 200 OK
x-query-limit: 1000
x-resource-count: 1
Content-Type: application/json
Content-Length: 1310
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: w5wJLKlhDzPpC6zKjtqaCw==
Date: Thu, 21 Jan 2016 10:55:25 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 779b5cc0-c02d-11e5-a7d2-fdf229d32220
Response-Time: 3444

[
  {
    "id": "b6979942-7d5d-4fe6-a2ec-b812e950625a",
    "name": "test",
    "type": "smartmachine",
    "brand": "joyent",
    "state": "running",
    "image": "2b683a82-a066-11e3-97ab-2faa44701c5a",
    "ips": [
      "10.88.88.26",
      "192.168.128.5"
    ],
    "memory": 128,
    "disk": 12288,
    "metadata": {
      "root_authorized_keys": "..."
    },
    "tags": {},
    "created": "2016-01-04T12:55:50.539Z",
    "updated": "2016-01-21T08:56:59.000Z",
    "networks": [
      "a9c130da-e3ba-40e9-8b18-112aba2d3ba7",
      "45607081-4cd2-45c8-baf7-79da760fffaa"
    ],
    "primaryIp": "10.88.88.26",
    "firewall_enabled": false,
    "compute_node": "564d0b8e-6099-7648-351e-877faf6c56f6",
    "package": "sdc_128"
  }
]

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]

DNS names of the instance (if the instance is using CNS)

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:

triton instance get b6979942-7d5d-4fe6-a2ec-b812e950625a

or

sdc-getmachine b6979942-7d5d-4fe6-a2ec-b812e950625a

Example Request

GET /my/machines/b6979942-7d5d-4fe6-a2ec-b812e950625a HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Api-Version: ~8

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1308
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: 0q2leQEqeZCNiznbZvKhZw==
Date: Thu, 21 Jan 2016 10:58:11 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: db0705c0-c02d-11e5-b1b7-65fab9169f0e
Response-Time: 3159

{
  "id": "b6979942-7d5d-4fe6-a2ec-b812e950625a",
  "name": "test",
  "type": "smartmachine",
  "brand": "joyent",
  "state": "running",
  "image": "2b683a82-a066-11e3-97ab-2faa44701c5a",
  "ips": [
    "10.88.88.26",
    "192.168.128.5"
  ],
  "memory": 128,
  "disk": 12288,
  "metadata": {
    "root_authorized_keys": "...",
  },
  "tags": {},
  "created": "2016-01-04T12:55:50.539Z",
  "updated": "2016-01-21T08:56:59.000Z",
  "networks": [
    "a9c130da-e3ba-40e9-8b18-112aba2d3ba7",
    "45607081-4cd2-45c8-baf7-79da760fffaa"
  ],
  "primaryIp": "10.88.88.26",
  "firewall_enabled": false,
  "compute_node": "564d0b8e-6099-7648-351e-877faf6c56f6",
  "package": "sdc_128"
}

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:

"metadata": {
  "credentials": {
    "root": "s8v9kuht5e",
    "admin": "mf4bteqhpy"
  }
}

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

Id of the package to use on provisioning, obtained from ListPackages

image

String

The image UUID (the "id" field in ListImages)

networks

Array

Array of network objects, or an array of network UUIDs obtained from ListNetworks. See the note about network pools under AddNic.

affinity

Array

(Added in CloudAPI v8.3.0.) Optional array of affinity rules.

locality

Object

(Deprecated in CloudAPI v8.3.0.) Optionally object of locality hints, specify which instances the new instance should be near or far from.

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

Whether an instance is destroyable. See Deletion Protection. Default is false

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

triton instance create 2b683a82-a066-11e3-97ab-2faa44701c5a 7b17343c-94af-6266-e0e8-893a3b9993d0

or

sdc-createmachine --image=2b683a82-a066-11e3-97ab-2faa44701c5a --package=7b17343c-94af-6266-e0e8-893a3b9993d0

Example Request

POST /my/machines HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 455
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

{
  "image": "2b683a82-a066-11e3-97ab-2faa44701c5a",
  "package": "7b17343c-94af-6266-e0e8-893a3b9993d0"
}

Example Response

HTTP/1.1 201 Created
Location: /my/machines/e8622950-af78-486c-b682-dd147c938dc6
Content-Type: application/json
Content-Length: 1151
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Content-MD5: s5ROP0dBDWlf5X1drujDvg==
Date: Thu, 21 Jan 2016 12:57:52 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 9283ba80-c03e-11e5-b1b7-65fab9169f0e
Response-Time: 4655

{
  "id": "e8622950-af78-486c-b682-dd147c938dc6",
  "name": "e8622950",
  "type": "smartmachine",
  "brand": "joyent",
  "state": "provisioning",
  "image": "2b683a82-a066-11e3-97ab-2faa44701c5a",
  "ips": [],
  "memory": 128,
  "disk": 12288,
  "metadata": {
    "root_authorized_keys": "..."
  },
  "tags": {},
  "created": "2016-01-21T12:57:52.759Z",
  "updated": "2016-01-21T12:57:52.979Z",
  "networks": [],
  "firewall_enabled": false,
  "compute_node": null,
  "package": "sdc_128"
}

More Examples

Create instance with multiple nics

triton instance create --network=42325ea0-eb62-44c1-8eb6-0af3e2f83abc --network=c8cde927-6277-49ca-82a3-741e8b23b02f 2b683a82-a066-11e3-97ab-2faa44701c5a 7b17343c-94af-6266-e0e8-893a3b9993d0

or

sdc-createmachine --image=2b683a82-a066-11e3-97ab-2faa44701c5a --package=7b17343c-94af-6266-e0e8-893a3b9993d0 --networks=42325ea0-eb62-44c1-8eb6-0af3e2f83abc --networks=c8cde927-6277-49ca-82a3-741e8b23b02f

Create instance with tags

triton instance create -t foo=bar -t group=test 2b683a82-a066-11e3-97ab-2faa44701c5a 7b17343c-94af-6266-e0e8-893a3b9993d0

or

sdc-createmachine --image=2b683a82-a066-11e3-97ab-2faa44701c5a --package=7b17343c-94af-6266-e0e8-893a3b9993d0 -t foo=bar -t group=test

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:

[
  {
    "ipv4_uuid": "f65153df-edf5-11e7-bb45-54e1adb5aaf3",
    "ipv4_ips": [
      "10.0.1.50"
    ]
  },
  {
    "ipv4_uuid": "6fa58531-edf6-11e7-bb45-54e1adb5aaf3"
  }
]

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:

instance<op><value>
container<op><value>
<tagName><op><value>

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:

# Run on the same node as instance silent_bob.
triton instance create -a instance==silent_bob ...

# Run on a different node to all instances tagged with 'role=database'.
triton instance create -a 'role!=database' ...

# Run on a different node to all instances with names starting with "foo".
triton instance create -a 'instance!=foo*' ...

# Same, using a regular expression.
triton instance create -a 'instance!=/^foo/' ...

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:

"locality": {
  "strict": false,
  "near": ["af7ebb74-59be-4481-994f-f6e05fa53075"],
  "far": ["da568166-9d93-42c8-b9b2-bce9a6bb7e0a", "d45eb2f5-c80b-4fea-854f-32e4a9441e53"]
}

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

triton instance stop c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

or

sdc-stopmachine c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=stop

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:05:58 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: b49ae1b0-c03f-11e5-a7d2-fdf229d32220
Response-Time: 3175
Transfer-Encoding: chunked

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

triton instance start c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

or

sdc-startmachine c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=start

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:07:24 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: e7fda2e0-c03f-11e5-a64c-d133f917673f
Response-Time: 3487
Transfer-Encoding: chunked

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

triton instance reboot c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

or

sdc-rebootmachine c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=reboot

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:09:34 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 35679950-c040-11e5-b1b7-65fab9169f0e
Response-Time: 3124
Transfer-Encoding: chunked

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

A package id, as returned from ListPackages

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

sdc-resizemachine --package=7041ccc7-3f9e-cf1e-8c85-a9ee41b7f968 c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=resize&package=7041ccc7-3f9e-cf1e-8c85-a9ee41b7f968

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:12:06 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 8fa7d8d0-c040-11e5-9100-a95edd60134e
Response-Time: 161

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

sdc-renamemachine --name=new_friendly_name c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=rename&name=new_friendly_name

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:14:17 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: dda360e0-c040-11e5-a64c-d133f917673f
Response-Time: 3768
Transfer-Encoding: chunked

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

triton instance enable-firewall c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

or

sdc-enablemachinefirewall c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=enable_firewall

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:16:00 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 1b1e83a0-c041-11e5-b1b7-65fab9169f0e
Response-Time: 3594
Transfer-Encoding: chunked

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

triton instance disable-firewall c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

or

sdc-disablemachinefirewall c2855c3a-a91d-46b8-9da6-6d7ab1bc6962

Example Request

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=disable_firewall

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:23:39 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 2c74e120-c042-11e5-9100-a95edd60134e
Response-Time: 4178
Transfer-Encoding: chunked

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

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=enable_deletion_protection

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2017 13:16:00 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 1b1e83a0-c041-11e5-b1b7-65fab9169f0e
Response-Time: 3594
Transfer-Encoding: chunked

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

POST /my/machines/c2855c3a-a91d-46b8-9da6-6d7ab1bc6962 HTTP/1.1
Host: api.example.com
Authorization: ...
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

action=disable_deletion_protection

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Api-Version, Response-Time
Access-Control-Allow-Methods: POST, GET, HEAD, DELETE, PUT
Access-Control-Expose-Headers: Api-Version, Request-Id, Response-Time
Connection: Keep-Alive
Date: Thu, 21 Jan 2016 13:23:39 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 2c74e120-c042-11e5-9100-a95edd60134e
Response-Time: 4178
Transfer-Encoding: chunked

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

triton instance snapshot create 5e42cd1e-34bb-402f-8796-bf5a2cae47db

or

sdc-createmachinesnapshot --name=just-booted 5e42cd1e-34bb-402f-8796-bf5a2cae47db

Example Request

POST /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/snapshots HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

name=just-booted

Example Response

HTTP/1.1 201 Created
Location: /mark/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/snapshots/just-booted
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Connection: close
Date: Tue, 05 Jul 2011 17:19:26 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 4bcf467e-4b88-4ab4-b7ab-65fad7464de9
Response-Time: 754
Content-Type: application/json
Content-MD5: qKVbfrhXVqh7Oni6Pub9Pw==
Content-Length: 116

{
  "name": "just-booted",
  "state": "queued",
  "created": "2011-07-05T17:19:26+00:00",
  "updated": "2011-07-05T17:19:26+00:00"
}

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

triton instance start --snapshot=just-booted 5e42cd1e-34bb-402f-8796-bf5a2cae47db

or

sdc-startmachinefromsnapshot --snapshot=just-booted 5e42cd1e-34bb-402f-8796-bf5a2cae47db

Example Request

POST /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/snapshots/just-booted HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

Example Response

HTTP/1.1 202 Accepted
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE
Connection: close
Date: Tue, 05 Jul 2011 17:26:56 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: af79d9cd-68c5-4002-95c6-af4c3ff0f1e4
Response-Time: 297
Content-Length: 0

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

triton instance snapshot list 5e42cd1e-34bb-402f-8796-bf5a2cae47db

or

sdc-listmachinesnapshots 5e42cd1e-34bb-402f-8796-bf5a2cae47db

Example Request

GET /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/snapshots HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

Example Response

HTTP/1.1 200 Ok
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Connection: close
Date: Tue, 05 Jul 2011 17:19:26 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: 06a57272-9238-4276-951b-4123fbfdb948
Response-Time: 66
Content-Type: application/json
Content-MD5: UYdtqgRjRZVikfCM5Uf4XQ==
Content-Length: 119

[
  {
    "name": "just-booted",
    "state": "queued",
    "created": "2011-07-05T17:19:26+00:00",
    "updated": "2011-07-05T17:19:26+00:00"
  }
]

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

triton instance snapshot get 5e42cd1e-34bb-402f-8796-bf5a2cae47db just-booted

or

sdc-getmachinesnapshot --snapshot=just-booted 5e42cd1e-34bb-402f-8796-bf5a2cae47db

Example Request

GET /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/snapshots/just-booted HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

Example Response

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE
Connection: close
Date: Tue, 05 Jul 2011 17:26:56 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: af79d9cd-68c5-4002-95c6-af4c3ff0f1e4
Response-Time: 297
Content-Type: application/json
Content-MD5: VoPeS9cac4YMBIs8gUkd/A==
Content-Length: 117

{
  "name": "just-booted",
  "state": "queued",
  "created": "2011-07-05T17:19:26+00:00",
  "updated": "2011-07-05T17:19:26+00:00"
}

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

triton instance snapshot delete 5e42cd1e-34bb-402f-8796-bf5a2cae47db just-booted

or

sdc-deletemachinesnapshot --snapshot=just-booted 5e42cd1e-34bb-402f-8796-bf5a2cae47db

Example Request

DELETE /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/snapshots/just-booted HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 0
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8

Example Response

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE
Connection: close
Date: Tue, 05 Jul 2011 17:26:56 GMT
Server: Joyent Triton 8.0.0
Api-Version: 8.0.0
Request-Id: af79d9cd-68c5-4002-95c6-af4c3ff0f1e4
Response-Time: 297
Content-Length: 0

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

triton cloudapi /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks \
  -X POST -d '{"pci_slot":"0:4:1", "size": 1024}'

Example Request

POST /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~9

pci_slot=0:4:1
size=1024

Example Response

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Connection: close
Date: Tue, 05 Dec 2018 17:19:26 GMT
Server: Joyent Triton 9.4.0
Api-Version: 9.0.0
Request-Id: 4bcf467e-4b88-4ab4-b7ab-65fad7464de9
Response-Time: 754
Content-Type: application/json
Content-Length: 0

{