From c1dcef2f0ff5d898dc6e1864cc354c09d85f4e28 Mon Sep 17 00:00:00 2001 From: Angela Fong Date: Tue, 8 Sep 2015 12:04:30 -0700 Subject: [PATCH] README update to include more examples and background info --- README.md | 193 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 146 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 10731e9..080158e 100644 --- a/README.md +++ b/README.md @@ -2,43 +2,79 @@ ![logo](https://www.joyent.com/content/01-home/triton-logo.svg) -`triton` is a CLI tool for Joyent's Triton (a.k.a. SmartDataCenter), either for -on-premises installations of Triton or Joyent's Public Cloud -(, ). +`triton` is a CLI tool for working with the CloudAPI for Joyent's Triton [Public Cloud] +(https://docs.joyent.com/public-cloud) and [Private Cloud] (https://docs.joyent.com/private-cloud). +CloudAPI is a RESTful API for end users of the cloud to manage their accounts, instances, +networks, images, and to inquire other relevant details. CloudAPI provides a single view of +docker containers, infrastructure containers and hardware virtual machines available in the +Triton solution. -**This project aims to replace -[node-smartdc](https://github.com/joyent/node-smartdc) as both the API -client library for triton ([cloudapi](https://apidocs.joyent.com/cloudapi/)) -and the command line tool** +There is currently another CLI tool known as [node-smartdc](https://github.com/joyent/node-smartdc) +for CloudAPI. `node-smartdc` CLI works off the 32-character object UUID to uniquely +identify object instances in API requests, and returns response payload in JSON format. +The CLI covers both basic and advanced usage of [CloudAPI](https://apidocs.joyent.com/cloudapi/). -## Installation +As a lightweight programmable interface for CloudAPI, the `triton` CLI supports both name or +UUID identification of object instances and the use of short ID, as well as the choice +between concise tabular responses and full JSON responses. **The `triton` CLI is currently in +beta and will be expanded over time to support all CloudAPI commands, eventually replacing +`node-smartdc` as both the API client library for Triton cloud and the command line tool.** + +## Setup + +### User accounts, authentication, and security + +Before you can use the CLI you'll need an account on the cloud to which you are connecting and +an SSH key uploaded. The SSH key is used to identify and secure SSH access to containers and +other resources in Triton. + +If you do not already have an account on Joyent Public Cloud, sign up [here](https://www.joyent.com/public-cloud). + + +### API endpoint + +Each data center has a single CloudAPI endpoint. For Joyent Public Cloud, you can find the +list of datacenters [here](https://docs.joyent.com/public-cloud/api-access/cloudapi#datacenter-urls). +For private cloud implementations, please consult the private cloud operator for the correct URL. +Have the URL handy as you'll need it in the next step. + + +### Installation 1. Install [node.js](http://nodejs.org/). 2. `npm install -g git://github.com/joyent/node-triton` -Verify it installed and is on your PATH: +Verify that it is installed and on your PATH: $ triton --version - joyent-triton 1.0.0 + Triton CLI 1.0.0 -## Setup - -Before you can use the CLI you'll need a Joyent account, an SSH key uploaded -and `triton` configured with those account details. - -1. Create a Joyent Public Cloud account here https://www.joyent.com/public-cloud -2. Upload an SSH key (instructions on the site above) -3. Set the proper environmental variables (instructions also above) - -Example environmental variables +Configure the proper environmental variables that correspond to the API endpoint and account, +for example: SDC_URL=https://us-east-3b.api.joyent.com SDC_ACCOUNT=dave.eddy@joyent.com SDC_KEY_ID=04:0c:22:25:c9:85:d8:e4:fa:27:0d:67:94:68:9e:e9 + +### Bash completion + +You can quickly source `triton` bash completions in your current +shell with: + + source <(triton completion) + +For a more permanent installation: + + triton completion >> ~/.bashrc + + # Or maybe: + triton completion > /usr/local/etc/bash_completion.d/triton + + ## Example -List instances +### Create and view instances $ triton instances SHORTID NAME IMG STATE PRIMARYIP AGO @@ -48,10 +84,24 @@ an instance we need to specify two things: an image and a package. An image represents what will be used as the root of the instances filesystem, and the package represents the size of the instance, eg. ram, disk size, cpu shares, etc. More information on images and packages below - for now we'll just use -a basic combo of SmartOS 64bit and a small 128M ram package. +SmartOS 64bit and a small 128M ram package which is a combo available on the +Joyent Public Cloud. + $ triton create-instance base-64 t4-standard-128M + +Without a name specified, the container created will have a generated ID. Now +to create a container-native Ubuntu 14.04 container with 2GB of ram with the +name "server-1" + + $ triton create-instance --name=server-1 ubuntu-14.04 t4-standard-2G + +Now list your instances again + + $ triton instances + SHORTID NAME IMG STATE PRIMARYIP AGO + 7db6c907 b851ba9 base-64@15.2.0 running 165.225.169.63 9m + 9cf1f427 server-1 ubuntu-14.04@20150819 provisioning - 0s -### XXX 1. show create, 2. show instances again, 3. show ssh'ing in, 4. explain images and packages Get a quick overview of your account @@ -60,25 +110,50 @@ Get a quick overview of your account name: Dave Eddy email: dave.eddy@joyent.com url: https://us-east-3b.api.joyent.com - totalDisk: 8.5 GiB - totalMemory: 366.2 MiB - instances: 3 - running: 2 - stopped: 1 + totalDisk: 50.5 GiB + totalMemory: 2.0 MiB + instances: 2 + running: 1 + provisioning: 1 -See running instances +To obtain more detailed information of your instance - $ triton instances - ID NAME STATE TYPE IMG MEMORY DISK AGO - 908a781b-e4c8-4291-dcf5-b0fcbcc0cb8a machine-1 stopped smartmachine 5c7d0d24-3475-11e5-8e67-27953a8b237e 128 3072 2h - 7807f369-79eb-ebe9-85f6-db3017a75f0f machine-2 running smartmachine 5c7d0d24-3475-11e5-8e67-27953a8b237e 128 3072 2h - a2d537b4-feb1-c530-f1ff-e034eb73adaa machine-3 running smartmachine 5c7d0d24-3475-11e5-8e67-27953a8b237e 128 3072 2h - 7db6c907-2693-42bc-ea9b-f38678f2554b machine-4 running smartmachine 5c7d0d24-3475-11e5-8e67-27953a8b237e 128 3072 2h - 8892b12f-60e9-c4ba-f0f8-a4ca9714ea9c machine-5 running smartmachine 5c7d0d24-3475-11e5-8e67-27953a8b237e 128 3072 2h + $ triton instance server-1 + { + "id": "9cf1f427-9a40-c188-ce87-fd0c4a5a2c2c", + "name": "251d4fd", + "type": "smartmachine", + "state": "running", + "image": "c8d68a9e-4682-11e5-9450-4f4fadd0936d", + "ips": [ + "165.225.169.54", + "192.168.128.16" + ], + "memory": 2048, + "disk": 51200, + "metadata": { + "root_authorized_keys": "(...ssh keys...)" + }, + "tags": {}, + "created": "2015-09-08T04:56:27.734Z", + "updated": "2015-09-08T04:56:43.000Z", + "networks": [ + "feb7b2c5-0063-42f0-a4e6-b812917397f7", + "726379ac-358b-4fb4-bb7c-8bc4548bac1e" + ], + "dataset": "c8d68a9e-4682-11e5-9450-4f4fadd0936d", + "primaryIp": "165.225.169.54", + "firewall_enabled": false, + "compute_node": "44454c4c-5400-1034-8053-b5c04f383432", + "package": "t4-standard-2G" + } + + +### SSH to an instance Connect to an instance over SSH - $ triton ssh machine-4 + $ triton ssh b851ba9 Last login: Wed Aug 26 17:59:35 2015 from 208.184.5.170 __ . . _| |_ | .-. . . .-. :--. |- @@ -94,29 +169,53 @@ Connect to an instance over SSH Or non-interactively - $ triton ssh machine-4 uname -v + $ triton ssh b851ba9 uname -v joyent_20150826T120743Z -## Bash completion +### Manage an instance -You can quickly source `triton` bash completions in your current -shell with: +Commonly used container operations are supported in the Triton CLI. +More operations will be added to the list over time. - source <(triton completion) + $ triton help + ... + instance-audit List instance actions. + start-instance (start) Start a single instance. + stop-instance (stop) Stop a single instance. + reboot-instance (reboot) Reboot a single instance. + delete-instance (delete) Delete a single instance. + wait-instance (wait) Wait on instances changing state. + ... -For a more permanent installation: +### View packages and images - triton completion >> ~/.bashrc +Packages definitions and images available vary between different datacenters +and different Triton cloud implementation. - # Or maybe: - triton completion > /usr/local/etc/bash_completion.d/triton +To see all the packages offered in the datacenter and specific package information, use + + $ triton packages + $ triton package ID|NAME + +Similarly, to find out the available images and their details, do + + $ triton images + $ triton image ID|NAME + +Note that docker images are not shown in `triton images` as they are +maintained in Docker Hub and other third-party registries configured to be +used with Joyent's Triton clouds. **In general, docker containers should be +provisioned and managed with the regular [`docker` CLI](https://docs.docker.com/installation/#installation) +(Triton provides an endpoint that represents the *entire datacenter* +as a single `DOCKER_HOST`. See the [Triton Docker +documentation](https://apidocs.joyent.com/docker) for more information.) ## node-triton differences with node-smartdc - There is a single `triton` command instead of a number of `sdc-*` commands. -- The `SDC_USER` envvar is accepted in preference to `SDC_ACCOUNT`. +- The `SDC_USER` env variable is accepted in preference to `SDC_ACCOUNT`. ## cloudapi2.js differences with node-smartdc/lib/cloudapi.js