# Triton CLI tool ## Triton CLI tool The Triton command line tool (`triton`) uses CloudAPI to manage infrastructure in Triton data centers. Many of the tasks that you can perform through the portal are also possible with Triton CLI, including: * Provision compute instances, including infrastructure containers and hardware virtual machines * Manage compute instances, including Docker containers, infrastructure containers and hardware virtual machines * Provision and manage networks * Manage your account In this page, you will learn how to install `triton`. You can learn more about CloudAPI methods and resources [in our additional reference documentation](http://apidocs.joyent.com/cloudapi/). Need a visual reference? [Watch the screencast](#watch-to-learn) which covers how to install the Triton CLI tool and manage infrastructure in Triton data centers. ### [Installation](#installation) To install Triton CLI and CloudAPI tools, you must first install Node.js. You can find the latest version of Node.js for your operating system and architecture at [nodejs.org](http://nodejs.org/). You can install `triton` using Node Package Manager (`npm`). In the following example, the `npm` install command sets a global flag (`-g`) that makes `npm` modules accessible to all users. This flag is mandatory when installing `triton` on Windows. ``` $ sudo npm install -g triton . . . /usr/local/bin/triton -> /usr/local/lib/node_modules/triton/bin/triton triton@4.11.0 /usr/local/lib/node_modules/triton ├── bigspinner@3.1.0 ├── assert-plus@0.2.0 ├── extsprintf@1.0.2 ├── wordwrap@1.0.0 ├── strsplit@1.0.0 ├── node-uuid@1.4.3 ├── read@1.0.7 (mute-stream@0.0.6) ├── semver@5.1.0 ├── vasync@1.6.3 ├── once@1.3.2 (wrappy@1.0.2) ├── backoff@2.4.1 (precond@0.2.3) ├── verror@1.6.0 (extsprintf@1.2.0) ├── which@1.2.4 (isexe@1.1.2, is-absolute@0.1.7) ├── cmdln@3.5.4 (extsprintf@1.3.0, dashdash@1.13.1) ├── lomstream@1.1.0 (assert-plus@0.1.5, extsprintf@1.3.0, vstream@0.1.0) ├── mkdirp@0.5.1 (minimist@0.0.8) ├── sshpk@1.7.4 (ecc-jsbn@0.1.1, jsbn@0.1.0, asn1@0.2.3, jodid25519@1.0.2, dashdash@1.13.1, tweetnacl@0.14.3) ├── rimraf@2.4.4 (glob@5.0.15) ├── tabula@1.7.0 (assert-plus@0.1.5, dashdash@1.13.1, lstream@0.0.4) ├── smartdc-auth@2.3.0 (assert-plus@0.1.2, once@1.3.0, clone@0.1.5, dashdash@1.10.1, sshpk@1.7.1, sshpk-agent@1.2.0, vasync@1.4.3, http-signature@1.1.1) ├── restify-errors@3.0.0 (assert-plus@0.1.5, lodash@3.10.1) ├── bunyan@1.5.1 (safe-json-stringify@1.0.3, mv@2.1.1, dtrace-provider@0.6.0) └── restify-clients@1.1.0 (assert-plus@0.1.5, tunnel-agent@0.4.3, keep-alive-agent@0.0.1, lru-cache@2.7.3, mime@1.3.4, lodash@3.10.1, restify-errors@4.2.3, dtrace-provider@0.6.0) ``` **NOTE**: on some platforms and for some installations of Node.js, you may receive an error when using `sudo`. Remove it from the command to install `triton`: ``` $ npm install -g triton ``` ### [Environment variables](#environment-variables) We recommend setting up environment variables to populate an initial environment-based profile. These environment variables are useful for interacting with CloudAPI as well as other tools such as Packer and Terraform. On Windows, this step is mandatory. #### [Add environment variables on macOS](#add-environment-variables-on-macos) Environment variables live in your bash profile, `.bash_profile`. On macOS, this file should be in your home directory. From the terminal, edit your bash profile: ``` $ vi .bash_profile ``` Add the following content to your profile, modified to include the correct Triton username and SSH key if not `id_rsa.pub`: ``` export TRITON_PROFILE="env" export TRITON_URL="https://us-central-1.api.mnx.io" export TRITON_ACCOUNT="" unset TRITON_USER export TRITON_KEY_ID="$(ssh-keygen -l -f $HOME/.ssh/id_rsa.pub | awk '{print $2}')" unset TRITON_TESTING unset TRITON_PROFILE ``` Previous versions of `triton` required environment variables that began with `SDC_*`, i.e. `SDC_URL` and `SDC_ACCOUNT`. As of January 2018, the SDC environment variables are still supported by `triton`. If you've installed `smartdc`, you must [set up `SDC_*` environment variables](https://apidocs.joyent.com/cloudapi/#set-up-your-cli). ### [Configuring Triton profiles](#configuring-triton-profiles) Triton CLI uses "profiles" to store access information. Profiles contain the data center CloudAPI URL, your login name, and SSH key fingerprint. You can create a profile for each data center or profiles for different users. Profiles make it easy to connect to different data centers, or connect to the same data center as different users. The `triton profile create` command prompts you to answer a series of questions to configure your profile. The following example shows the steps for Triton user `jill`. ``` $ triton profile create A profile name. A short string to identify a CloudAPI endpoint to the `triton` CLI. name: us-central-1 The CloudAPI endpoint URL. url: https://us-central-1.api.mnx.io Your account login name. account: myuser The fingerprint of the SSH key you have registered for your account. You may enter a local path to a public or private key to have the fingerprint calculated for you. keyId: ~/.ssh/.id_rsa Fingerprint: 2e:c9:f9:89:ec:78:04:5d:ff:fd:74:88:f3:a5:18:a5 Saved profile "us-central-1" ``` Select a CloudAPI endpoint URL from any of our [global data centers](https://docs.mnx.io/data-centers), or use a Triton-powered data center of your own (remember: [it's open source](https://github.com/joyent/sdc)). To test the installation and configuration, let's use `triton info`: ``` $ triton info login: myuser name: MyUser Example email: myuser@example.com url: https://us-central-1.api.mnx.io totalDisk: 22.1 GiB totalMemory: 2.0 GiB instances: 2 running: 2 ``` The `triton info` output above shows that myuser's account already has two instances running. ### [Using profiles](#using-profiles) You can view all configured profiles with the `triton profiles` command: ``` $ triton profiles NAME CURR ACCOUNT USER URL us-central-1 * myuser - https://us-central-1.api.mnx.io ``` Next let's make a profile for each data center. To do this we will use `triton` commands to make a copy of the `us-sw-1` profile for each of the data center urls. Copy this snippet below to add the new profiles (in this case, based on a profile named 'env'): ``` triton datacenters | egrep -v NAME | while read -r i; do name=$(echo $i | awk {'print $1'}); url=$(echo $i | awk {'print $2'}); triton profile get -j env | sed -e "s/env/$name/" -e "s#http[^\"]*#$url#" | triton profile create -f - -y; done ``` Run `triton profiles` again to check to see that it worked. We should have a new profile for each data center listed in `triton datacenters`: ``` $ triton profiles NAME CURR ACCOUNT USER URL us-central-1 myuser - https://us-central-1.api.mnx.io ``` You can change the default profile with the `triton profile set` command: ``` $ triton profile set us-central-1 Set "us-central-1" as current profile ``` ### [Completions](#completions) You can also [configure bash completions](https://github.com/joyent/node-triton#bash-completion) with this command: ``` # Mac OSX $ triton completion > /usr/local/etc/bash_completion.d/triton # Linux $ triton completion > /etc/bash_completion.d/triton # Windows bash shell $ triton completion >> ~/.bash_completion ``` ### [Quick start: create an instance](#quick-start-create-an-instance) With `triton` installed and configured, we can jump right into provisioning instances. Here's an example of provisioning an infrastructure container running Ubuntu. Think of infrastructure containers like virtual machines, only faster and more efficient. Let's run `triton instance create` and we'll talk about the pieces after: ``` $ triton instance create -w --name=server-1 ubuntu-14.04 g4-highcpu-1G Creating instance server-1 (e9314cd2-e727-4622-ad5b-e6a6cac047d4, ubuntu-14.04@20160114.5, g4-highcpu-1G) Created instance server-1 (e9314cd2-e727-4622-ad5b-e6a6cac047d4) in 22s ``` Now that we have an instance, we can run `triton ssh` to connect to it. This is an awesome addition to our tools because it means that we don't need to copy SSH keys or even lookup the IP address of the instance. ``` $ triton ssh server-1 Welcome to Ubuntu 14.04 (GNU/Linux 3.19.0 x86_64) * Documentation: https://help.ubuntu.com/ The programs included with the Ubuntu system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. __ . . _| |_ | .-. . . .-. :--. |- |_ _| ;| || |(.-' | | | |__| `--' `-' `;-| `-' ' ' `-' / ; Instance (Ubuntu 14.04 20151105) `-' https://docs.joyent.com/images/container-native-linux root@8367b339-799b-cff5-a662-a211e1927797:~# ``` ### [Instance creation options and details](#instance-creation-options-and-details) In our quick start example, we ran `triton instance create -w --name=server-1 ubuntu-14.04 g4-highcpu-1G`. That command has three parameters: 1. We gave our instance a name using `--name server-1` 2. We used `-w` to wait the instance to be created 3. We used `ubuntu-14.04` as our image 4. We set `g4-highcpu-1G` as our package Let's look at each of those in detail to see how you can set the options that will work best for your needs. #### [Specifying the instance name](#specifying-the-instance-name) Names for instances can be up to 189 characters and include any alphanumeric character plus `_`, `-`, and `.` #### [Selecting an image](#selecting-an-image) Finding our Ubuntu image is pretty easy. We use `triton images` to list the images and add `name=~ubuntu` to do a substring search for Ubuntu. It's sorted by published date so usually we'll pick the most recent. Today we'll choose 14.04 because it has wider support. ``` $ triton images name=~ubuntu type=lx-dataset SHORTID NAME VERSION FLAGS OS TYPE PUBDATE ... c8d68a9e ubuntu-14.04 20150819 P linux lx-dataset 2015-08-19 52be84d0 ubuntu-14.04 20151005 P linux lx-dataset 2015-10-05 ffe82a0a ubuntu-15.04 20151105 P linux lx-dataset 2015-11-05 ``` **Note**: Want to build a custom application using our infrastructure containers? Learn how to [create a custom ifrastructure image](https://docs.joyent.com/public-cloud/instances/infrastructure/images/creating#commandlinetools). #### [Selecting a package](#selecting-a-package) There are 4 types of packages available for containers: compute optimized (`g4-highcpu-`), general purpose (`g4-general-`), memory optimized (`g4-highram-`), and storage optimized (`g4-fastdisk-` and `g4-bigdisk-`). The package types for [HVMs](https://docs.mnx.io/api/broken-reference) have a similar name structure: compute optimized (`k4-highcpu--`), general purpose (`k4-general--`), memory optimized (`k4-highram--`), and storage optimized (`k4-fastdisk--` and `k4-bigdisk--`). We'll use `triton package` to search for a package with 1 gigabyte of RAM. We'll pick the `g4-highcpu-1G`. ``` $ triton packages memory=1024 SHORTID NAME MEMORY SWAP DISK VCPUS 14af2214 g4-highcpu-1G 1G 4G 25G - ``` At this time, there is no way to use `triton` to fetch the pricing details for the different packages. To find out those costs, you can visit our [public pricing page](https://www.joyent.com/pricing/cloud/compute). ### [Watch to learn](#watch-to-learn) This screencast covers how to install the Triton CLI tool and use CloudAPI to manage infrastructure in Triton data centers. If you skipped ahead to the video, you can go back and review the [installation process](#installation) for step-by-step instructions. ### [Bootstrapping an instance with a script](#bootstrapping-an-instance-with-a-script) Our quick start example didn't include one of the most useful options for automating infrastructure on Triton: specifying a script for containers to run at startup. The command below sets up a 16GB CentOS infrastructure container, and installs Couchbase. The `--script` file installs Couchbase, and the `triton ssh` runs `cat /root/couchbase.txt` to show the address of the Couchbase dashboard. ``` curl -sL -o couchbase-install-triton-centos.bash https://raw.githubusercontent.com/misterbisson/couchbase-benchmark/master/bin/install-triton-centos.bash triton instance create \ --name=couch-bench-1 \ $(triton images name=~centos-6 type=lx-dataset -Ho id | tail -1) \ 'Large 16GB' \ --wait \ --script=./couchbase-install-triton-centos.bash triton ssh couch-bench-1 'cat /root/couchbase.txt' ``` Infrastructure management isn't just about creating instances. Triton CLI offers some of its biggest improvements in this space. Below are some examples of `triton` commands. #### [List instances](#list-instances) ``` $ triton instances SHORTID NAME IMG STATE PRIMARYIP AGO 1fdc4b78 couch-bench-1 8a1dbc62 running 165.225.136.140 3m 8367b039 server-1 ubuntu-14.04@20151005 running 165.225.122.69 3m ``` #### [Wait for tasks](#wait-for-tasks) By default the `triton` tool does not wait for tasks to finish. This is great because it means that your commands return control back to you very quickly. However sometimes you'll need to wait for a task to complete before you do the next one. When this happens you can wait by using either the `--wait` or `-w` flags, or the `triton instance wait` command. In the example above we used `--wait` so that the instance would be ready by the time the `triton ssh` command ran. #### [Show instance details](#show-instance-details) Use `triton instance get -j` to view your instance's details as a JSON blob. To parse fields out of the blob, I recommend using [json](https://github.com/trentm/json) although there are many other great tools out there. ``` $ triton instance get -j couch-bench-1 { "id": "1fdc4b78-62ec-cb97-d7ff-f99feb8b3d2a", "name": "couch-bench-1", "type": "smartmachine", "state": "running", "image": "82cf0a0a-6afc-11e5-8f79-273b6aea6443", "ips": [ "165.225.136.140", "10.112.2.230" ], "memory": 16384, "disk": 409600, "metadata": { "user-script": "#!/bin/bash\n...\n\n", "root_authorized_keys": "ssh-rsa ..." }, "tags": {}, "created": "2015-12-18T03:44:42.314Z", "updated": "2015-12-18T03:45:10.000Z", "networks": [ "65ae3604-7c5c-4255-9c9f-6248e5d78900", "56f0fd52-4df1-49bd-af0c-81c717ea8bce" ], "dataset": "82cf0a0a-6afc-11e5-8f79-273b6aea6443", "primaryIp": "165.225.136.140", "firewall_enabled": false, "compute_node": "44454c4c-4400-1059-804e-b5c04f383432", "package": "g4-general-16G" } ``` Up above you can see that the `user-script` that we ran is part of the metadata. You can pull out individual values by piping the output to `json KEYNAME`. For example you could get the IP address of an instance like this: ``` $ triton instance get -j couch-bench-1 | json primaryIp 165.225.136.140 ``` #### [Clean up](#clean-up) Let's wrap up with this container. We'll delete it using the `triton instance delete` command: ``` $ triton instance delete server-1 couch-bench-1 Delete (async) instance server-1 (8367b039-759b-c6f5-a6c2-a210e1926798) Delete (async) instance couch-bench-1 (1fdc4b78-62ec-cb97-d7ff-f99feb8b3d2a) ``` For something a bit more dangerous, you can delete all your instances using this command: ``` $ triton instance delete $(triton instances -Ho shortid) ``` Be careful. Using the `triton instance delete` command removes all of your instances regardless of whether they running or stopped. If you are familiar with using `docker`, note that this is equivalent to using `docker rm -f $(docker ps -aq)` to force the deletion of all your containers. If you want to remove all of your instances, using `triton instance delete` might be faster since it deletes the instances in parallel. ### [CloudAPI and Triton Elastic Docker Host](#cloudapi-and-triton-elastic-docker-host) In addition to CloudAPI and the Triton CLI tool, you can also create and manage bare metal Docker containers on Triton using the Triton Elastic Docker Host and Triton-Docker CLI tools. The two APIs work in parallel, though the Triton-Docker CLI can *only* create and manage bare metal Docker containers on Triton. CloudAPI and the Triton CLI tool can manage almost every aspect of Docker containers with the exception of provisioning bare metal Docker containers on Triton.