Skip to main content

Run your first instance

In this tutorial you set up tritonctl, the Triton Cloud tenant CLI, on your own machine. You sign in, choose the project you work in, register an SSH key, pick an image and a subnet, and create an instance. You end with a running instance and its IP address, then delete it.

Allow about 15 minutes.

Before you start​

You need four things:

  • tritonctl on your PATH. See Install tritonctl.
  • The URL of your cloud's API endpoint, plus a username and password for it.
  • The name of a project in your tenant.
  • A VPC in that project with at least one subnet.

Step 1: Check the binary​

On your workstation:

tritonctl --version

The command prints tritonctl and its version. If your shell reports that tritonctl is not found, the binary is not on your PATH yet. See Put tritonctl on your PATH.

Step 2: Sign in​

Run tritonctl configure with no flags:

tritonctl configure

The first prompt is Sign in with. Choose Username and password. The next prompt is Endpoint, which defaults to http://localhost:8080; enter your cloud's endpoint URL. Then enter your username at Username and your password at Password: , which does not echo what you type.

Output:

Configured. Logged in as <USERNAME> at <ENDPOINT>.
No project set. Pass --project on `configure` (or per command) to scope tenant reads.
Config written to <CONFIG_PATH>

<CONFIG_PATH> is triton/tritonctl/config.json inside your user configuration directory, for example ~/.config/triton/tritonctl/config.json on Linux. The file holds the endpoint and your session tokens.

Step 3: Set your project​

Instances belong to a project, and tritonctl needs to know which one. Store it once:

tritonctl configure --project <PROJECT_NAME>

Output:

Configured <ENDPOINT>.
Scoped to project <PROJECT_NAME> (<PROJECT_UUID>).
Config written to <CONFIG_PATH>

Every later command works in that project. Confirm who you are and where you are working:

tritonctl whoami

You should see output like:

endpoint:      <ENDPOINT>
...
project:       <PROJECT_NAME> (<PROJECT_UUID>)
...
principal:     <USERNAME> (user <USER_UUID>)
...

If the principal: line reads not available (no valid session), step 2 did not store a session. Run tritonctl configure again.

Step 4: Register your SSH key​

Register the public half of an SSH key pair so it is installed on the instance. This example uses an Ed25519 key:

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

The command prints the new key as key value lines, including id, name, and fingerprint. List your keys to confirm:

tritonctl ssh-key list

The table has two columns, FINGERPRINT and NAME, and a row for laptop.

Step 5: Pick an image​

List the images you can boot:

tritonctl image list

The table columns are SHORTID, NAME, VERSION, FLAGS, OS, SIZE, and PUBDATE. Choose the operating system you want and note its NAME. That is <IMAGE_NAME> in step 7. If more than one row has that name, write it as <IMAGE_NAME>@<VERSION>.

Step 6: Pick a subnet​

Your instance's primary network interface attaches to a subnet. List the subnets in your project:

tritonctl subnet list

The table columns are SHORTID, NAME, VPC, KIND, VLAN, SSH, and AGE. Note the NAME of the subnet you want. That is <SUBNET_NAME> in step 7.

Step 7: Create the instance​

On your workstation:

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

--memory 4G is 4 GiB. --wait keeps the command running until the instance is up, and prints each state as it changes:

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

The command then prints the instance record as key value lines. The line state.state running tells you it worked.

If the command ends with instance web-1 failed: followed by a reason, the instance did not come up. The reason says why.

Step 8: Find the instance's address​

List your instances:

tritonctl instance list

The table columns are SHORTID, NAME, IMG, STATE, FLAGS, and AGE. The web-1 row shows running under STATE.

Read its network interface:

tritonctl instance nics web-1

The table columns are SHORTID, NAME, MAC, IP, INSTANCE, and AGE. IP is the instance's IPv4 address on the subnet you chose.

Your instance is running.

Step 9: Clean up​

An instance must be stopped before you delete it. Stop it:

tritonctl instance stop web-1 --wait

The command returns once web-1 is stopped. Then delete it:

tritonctl instance delete web-1 --wait

The command prints what it is about to delete and asks:

This will make the following changes:
    delete instance web-1 (<SHORTID>), state stopped
Would you like to continue? [y/N]

Type y. The command prints web-1 is gone when the instance and its disks are deleted.

Next steps​