README update to include more examples and background info
This commit is contained in:
Angela Fong
parent
9d314def3d
commit
c1dcef2f0f
193
README.md
193
README.md
|
|
@ -2,43 +2,79 @@
|
|||
|
||||
|
||||
|
||||
`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
|
||||
(<https://my.joyent.com>, <http://www.joyent.com/products/compute-service>).
|
||||
`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
|
||||
|
|
|
|||
Reference in New Issue