joyent/node-triton#35 More easily distinguish KVM and LX and Docker images and instances

Also support filtering insts on docker=true.

CHANGES.md

@@ -1,8 +1,49 @@
 # node-triton changelog
 
-## 4.0.2 (not yet released)
+## 4.1.0 (not yet released)
 
-(nothing yet)
+- #35 More easily distinguish KVM and LX and Docker images and instances.
+
+    In PUBAPI-1161 CloudAPI (v8.0.0) started exposing IMG.type, INST.brand and
+    INST.docker. One of the main issues for users is that telling KVM ubuntu
+    from LX ubuntu is confusing (see also joyent/smartos-live#532).
+
+    tl;dr:
+
+    - `triton image list` default output now includes the `type` instead of
+      `state`. The `state` column is still in output with `-l`, `-j`,
+      `-o state`.
+    - `triton instance list` default output now includes a `flags` column
+      instead of `primaryIp`. The 'D' and 'K' flags identify Docker and KVM
+      instances.
+    - `triton instance list -l` includes the brand.
+
+    Default output examples showing the various cases (and the attempt to
+    stay within 80 columns):
+
+    ```bash
+    $ triton imgs
+    SHORTID   NAME            VERSION   FLAGS  OS       TYPE          PUBDATE
+    1bd84670  minimal-64-lts  14.4.2    P      smartos  zone-dataset  2015-05-28
+    b67492c2  base-64-lts     14.4.2    P      smartos  zone-dataset  2015-05-28
+    ffe82a0a  ubuntu-15.04    20151105  P      linux    lx-dataset    2015-11-05
+    8a1dbc62  centos-6        20160111  P      linux    zvol          2016-01-11
+
+    $ triton insts
+    SHORTID   NAME         IMG                    STATE    FLAGS  AGE
+    da7c6edd  cocky_noyce  3d996aaa               running  DF     10m
+    deedeb42  ubu0         ubuntu-15.04@20151105  running  -      9m
+    aa9ccfda  mini2        minimal-64-lts@14.4.2  running  -      9m
+    e8fc0b96  centi0       centos-6@20160111      running  K      8m
+    ```
+
+- Filtering instances on `docker=true`:
+
+    ```bash
+    $ triton insts docker=true
+    SHORTID   NAME         IMG       STATE    FLAGS  AGE
+    da7c6edd  cocky_noyce  3d996aaa  running  DF     13m
+    ```
 
 
 ## 4.0.1

lib/do_image/do_list.js

@@ -5,7 +5,7 @@
  */
 
 /*
- * Copyright 2015 Joyent, Inc.
+ * Copyright 2016 Joyent, Inc.
  *
  * `triton image list ...`
  */
@@ -28,10 +28,10 @@ var validFilters = [
 ];
 
 // columns default without -o
-var columnsDefault = 'shortid,name,version,state,flags,os,pubdate';
+var columnsDefault = 'shortid,name,version,flags,os,type,pubdate';
 
 // columns default with -l
-var columnsDefaultLong = 'id,name,version,state,flags,os,pubdate';
+var columnsDefaultLong = 'id,name,version,state,flags,os,type,pubdate';
 
 // sort default with -s
 var sortDefault = 'published_at';
@@ -69,9 +69,6 @@ function do_list(subcmd, opts, args, callback) {
         }
 
         if (opts.json) {
-            // XXX we should have a common method for all these:
-            //      XXX sorting
-            //      XXX if opts.o is given, then filter to just those fields?
             common.jsonStream(imgs);
         } else {
             // Add some convenience fields
@@ -125,33 +122,35 @@ do_list.options = [
     sortDefault: sortDefault
 }));
 
-do_list.help = (
+do_list.help = [
     /* BEGIN JSSTYLED */
-    'List images.\n' +
+    'List images.',
-    '\n' +
+    '',
-    'Usage:\n' +
+    'Usage:',
-    '    {{name}} list [<options>] [<filters>]\n' +
+    '    {{name}} list [<options>] [<filters>]',
-    '\n' +
+    '',
-    '{{options}}' +
+    '{{options}}',
-    '\n' +
+    'Filters:',
-    'Filters:\n' +
+    '    FIELD=VALUE        Equality filter. Supported fields: account, owner,',
-    '    FIELD=VALUE        Field equality filter. Supported fields: \n' +
+    '                       state, name, os, and type.',
-    '                       account, owner, state, name, os, and type.\n' +
+    '    FIELD=true|false   Boolean filter. Supported fields: public.',
-    '    FIELD=true|false   Field boolean filter. Supported fields: public.\n' +
+    '    FIELD=~SUBSTRING   Substring filter. Supported fields: name',
-    '    FIELD=~SUBSTRING   Field substring filter. Supported fields: name\n' +
+    '',
-    '\n' +
+    'Fields (most are self explanatory, "*" indicates a field added client-side',
-    'Fields (most are self explanatory, the client adds some for convenience):\n' +
+    'for convenience):',
-    '    shortid            A short ID prefix.\n' +
+    '    shortid*           A short ID prefix.',
-    '    flags              This is a set of single letter flags\n' +
+    '    flags*             Single letter flags summarizing some fields:',
-    '                       summarizing some fields. "P" indicates the\n' +
+    '                           "P" image is public',
-    '                       image is public. "I" indicates an incremental\n' +
+    '                           "I" an incremental image (i.e. has an origin)',
-    '                       image (i.e. has an origin). "X" indicates an\n' +
+    '                           "X" has a state *other* than "active"',
-    '                       image with a state *other* than "active".\n' +
+    '    pubdate*           Short form of "published_at" with just the date',
-    '    pubdate            Short form of "published_at" with just the date\n' +
+    '    pub*               Short form of "published_at" elliding milliseconds.',
-    '    pub                Short form of "published_at" elliding milliseconds.\n' +
+    '    size*              The number of bytes of the image file (files.0.size)',
-    '    size               The number of bytes of the image file (files.0.size)\n'
+    '    type               The image type. As of CloudAPI 8.0 this is defined by',
+    '                       <https://images.joyent.com/docs/#manifest-type>. Before',
+    '                       that it was one of "smartmachine" or "virtualmachine".'
     /* END JSSTYLED */
-);
+].join('\n');
 
 do_list.aliases = ['ls'];
 

