Skip to main content

Create an instance

This guide creates an instance from an existing image with tritonctl, the tenant CLI, and waits until it is running.

Before you start, you need:

  • tritonctl signed in to your endpoint (tritonctl configure).
  • A project set for the CLI. Set one with tritonctl configure --project <PROJECT_NAME>, or pass --project on each command.
  • A VPC in that project with at least one subnet.

Every argument that names a resource accepts a name, a full UUID, or a UUID prefix. See Resource references.

Step 1: Register an SSH key​

On your workstation:

tritonctl ssh-key create --name workstation --public-key-file ~/.ssh/id_ed25519.pub

The command prints the new key's record as key value lines, including its id, name, and fingerprint. You pass the key's name to instance create as --ssh-key.

If you already registered a key, find its name with tritonctl ssh-key list.

Step 2: Pick an image​

List the images you can boot:

tritonctl image list

Pass the image to instance create by name, or as name@version when more than one version shares the name.

Step 3: Pick a subnet​

List the subnets in the project:

tritonctl subnet list

Add --vpc <VPC_NAME> to narrow the list to one VPC.

Step 4: Create the instance​

On your workstation:

tritonctl instance create \
  --name web-1 \
  --image <IMAGE_NAME> \
  --subnet <SUBNET_NAME> \
  --ssh-key workstation \
  --cpu 2 \
  --memory 4G \
  --wait

<IMAGE_NAME> and <SUBNET_NAME> are the names from the two lists above.

--wait keeps the command running until the instance is running, and prints each state change on stderr:

waiting for web-1: pending
waiting for web-1: provisioning
waiting for web-1: running

It then prints the instance record. The wait gives up after 15 minutes. Without --wait, the command returns as soon as the server has accepted the request, with the instance in pending.

To size the instance from a package in your silo's catalog instead of --cpu and --memory, pass --package <PACKAGE_NAME>. The two forms conflict. A package is a named CPU, memory, and disk configuration. Your silo's provisioning policy can allow one form, the other, or both.

Without --package and with no boot disk size, the boot disk is the image's size, with a 20 GiB floor for bhyve images. With --package, the package sets the boot disk size. Every flag, including replicated disks, is in the tritonctl instance create reference.

Step 5: Confirm the instance​

List the instances in the project:

tritonctl instance list

The STATE column reads running.

Read the instance's addresses:

tritonctl instance nics web-1

The IP column is the NIC's primary IPv4 address.

For the full record, pass -j:

tritonctl instance show web-1 -j

If the create fails​

Errors the server answers before it accepts the request:

ResponseCause
size the instance with --package, or with both --cpu and --memoryNeither --package nor both of --cpu and --memory. The CLI refuses this before it sends a request.
creating an instance needs a project; pass --project, or set one with `tritonctl configure --project` No project set.
400, cpu must be greater than zero--cpu 0.
400, memory_bytes must be greater than zero--memory 0.
400, disk_bytes must be greater than zero and at most 16 TiBA boot disk size of zero or above 16 TiB.
400, The boot disk must be at least <BYTES> bytes to hold the image.A boot disk smaller than the image.
403, free-form instance sizing is disabled by this silo's provisioning policy; select an available packageYour silo requires --package.
403, package-based instance sizing is disabled by this silo's provisioning policy; supply explicit dimensionsYour silo requires --cpu and --memory.
404The image, an SSH key, the subnet, or the project does not exist or is not visible to you. A subnet in another project also returns 404.
409, instance with name "web-1" already exists in project <PROJECT_UUID>Another instance in the project has that name.
409, This image cannot receive SSH keys or a password, so you could not sign in. ...The image has no channel for credentials. Choose another image.

Placement and provisioning run after the server accepts the request. A failure there leaves the instance in failed with a reason, and --wait ends with:

instance web-1 failed: <REASON>

When no compute node has capacity, the reason is No compute node has room for this instance right now. Try again later or choose a smaller package. A failed instance stays until you delete it, and it keeps its name in the project. Delete it before you retry with the same name.

danger

This deletes the instance and its disks. There is no undo. -y skips the confirmation prompt.

tritonctl instance delete web-1 -y --wait

Next steps​