Getting Started

Getting Started

If you choose to use node-triton or node-smartdc, be aware that they both require Node.js.

You can get Node.js from nodejs.org as source code, and as precompiled packages for Windows, Macintosh, Linux and Illumos distributions. Alternatively, when using a *nix, you can usually install Node.js using a package manager as well (e.g. pkgsrc, brew, apt-get, yum). The version of Node.js should be at least v0.10, so npm (Node.js's package manager) should come with it as well.

Once you've installed Node.js, to install node-triton invoke:

npm install -g triton

or, to install node-smartdc:

npm install -g smartdc

You will probably want to install json as well. It is a tool that makes it easier to work with JSON-formatted output. You can install it like this:

npm install -g json

In all cases above, the -g switch installs the tools globally, usually in /usr/local/bin, so that you can use them easily from the command line. Omit this switch if you'd rather the tools be installed in your home hierarchy, but you'll need to set your PATH appropriately.

Generate an SSH key

Both CLIs require an SSH key to communicate with CloudAPI, as well as logging-in to many instances.

If you haven't already generated an SSH key (required to use both SSH and HTTP Signing), run the following command:

ssh-keygen -b 2048 -t rsa -m PEM

This will prompt you with a place to save the key. You should probably just accept the defaults, as many programs (SSH and CloudAPI CLIs) will first look for a file called ~/.ssh/id_rsa. Before running the above command, ensure that ~/.ssh/id_rsa does not already exist; overwriting it may have unintended consequences.

Set Up your CLI

You need to set the following environment variables information in order to interact with CloudAPI using either node-triton or node-smartdc:

• SDC_URL: The URL of the CloudAPI endpoint.

• SDC_KEY_ID: Fingerprint for the key you uploaded to Triton.

• SDC_ACCOUNT: Your username; the login you use for Triton.

• SDC_USER: If authenticating as a subuser, the username of the subuser. See Role Based Access Control.

• SDC_TESTING: If using a self-signed SSL certificate, set this to 1.

An example for SDC_URL is https://us-west-1.api.joyent.com. Each datacenter in a cloud has its own CloudAPI endpoint; a different cloud that uses Triton would have a different URL.

In this document, we'll use api.example.com as the SDC_URL endpoint; please replace it with the URL of your datacenter(s). Note that CloudAPI always uses SSL/TLS, which means that the endpoint URL must begin with https.

You can quickly get your key fingerprint for SDC_KEY_ID by running:

ssh-keygen -l -f ~/.ssh/id_rsa.pub | awk '{print $2}' | tr -d '\n'

where you replace ~/.ssh/id_rsa.pub with the path to the public key you want to use for signing requests.

Working with the CLI

For a complete list of CloudAPI CLI commands available, please see Appendix C: CloudAPI CLI Commands.

To get help on a command, use the --help flag. For example:

triton datacenters --help
Show datacenters in this cloud.
A "cloud" is a set of related datacenters that share account
information.

Usage:
     triton datacenters

Options:
    -h, --help                Show this help.

  Output options:
    -H                        Omit table header row.
    -o field1,...             Specify fields (columns) to output.
    -s field1,...             Sort on the given fields. Default is "name".
    -j, --json                JSON output.

or

sdc-listdatacenters --help
sdc-listdatacenters [--account string] [--api-version string] [--debug boolean] [--help boolean] [--keyId string] [--url url] [--version boolean] [--verbose boolean] [--user string] [--role string]

You can set environment variables for the following flags so that you don't have to type them for each request (e.g. in your .bash_profile). All the examples in this document assume that these variables have been set:

CLI Flags	Description	Environment Variable
--account -a	Login name (account)	SDC_ACCOUNT
--user	Subuser name when using Role Based Access Control	SDC_USER
--keyId -k	Fingerprint of key to use for signing	SDC_KEY_ID
--url -u	URL of the CloudAPI endpoint	SDC_URL

Provision a new instance

To provision a new instance, you first need to get the ids for the image and package you want to use as the base for your instance.

An image is a snapshot of a filesystem and its software (for some types of container), or a disk image (for hardware virtual machines). You can get the list of available images using the triton image list or sdc-listimages commands; see the ListImages section below for a detailed explanation of these commands.

A package is a set of dimensions for the new instance, such as RAM and disk size. You can get the list of available packages using the triton package list or sdc-listpackages commands; see the ListPackages section below for a detailed explanation of these commands.

Once you have the package and image ids, to provision a new instance:

triton instance create $image $package

or

sdc-createmachine --image=$image --package=$package

For example:

triton instance create 2b683a82-a066-11e3-97ab-2faa44701c5a 64e23114-d502-c171-967f-b0e0cfb2009a
Creating instance 61dc8be (9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93, base@13.4.0, test_128)

You can use the --name flag to name your instance; if you do not specify a name, Triton will generate one for you. --image is the id of the image you'd like to use as the new instance's base. --package is the id of the package to use to set instance dimensions. For the triton command, you can also pass the name of the image or the package instead of their id.

Retrieve the status of your new instance by:

triton instance get $instance_id

or

sdc-getmachine $instance_id

For example:

triton instance get 9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93
{
    "id": "9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93",
    "name": "61dc8be",
    "type": "smartmachine",
    "brand": "joyent",
    "state": "running",
    "image": "2b683a82-a066-11e3-97ab-2faa44701c5a",
    "ips": [
        "10.88.88.56",
        "192.168.128.5"
    ],
    "memory": 128,
    "disk": 12288,
    "metadata": {
        "root_authorized_keys": "<...>"
    },
    "tags": {},
    "created": "2015-12-06T04:31:17.053Z",
    "updated": "2015-12-06T04:31:26.000Z",
    "networks": [
        "67f1232c-5b40-4693-8b55-560245984233",
        "05dcc9e2-8ae6-48d9-8222-25f64465693f"
    ],
    "primaryIp": "10.88.88.56",
    "firewall_enabled": false,
    "compute_node": "564d0b8e-6099-7648-351e-877faf6c56f6",
    "package": "test_128"
}

When you provision a new instance, the instance will take time to be initialized and booted; the state attribute will reflect this. Once the state attribute "running", you can login to your new instance (assuming it's a Unix-based instance), with the following:

ssh-add ~/.ssh/<key file>
$ ssh -A root@<new instance IP address>

These two commands set up your SSH agent (which has some magical properties, so you need to handle your SSH keys less often), and logs you in as the admin user on an instance. Note that the admin user has password-less sudo capabilities, so you may want to set up some less privileged users. The SSH keys on your account will allow you to login as root or admin on your new instance.

An alternative of using SSH directly is:

triton ssh <name of instance>

Now that we've done some basics with an instance, let's introduce a few concepts:

Images

By default, SmartOS images should be available to your for use. Your Triton cloud may have other images available as well, such as Linux or Windows images. The list of available images can be obtained with:

triton image list

or

sdc-listimages

For example:

triton image list
SHORTID   NAME            VERSION  FLAGS  OS       TYPE          PUBDATE
e1faace4  minimal-64-lts  15.4.1   P      smartos  zone-dataset  2016-03-03

Packages

You can list packages available in your cloud with:

triton package list

or

sdc-listpackages

For example:

 ./triton package list
SHORTID   NAME      DEFAULT  MEMORY  SWAP  DISK  VCPUS
64e23114  test_128  false      128M  256M   12G      1

Packages are the Triton name for the dimensions of an instance (how much CPU will be available, how much RAM, disk and swap, and so forth). Packages are provided so that you do not need to select individual settings, such as RAM or disk size.

Managing SSH keys

For instances which don't have a brand of kvm or bhyve (see triton instance list -o id,brand or sdc-listmachines), you can manage the SSH keys that allow logging into the instance via CloudAPI. For example, to rotate keys:

triton key add --name=my-other-rsa-key ~/.ssh/my_other_rsa_key.pub

or

sdc-createkey --name=my-other-rsa-key ~/.ssh/my_other_rsa_key.pub

The --name option sets the name of the key. If you don't provide one, CloudAPI sets it to the name of the file; in this case my_other_rsa_key.pub.

To use the new key, you will need to update the environment variables:

export SDC_KEY_ID=`ssh-keygen -l -f ~/.ssh/my_other_rsa_key.pub | awk '{print $2}' | tr -d '\n'`

At this point you could delete your other key from the system; see Cleaning Up for a quick example.

You cannot manage the SSH keys of instances with a brand of kvm or bhyve. Hardware virtual machines are static, and whatever keys were in your account at instance creation time are used, provided the OS inside KVM is a *nix.

Cleaning up

After going through this Getting Started section, you should now have at least one SSH key and one instance. The rest of the commands assume you have json installed.

Deleting Machines

To clean up an instance, you can use either:

triton instance delete $instance_id

or

sdc-deletemachine $instance_id

For example:

triton instance delete 9205af5b
Delete (async) instance 9205af5b (9205af5b-f2c0-ef07-e1f3-94bf1ff8fb93)

Deleting keys

Finally, you probably have one or two SSH keys uploaded to Triton after going through the guide, so to delete the one we setup:

triton key delete id_rsa

or

sdc-deletekey id_rsa