# 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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://docs.joyent.com/public-cloud/network/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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#keys) 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](https://apidocs.joyent.com/cloudapi/#GetMachine) until the instance state is `running`.
Typically, Triton will allocate the new instance somewhere reasonable within the cloud. See [affinity rules](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#ListPackages) |
| image | String | The image UUID (the "id" field in [ListImages](https://apidocs.joyent.com/cloudapi/#ListImages)) |
| networks | Array | Array of [network objects](https://apidocs.joyent.com/cloudapi/#network-objects), or an array of network UUIDs obtained from [ListNetworks](https://apidocs.joyent.com/cloudapi/#ListNetworks). See the note about network pools under [AddNic](https://apidocs.joyent.com/cloudapi/#AddNic). |
| affinity | Array | (Added in CloudAPI v8.3.0.) Optional array of [affinity rules](https://apidocs.joyent.com/cloudapi/#affinity-rules). |
| locality | Object | (Deprecated in CloudAPI v8.3.0.) Optionally object of [locality hints](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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
container
```
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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#packages) (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](https://apidocs.joyent.com/cloudapi/#ListPackages) |
#### Returns
* None
#### Errors
For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#list-machine-disks) 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](https://apidocs.joyent.com/cloudapi/#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
{
"id": "21f04764-1db8-47dc-acfd-2215f2b842e9",
"pci_slot": "0:4:1",
"size": 1024,
"boot": false,
"state": "creating"
}
```
### 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](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#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
```
triton cloudapi /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks/21f04764-1db8-47dc-acfd-2215f2b842e9 \
-X POST -d '{"size": 2048}'
```
#### Example Request
```
POST /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks/21f04764-1db8-47dc-acfd-2215f2b842e9 HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~9
size=2048
```
#### 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-MD5: qKVbfrhXVqh7Oni6Pub9Pw==
Content-Length: 70
{
"id": "21f04764-1db8-47dc-acfd-2215f2b842e9",
"pci_slot": "0:4:1",
"size": 1024,
"boot": false,
"state": "resizing"
}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ------------------------------------------------ |
| ResourceNotFound | If `:login`, `:id`, or `:disk_id` does not exist |
#### CLI Command
```
triton cloudapi /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks/21f04764-1db8-47dc-acfd-2215f2b842e9
```
#### Example Request
```
GET /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks/21f04764-1db8-47dc-acfd-2215f2b842e9 HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~9
```
#### 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-MD5: qKVbfrhXVqh7Oni6Pub9Pw==
Content-Length: 74
{
"id": "21f04764-1db8-47dc-acfd-2215f2b842e9",
"pci_slot": "0:4:1",
"size": 2048,
"boot": false,
"state": "running",
}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
```
triton cloudapi /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks
```
#### Example Request
```
GET /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
```
#### 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-MD5: qKVbfrhXVqh7Oni6Pub9Pw==
Content-Length: 74
[
{
"id": "2bb08ea6-1da0-11e9-adaa-23f0e1aab5d7",
"pci_slot": "0:4:0",
"size": 10240,
"boot": true,
"state": "running",
},
{
"id": "21f04764-1db8-47dc-acfd-2215f2b842e9",
"pci_slot": "0:4:1",
"size": 2048,
"boot": false,
"state": "running",
}
]
```
### 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](https://apidocs.joyent.com/cloudapi/#GetMachineDisk).
#### Inputs
* None
#### Returns
* None
#### Errors
For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------------------- |
| ResourceNotFound | If `:login`, `:id` or `:disk_id` does not exist |
#### CLI Command
```
triton cloudapi /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks/21f04764-1db8-47dc-acfd-2215f2b842e9 -X DELETE
```
#### Example Request
```
DELETE /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/disks/21f04764-1db8-47dc-acfd-2215f2b842e9 HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~9
```
#### Example Response
```
HTTP/1.1 204 No Content
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
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
```
sdc-updatemachinemetadata -m foo=bar -m group=test cf055959-d776-482e-bd71-ca510a04bdd7
```
#### Example Request
```
POST /my/machines/cf055959-d776-482e-bd71-ca510a04bdd7/metadata HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Content-Length: 12
Content-Type: application/x-www-form-urlencoded
Api-Version: ~8
foo=bar&group=test
```
#### 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: 4bcf467e-4b88-4ab4-b7ab-65fad7464de9
Response-Time: 754
Content-Type: application/json
Content-MD5: qKVbfrhXVqh7Oni6Pub9Pw==
Content-Length: 116
{
"foo": "bar",
"group": "test"
}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
```
sdc-listmachinemetadata cf055959-d776-482e-bd71-ca510a04bdd7
```
#### Example Request
```
GET /my/machines/cf055959-d776-482e-bd71-ca510a04bdd7/metadata?credentials=true HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
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: 4bcf467e-4b88-4ab4-b7ab-65fad7464de9
Response-Time: 754
Content-Type: application/json
Content-MD5: qKVbfrhXVqh7Oni6Pub9Pw==
Content-Length: 116
{
"foo": "bar",
"group": "test",
"credentials": {
"root": "s8v9kuht5e",
"admin": "mf4bteqhpy"
}
}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ------------------------------------------- |
| ResourceNotFound | If `:login`, `:id` or `:key` does not exist |
#### CLI Command
```
sdc-getmachinemetadata --metadataId=foo cf055959-d776-482e-bd71-ca510a04bdd7
```
#### Example Request
```
GET /my/machines/cf055959-d776-482e-bd71-ca510a04bdd7/metadata/foo HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
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 2014 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: 4
bar
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ------------------------------------------- |
| ResourceNotFound | If `:login`, `:id` or `:key` does not exist |
#### CLI Command
```
sdc-deletemachinemetadata --metadata=foo cf055959-d776-482e-bd71-ca510a04bdd7
```
#### Example Request
```
DELETE /my/machines/cf055959-d776-482e-bd71-ca510a04bdd7/metadata/foo HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Api-Version: ~8
```
#### Example Response
```
HTTP/1.1 204 No Content
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: 0
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
```
sdc-deletemachinemetadata --metadata='*' cf055959-d776-482e-bd71-ca510a04bdd7
```
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
```
DELETE /my/machines/cf055959-d776-482e-bd71-ca510a04bdd7/metadata HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Api-Version: ~8
```
#### Example Response
```
HTTP/1.1 204 No Content
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: 0
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
Using node-triton:
```
triton instance tag set -w 5e42cd1e foo=bar group=test
```
Using node-smartdc:
```
sdc-addmachinetags --tag='foo=bar' --tag='group=test' 5e42cd1e-34bb-402f-8796-bf5a2cae47db
```
#### Example Request
```
POST /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags HTTP/1.1
Host: us-east-3b.api.joyent.com
date: Thu, 11 Feb 2016 18:03:46 GMT
authorization: ...
accept: application/json
content-type: application/json
accept-version: ~8||~7
content-length: 28
{"foo":"bar","group":"test"}
```
#### Example Response
```
HTTP/1.1 200 OK
server: Joyent Triton 8.0.0
request-id: cb65c530-d0e9-11e5-ac0c-090497b36c30
date: Thu, 11 Feb 2016 18:03:46 GMT
response-time: 91
...
api-version: 8.0.0
content-length: 48
{"foo":"bar","group":"test","preexiting":"blah"}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
Using node-triton:
```
triton instance tag replace-all -w 5e42cd1e foo=bar group=test
```
Using node-smartdc:
```
sdc-replacemachinetags --tag='foo=bar' --tag='group=test' 5e42cd1e-34bb-402f-8796-bf5a2cae47db
```
#### Example Request
```
POST /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags HTTP/1.1
Host: us-east-3b.api.joyent.com
date: Thu, 11 Feb 2016 18:03:46 GMT
authorization: ...
accept: application/json
content-type: application/json
accept-version: ~8||~7
content-length: 28
{"foo":"bar","group":"test"}
```
#### Example Response
```
HTTP/1.1 200 OK
server: Joyent Triton 8.0.0
request-id: cb65c530-d0e9-11e5-ac0c-090497b36c30
date: Thu, 11 Feb 2016 18:03:46 GMT
response-time: 91
...
api-version: 8.0.0
content-length: 28
{"foo":"bar","group":"test"}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
Using node-triton:
```
triton instance tag list 5e42cd1e
{
"foo": "bar",
"group": "test"
}
$ triton instance tags 5e42cd1e # shortcut
{
"foo": "bar",
"group": "test"
}
```
Using node-smartdc:
```
sdc-listmachinetags 5e42cd1e-34bb-402f-8796-bf5a2cae47db
```
#### Example Request
```
GET /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags HTTP/1.1
Host: api.example.com
authorization: ...
accept: application/json
accept-version: ~8||~7
```
#### Example Response
```
HTTP/1.1 200 OK
server: Joyent Triton 8.0.0
request-id: 4bcf467e-4b88-4ab4-b7ab-65fad7464de9
date: Thu, 11 Feb 2016 18:03:46 GMT
response-time: 91
...
api-version: 8.0.0
content-length: 28
{"foo":"bar","group":"test"}
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ------------------------------------------- |
| ResourceNotFound | If `:login`, `:id` or `:tag` does not exist |
#### CLI Command
Using node-triton:
```
triton instance tag get 5e42cd1e foo
bar
$ triton instance tag get --json 5e42cd1e foo # encoded as JSON
"bar"
```
Using node-smartdc:
```
sdc-getmachinetag --tag=foo 5e42cd1e-34bb-402f-8796-bf5a2cae47db
bar
```
#### Example Request/Response
Using `application/json`, the request:
```
GET /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags/foo HTTP/1.1
Host: api.example.com
authorization: ...
accept: application/json
accept-version: ~8||~7
```
the response:
```
HTTP/1.1 200 OK
...
content-type: application/json
content-length: 5
"bar"
```
Using `text/plain`, the request:
```
GET /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags/foo HTTP/1.1
Host: api.example.com
authorization: ...
accept: text/plain
accept-version: ~8||~7
```
the response:
```
HTTP/1.1 200 OK
...
content-type: text/plain
content-length: 3
bar
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ------------------------------------------- |
| ResourceNotFound | If `:login`, `:id` or `:tag` does not exist |
#### CLI Command
Using node-triton:
```
triton instance tag delete -w 5e42cd1e foo
```
Using node-smartdc:
```
sdc-deletemachinetag --tag=foo 5e42cd1e-34bb-402f-8796-bf5a2cae47db
```
#### Example Request
```
DELETE /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags/foo HTTP/1.1
Host: api.example.com
authorization: ...
accept: text/plain
accept-version: ~8||~7
```
#### Example Response
```
HTTP/1.1 204 No Content
...
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
Using node-triton:
```
triton instance tag delete -w --all 5e42cd1e
```
Using node-smartdc:
```
# Remember to quote the `*` to avoid shell expansion.
$ sdc-deletemachinetag --tag='*' 5e42cd1e-34bb-402f-8796-bf5a2cae47db
```
#### Example Request
```
DELETE /my/machines/5e42cd1e-34bb-402f-8796-bf5a2cae47db/tags HTTP/1.1
Host: api.example.com
authorization: ...
accept: text/plain
accept-version: ~8||~7
```
#### Example Response
```
HTTP/1.1 204 No Content
...
```
### DeleteMachine (DELETE /:login/machines/:id)
Allows you to completely destroy an instance.
An instance cannot be destroyed so long as [Deletion Protection](https://apidocs.joyent.com/cloudapi/#deletion-protection) is enabled on that instance.
#### Inputs
* None
#### Returns
* None
#### Errors
For all possible errors, see [CloudAPI HTTP Responses](https://apidocs.joyent.com/cloudapi/#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 | [Deletion Protection](https://apidocs.joyent.com/cloudapi/#deletion-protection) is enabled on this instance |
#### CLI Command
```
triton instance delete 75cfe125-a5ce-49e8-82ac-09aa31ffdf26
```
or
```
sdc-deletemachine 75cfe125-a5ce-49e8-82ac-09aa31ffdf26
```
#### Example Request
```
DELETE /my/machines/75cfe125-a5ce-49e8-82ac-09aa31ffdf26 HTTP/1.1
Authorization: ...
Host: api.example.com
Accept: application/json
Api-Version: ~8
```
**Example Response**
```
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE
Server: Joyent Triton 8.0.0
Connection: close
Date: Wed, 13 Apr 2011 23:38:03 GMT
Api-Version: 8.0.0
Request-Id: 762C3F37-8ACA-4A49-AF10-84CEC8137B1D
Response-Time: 72
Content-Length: 0
```
### 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](https://apidocs.joyent.com/cloudapi/#cloudapi-http-responses).
| **Error Code** | **Description** |
| ---------------- | ----------------------------------- |
| ResourceNotFound | If `:login` or `:id` does not exist |
#### CLI Command
```
triton instance audit 75cfe125-a5ce-49e8-82ac-09aa31ffdf26
```
or
```
sdc-getmachineaudit 75cfe125-a5ce-49e8-82ac-09aa31ffdf26
```
#### Example Request
```
GET /my/machines/75cfe125-a5ce-49e8-82ac-09aa31ffdf26/audit 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: 191
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: GET
access-control-expose-headers: Api-Version, Request-Id, Response-Time
connection: Keep-Alive
content-md5: GRmOq/dAdKZJ4wVpEelRrQ==
date: Fri, 22 Feb 2013 15:19:37 GMT
server: Joyent Triton 8.0.0
api-version: 8.0.0
request-id: 453aee00-7d03-11e2-8048-5195b6159808
response-time: 34
[{
"success": "yes",
"time": "2013-02-22T15:19:32.522Z",
"action": "provision",
"caller": {
"type": "signature",
"ip": "127.0.0.1",
"keyId": "/:login/keys/:fingerprint"
}
}, ...]
```
### Deletion Protection
If you want to decrease the risk of accidental instance destruction, it is possible to make instance destruction (e.g. through [DeleteMachine](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#CreateMachine)), or added later (see [EnableMachineDeletionProtection](https://apidocs.joyent.com/cloudapi/#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](https://apidocs.joyent.com/cloudapi/#DisableMachineDeletionProtection)) on the instance.
#### CLI Commands
```
triton instance create 62aaa296 0ea54d9d --deletion-protection
$ triton instance disable-deletion-protection 9985bc81
$ triton instance enable-deletion-protection 9985bc81
```