lib/do_instance/do_list.js

@@ -5,7 +5,7 @@
  */
 
 /*
- * Copyright 2015 Joyent, Inc.
+ * Copyright 2016 Joyent, Inc.
  *
  * `triton instance list ...`
  */
@@ -17,22 +17,26 @@ var vasync = require('vasync');
 var common = require('../common');
 
 
-
+/*
-// to be passed as query string args to /my/machines
+ * Filters to be passed as query string args to /my/machines.
+ * See <https://apidocs.joyent.com/cloudapi/#ListMachines>.
+ */
 var validFilters = [
+    'type',
+    'brand',  // Added in CloudAPI 8.0.0
     'name',
     'image',
     'state',
     'memory',
-    'tombstone',
+    'docker'  // Added in CloudAPI 8.0.0
-    'credentials'
 ];
 
 // columns default without -o
-var columnsDefault = 'shortid,name,img,state,primaryIp,ago';
+var columnsDefault = 'shortid,name,img,state,flags,age';
 
 // columns default with -l
-var columnsDefaultLong = 'id,name,img,package,state,primaryIp,created';
+var columnsDefaultLong
+    = 'id,name,img,brand,package,state,flags,primaryIp,created';
 
 // sort default with -s
 var sortDefault = 'created';
@@ -107,14 +111,17 @@ function do_list(subcmd, opts, args, callback) {
         });
 
         // Add extra fields for nice output.
-        // XXX FWIW, the "extra fields" for images and packages are not added
-        //     for `opts.json`. Thoughts? We should be consistent there. --TM
         var now = new Date();
         insts.forEach(function (inst) {
             var created = new Date(inst.created);
-            inst.ago = common.longAgo(created, now);
+            inst.age = common.longAgo(created, now);
-            inst.img = imgmap[inst.image] || inst.image;
+            inst.img = imgmap[inst.image] || common.uuidToShortId(inst.image);
             inst.shortid = inst.id.split('-', 1)[0];
+            var flags = [];
+            if (inst.docker) flags.push('D');
+            if (inst.firewall_enabled) flags.push('F');
+            if (inst.brand === 'kvm') flags.push('K');
+            inst.flags = flags.length ? flags.join('') : undefined;
         });
 
         if (opts.json) {
@@ -142,14 +149,32 @@ do_list.options = [
     sortDefault: sortDefault
 }));
 
-do_list.help = (
+do_list.help = [
-    'List instances.\n'
+    /* BEGIN JSSTYLED */
-    + '\n'
+    'List instances.',
-    + 'Usage:\n'
+    '',
-    + '     {{name}} list [<filters>...]\n'
+    'Usage:',
-    + '\n'
+    '     {{name}} list [<filters>...]',
-    + '{{options}}'
+    '',
-);
+    '{{options}}',
+    'Filters:',
+    '    FIELD=VALUE        Equality filter. Supported fields: type, brand, name,',
+    '                       image, state, memory, and tag',
+    '    FIELD=true|false   Boolean filter. Supported fields: docker (added in',
+    '                       CloudAPI 8.0.0)',
+    '',
+    'Fields (most are self explanatory, "*" indicates a field added client-side',
+    'for convenience):',
+    '    shortid*           A short ID prefix.',
+    '    flags*             Single letter flags summarizing some fields:',
+    '                           "D" docker instance',
+    '                           "F" firewall is enabled',
+    '                           "K" the brand is "kvm"',
+    '    age*               Approximate time since created, e.g. 1y, 2w.',
+    '    img*               The image "name@version", if available, else its',
+    '                       "shortid".'
+    /* END JSSTYLED */
+].join('\n');
 
 do_list.aliases = ['ls'];
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "triton",
   "description": "Joyent Triton CLI and client (https://www.joyent.com/triton)",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "author": "Joyent (joyent.com)",
   "dependencies": {
     "assert-plus": "0.2.0",