From 658e1b951dbf1fafbbaf22b9e57fd7c6752f62f5 Mon Sep 17 00:00:00 2001 From: mpana Date: Sat, 10 Feb 2018 17:42:58 +0200 Subject: [PATCH] updated readme --- README.md | 414 ++---------------------------------------------------- 1 file changed, 8 insertions(+), 406 deletions(-) diff --git a/README.md b/README.md index de48ff7..09acf5d 100644 --- a/README.md +++ b/README.md @@ -2,425 +2,27 @@ # node-spearhead -This repository is part of the Joyent Triton project. See the [contribution -guidelines](https://github.com/joyent/triton/blob/master/CONTRIBUTING.md) -- -*Triton does not use GitHub PRs* -- and general documentation at the main -[Triton project](https://github.com/joyent/triton) page. +This repository holds the node-spearhead CLI tool to work with the Spearhead 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. +## Installation and configuration -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/). +### Get a Spearhead Cloud account -**The `triton` CLI is currently in beta (effectively because it does not yet -have *complete* coverage of all commands from node-smartdc) 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). +Create an account on the Spearhead Cloud and upload your SSH key.[!TBD: docs]You can create an account [here](https://spearhead.cloud/). -### API endpoint +### Data-centers -Each data center has a single CloudAPI endpoint. For Joyent Public Cloud, you can find the -list of data centers [here](https://docs.joyent.com/public-cloud/data-centers). -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. +The list of available Spearhead Cloud data-centers is available [here](https://spearhead.cloud/datacenters). ### Installation Install [node.js](http://nodejs.org/), then: - npm install -g triton - -Verify that it is installed and on your PATH: - - $ triton --version - Triton CLI 4.15.0 - https://github.com/joyent/node-triton - -To use `triton`, you'll need to configure it to talk to a Triton DataCenter -API endpoint (called CloudAPI). Commonly that is done using a Triton profile: - - $ triton profile create - A profile name. A short string to identify a CloudAPI endpoint to the - `triton` CLI. - name: sw1 - - The CloudAPI endpoint URL. - url: https://us-sw-1.api.joyent.com - - Your account login name. - account: bob - - Available SSH keys: - 1. 2048-bit RSA key with fingerprint 4e:e7:56:9a:b0:91:31:3e:23:8d:f8:62:12:58:a2:ec - * [in homedir] bob-20160704 id_rsa - - The fingerprint of the SSH key you want to use, or its index in the list - above. If the key you want to use is not listed, make sure it is either saved - in your SSH keys directory or loaded into the SSH agent. - keyId: 1 - - Saved profile "sw1". - - WARNING: Docker uses TLS-based authentication with a different security model - from SSH keys. As a result, the Docker client cannot currently support - encrypted (password protected) keys or SSH agents. If you continue, the - Triton CLI will attempt to format a copy of your SSH *private* key as an - unencrypted TLS cert and place the copy in ~/.triton/docker for use by the - Docker client. - Continue? [y/n] y - Setting up profile "sw1" to use Docker. - Setup profile "sw1" to use Docker (v1.12.3). Try this: - eval "$(triton env --docker sw1)" - docker info - - Set "sw1" as current profile (because it is your only profile). - -Or instead of using profiles, you can set the required environment variables -(`triton` defaults to an "env" profile that uses these environment variables if -no profile is set). For example: - - TRITON_URL=https://us-sw-1.api.joyent.com - TRITON_ACCOUNT=bob - TRITON_KEY_ID=SHA256:j2WoSeOWhFy69BQ0uCR3FAySp9qCZTSCEyT2vRKcL+s - -For compatibility with the older [sdc-* tools from -node-smartdc](https://github.com/joyent/node-smartdc), `triton` also supports -`SDC_URL`, `SDC_ACCOUNT`, etc. environment variables. - - -### Bash completion - -Install Bash completion with - -```bash -triton completion > /usr/local/etc/bash_completion.d/triton # Mac -triton completion > /etc/bash_completion.d/triton # Linux -``` - -Alternatively, if you don't have or don't want to use a "bash\_completion.d" -dir, then something like this would work: - -```bash -triton completion > ~/.triton.completion -echo "source ~/.triton.completion" >> ~/.bashrc -``` - -Then open a new shell or manually `source FILE` that completion file, and -play with the bash completions: - - triton - - -## `triton` CLI Usage - -### Create and view instances - - $ triton instance list - SHORTID NAME IMG STATE PRIMARYIP AGO - -We have no instances created yet, so let's create some. In order to create -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 -SmartOS 64bit and a small 128M ram package which is a combo available on the -Joyent Public Cloud. - - $ triton instance create 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 instance create --name=server-1 ubuntu-14.04 t4-standard-2G - -Now list your instances again - - $ triton instance list - 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 - - -Get a quick overview of your account - - $ triton info - login: dave.eddy@joyent.com - name: Dave Eddy - email: dave.eddy@joyent.com - url: https://us-east-3b.api.joyent.com - totalDisk: 50.5 GiB - totalMemory: 2.0 MiB - instances: 2 - running: 1 - provisioning: 1 - -To obtain more detailed information of your instance - - $ triton instance get 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 b851ba9 - Last login: Wed Aug 26 17:59:35 2015 from 208.184.5.170 - __ . . - _| |_ | .-. . . .-. :--. |- - |_ _| ;| || |(.-' | | | - |__| `--' `-' `;-| `-' ' ' `-' - / ; Instance (base-64 15.2.0) - `-' https://docs.joyent.com/images/smartos/base - - [root@7db6c907-2693-42bc-ea9b-f38678f2554b ~]# uptime - 20:08pm up 2:27, 0 users, load average: 0.00, 0.00, 0.01 - [root@7db6c907-2693-42bc-ea9b-f38678f2554b ~]# logout - Connection to 165.225.169.63 closed. - -Or non-interactively - - $ triton ssh b851ba9 uname -v - joyent_20150826T120743Z - - -### Manage an instance - -Commonly used container operations are supported in the Triton CLI: - - $ triton help instance - ... - list (ls) List instances. - get Get an instance. - create Create a new instance. - delete (rm) Delete one or more instances. - - start Start one or more instances. - stop Stop one or more instances. - reboot Reboot one or more instances. - - ssh SSH to the primary IP of an instance - wait Wait on instances changing state. - audit List instance actions. - -### View packages and images - -Package definitions and images available vary between different data centers -and different Triton cloud implementations. - -To see all the packages offered in the data center and specific package -information, use - - $ triton package list - $ triton package get ID|NAME - -Similarly, to find out the available images and their details, do - - $ triton image list - $ triton images 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.) - - -## `TritonApi` Module Usage - -Node-triton can also be used as a node module for your own node.js tooling. -A basic example appropriate for a command-line tool is: - -```javascript -var mod_bunyan = require('bunyan'); -var mod_triton = require('triton'); - -var log = mod_bunyan.createLogger({name: 'my-tool'}); - -// See the `createClient` block comment for full usage details: -// https://github.com/joyent/node-triton/blob/master/lib/index.js -mod_triton.createClient({ - log: log, - // Use 'env' to pick up 'TRITON_/SDC_' env vars. Or manually specify a - // `profile` object. - profileName: 'env', - unlockKeyFn: mod_triton.promptPassphraseUnlockKey -}, function (err, client) { - if (err) { - // handle err - } - - client.listImages(function (err, images) { - client.close(); // Remember to close the client to close TCP conn. - if (err) { - console.error('listImages err:', err); - } else { - console.log(JSON.stringify(images, null, 4)); - } - }); -}); -``` - -See the following for more details: -- The block-comment for `createClient` in [lib/index.js](lib/index.js). -- Some module-usage examples in [examples/](examples/). -- The lower-level details in the top-comment in - [lib/tritonapi.js](lib/tritonapi.js). - - -## Configuration - -This section defines all the vars in a TritonApi config. The baked in defaults -are in "etc/defaults.json" and can be overriden for the CLI in -"~/.triton/config.json" (on Windows: "%APPDATA%/Joyent/Triton/config.json"). - -| Name | Description | -| ---- | ----------- | -| profile | The name of the triton profile to use. The default with the CLI is "env", i.e. take config from `SDC_*` envvars. | -| cacheDir | The path (relative to the config dir, "~/.triton") where cache data is stored. The default is "cache", i.e. the `triton` CLI caches at "~/.triton/cache". | - - -## node-triton differences with node-smartdc - -- There is a single `triton` command instead of a number of `sdc-*` commands. -- `TRITON_*` environment variables are preferred to the `SDC_*` environment - variables. However the `SDC_*` envvars are still supported. -- Node-smartdc still has more complete coverage of the Triton - [CloudAPI](https://apidocs.joyent.com/cloudapi/). However, `triton` is - catching up and is much more friendly to use. - - -## Development Hooks - -Before commiting be sure to, at least: - - make check # lint and style checks - make test-unit # run unit tests - -A good way to do that is to install the stock pre-commit hook in your -clone via: - - make git-hooks - -Also please run the full (longer) test suite (`make test`). See the next -section. - - -## Test suite - -node-triton has both unit tests (`make test-unit`) and integration tests (`make -test-integration`). Integration tests require a config file, by default at -"test/config.json". For example: - - $ cat test/config.json - { - "profileName": "east3b", - "allowWriteActions": true, - "image": "minimal-64", - "package": "g4-highcpu-128M", - "resizePackage": "g4-highcpu-256M" - } - -See "test/config.json.sample" for a description of all config vars. Minimally -just a "profileName" or "profile" is required. - -*Warning:* Running the *integration* tests will create resources and could -incur costs if running against a public cloud. - -Run all tests: - - make test - -You can use `TRITON_TEST_CONFIG` to override the test file, e.g.: - - $ cat test/coal.json - { - "profileName": "coal", - "allowWriteActions": true - } - $ TRITON_TEST_CONFIG=test/coal.json make test - -where "coal" here refers to a development Triton (a.k.a SDC) ["Cloud On A -Laptop"](https://github.com/joyent/sdc#getting-started) standup. - - -## Release process - -Here is how to cut a release: - -1. Make a commit to set the intended version in "package.json#version" and changing `## not yet released` at the top of "CHANGES.md" to: - - ``` - ## not yet released - - - ## $version - ``` - -2. Get that commit approved and merged via , as with all - commits to this repo. See the discussion of contribution at the top of this - readme. - -3. Once that is merged and you've updated your local copy, run: - - ``` - make cutarelease - ``` - - This will run a couple checks (clean working copy, versions in package.json - and CHANGES.md match), then will git tag and npm publish. + npm install -g spearhead +Now you ca use `spearhead` to interact with our Public Cloud. More details about installation and configuration are available [here](https://docs.spearhead.cloud). ## License