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
Last updated
Triton supports three different types of instances:Docker containers. OS-virtualized instances managed through the Docker client.Infrastructure containers. More traditional OS-virtualized instances
Last updated
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.
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.
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.
An array of instance objects, which contain:
For all possible errors, see CloudAPI HTTP Responses.
Get all instance:
or
Get all LX instance:
or
Get all LX machines that are currently running:
or
Get all LX instances that are currently running, and have 256 MiB of memory:
or
Get all LX instances that are currently running, with 256 MiB of RAM, tagged as 'test':
Get all tagged instances:
Beware that depending on your shell you may need to escape the asterisk character. E.g. Bash requires it escaped.
The CLI has parameters that let you filter on most things in the API, and you can combine them. Run triton instance list --help or sdc-listmachines --help to see all the options.
Gets the details for an individual instance.
Deleted instances are returned only if the instance history has not been purged from Triton.
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.
For all possible errors, see CloudAPI HTTP Responses.
Get the details for the instance with id 75cfe125-a5ce-49e8-82ac-09aa31ffdf26:
or
Allows you to provision an instance.
If you do not specify a name, CloudAPI will generate a random one for you. If you have enabled Triton CNS on your account, this name will also be used in DNS to refer to the new instance (and must therefore consist of DNS-safe characters only).
Your instance will initially be not available for login (Triton must provision and boot it); you can poll GetMachine for its status. When the state field is equal to running, you can log in. If the instance is a brand other than kvm or bhyve, you can usually use any of the SSH keys managed under the keys section of CloudAPI to login as any POSIX user on the OS. You can add/remove keys over time, and the instance will automatically work with that set.
If the the instance has a brand kvm or bhyve, and of a UNIX-derived OS (e.g. Linux), you must have keys uploaded before provisioning; that entire set of keys will be written out to /root/.ssh/authorized_keys in the new instance, and you can SSH in using one of those keys. Changing the keys over time under your account will not affect a running hardware virtual machine in any way; those keys are statically written at provisioning-time only, and you will need to manually manage them on the instance itself.
If the image you create an instance from is set to generate passwords for you, the username/password pairs will be returned in the metadata response as a nested object, like so:
You cannot overwrite the credentials key in CloudAPI.
More generally, the metadata keys can be set either at the time of instance creation, or after the fact. You must either pass in plain-string values, or a JSON-encoded string. On metadata retrieval, you will get a JSON object back.
Networks can be specified using the networks attribute. It is possible to have an instance attached to an internal network, external network or both. If the networks attribute is absent from the input, the instance will be attached to one externally-accessible network (i.e. assigned a public IP), and any one of internal/private networks. If the account owns or has access to multiple private networks, it will be important to include the desired network(s) in the request payload instead of letting the system assign the network automatically.
Be aware that CreateMachine does not return IP addresses or networks. To obtain the IP addresses and networks of a newly-provisioned instance, poll GetMachine until the instance state is running.
Typically, Triton will allocate the new instance somewhere reasonable within the cloud. See affinity rules below for options on controlling server placement of new instances.
When Triton CNS is enabled, the DNS search domain of the new VM will be automatically set to the suffix of the "instance" record that is created for that VM. For example, if the full CNS name of the new VM would be "foo.inst.35ad1ec4-2eab-11e6-ac02-8f56c66976a1.us-west-1.triton.zone", its automatic DNS search path would include "inst.35ad1ec4-2eab-11e6-ac02-8f56c66976a1.us-west-1.triton.zone". This can be changed later within the instance, if desired.
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:
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
For all possible errors, see CloudAPI HTTP Responses.
or
Create instance with multiple nics
or
Create instance with tags
or
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:
As of CloudAPI v8.3.0 an "affinity" field can be specified with CreateMachine. It is an array of "affinity rules" to specify rules (or hints, "soft rules") for placement of the new instance.
By default, Triton makes a reasonable attempt to spread all containers (and non-Docker containers and VMs) owned by a single account across separate physical servers.
Affinity rules are of one of the following forms:
is one of:
==: The new instance must be on the same node as the instance(s) identified by .
!=: The new instance must be on a different node to the instance(s) identified by .
==~: The new instance should be on the same node as the instance(s) identified by . I.e. this is a best effort or "soft" rule.
!=~: The new instance should be on a different node to the instance(s) identified by . I.e. this is a best effort or "soft" rule.
is an exact string, simple *-glob, or regular expression to match against instance names or IDs, or against the named tag's value. Some examples:
(Deprecated in CloudAPI v8.3.0.)
You may want this instance to be placed on the same server as another instance you have, or have it placed on an entirely different server from your existing instances so that you can spread them out. In either case, you can provide locality hints to CloudAPI.
Here is an example of a locality hint:
UUIDs provided should be the ids of instances belonging to you. If there is only a single UUID entry in an array, you can omit the array and provide the UUID string directly as the value to a near/far key.
strict defaults to false, meaning that Triton will attempt to meet all the near and/or far criteria but will still provision the instance when no server fits all the requirements. If strict is set to true, the creation of the new instance will fail if the affinity criteria cannot be met.
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.
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.