Add a porter explain command #646

jeremyrickard · 2019-09-24T19:52:56Z

Closes:

What does this change

This PR adds a new explain command that prints usage information for a bundle! Long gone are the days of trying to figure out how to use the bundle by running install until it works!

$ porter explain --tag jeremyrickard/porter-do-bundle:v0.4.1
Name: spring-music
Description: Run the Spring Music Service on Kubernetes and Digital Ocean PostgreSQL
Version: 0.4.1

Credentials:
+------------------+--------------------------------+----------+
|       NAME       |          DESCRIPTION           | REQUIRED |
+------------------+--------------------------------+----------+
| kubeconfig       | Kube config file with          | false    |
|                  | permissions to deploy app      |          |
| do_access_token  | Access Token for Digital Ocean | false    |
|                  | Account                        |          |
| do_spaces_key    | DO Spaces API Key              | false    |
| do_spaces_secret | DO Spaces API Secret           | false    |
+------------------+--------------------------------+----------+

Parameters:
+---------------+--------------------------------+---------+-------------------+----------+-------------+
|     NAME      |          DESCRIPTION           |  TYPE   |      DEFAULT      | REQUIRED | APPLIES TO  |
+---------------+--------------------------------+---------+-------------------+----------+-------------+
| node_count    | Number of database nodes       | integer | 1                 | false    | All Actions |
| porter-debug  | Print debug information from   | boolean | false             | false    | All Actions |
|               | Porter when executing the      |         |                   |          |             |
|               | bundle                         |         |                   |          |             |
| region        | Region to create Database and  | string  | nyc3              | false    | All Actions |
|               | DO Space                       |         |                   |          |             |
| space_name    | Name for DO Space              | string  | jrrportertest     | false    | All Actions |
| database_name | Name of database to create     | string  | jrrportertest     | false    | All Actions |
| helm_release  | Helm release name              | string  | spring-music-helm | false    | All Actions |
| namespace     | Namespace to install Spring    | string  | default           | false    | All Actions |
|               | Music app                      |         |                   |          |             |
+---------------+--------------------------------+---------+-------------------+----------+-------------+

Outputs:
+------------+--------------------------------+--------+-------------+
|    NAME    |          DESCRIPTION           |  TYPE  | APPLIES TO  |
+------------+--------------------------------+--------+-------------+
| service_ip | IP Address assigned to the     | string | All Actions |
|            | Load Balancer                  |        |             |
+------------+--------------------------------+--------+-------------+

No custom actions defined

This also provides support for json and yaml output.

An implementation note: I defined "Printable" types for this that only expose some of the fields of each type AND remove the omitempty on the json/yaml tags. I felt it was important to show values, even when they'd be omitted because they were "empty" (i.e. false...).

What issue does it fix

Closes #635

If there is not an existing issue, please make sure we have context on why this change is needed. See our Contributing Guide for examples of when an existing issue isn't necessary.

Notes for the reviewer

I added a new explain.go file, because bundle is getting rather large and I think I'd eventually like to explode this command more and support like an "explain" command on parameters or outputs themselves, like print the JSON schema in a useful format so you could leverage that info when crafting parameters.

Checklist

Unit Tests
Documentation

This PR adds a new `explain` command that prints usage information for a bundle Closes: getporter#635

vdice

Only one real code change question; other comment just a thought/brainstorm. Otherwise, LGTM!

vdice · 2019-09-24T22:37:45Z

pkg/porter/explain.go

+	if err != nil {
+		return err
+	}
+	err = p.ensureLocalBundleIsUpToDate(o.bundleFileOptions)


I'm thinking this call is not necessary, right? (Would re-build if bundle differed/out-of-date with local manifest.)

Actually, even though perhaps a main use case would be to explain a remote bundle, I can also see a use case for explaining a local bundle... in that scenario, we would want to ensure it'd be up-to-date. Therefore, seems we'd want to keep this!

Yeah, we for sure want to be able to use this on canonical JSON bundle files that are supper hard to read or a porter.yaml that people might have shared with others.

vdice · 2019-09-24T22:41:16Z

pkg/porter/explain.go

+
+	params := map[string]PrintableParameter{}
+	for p, v := range bun.Parameters {
+		def, ok := bun.Definitions[v.Definition]


Idea that this reminded me of whilst writin' similar code in Porter: We should add a helper func in cnab-go, GetDefinition(paramOrOutput) or some such (may need a function for each type), that'd return a parameter's/output's definition or return the corresponding error (not found/empty/etc.)

That’s a good idea. Do you want to file an issue for it?

Yuuuup cnabio/cnab-go#134

Thanks @vdice!

carolynvs

Looks great! Just some comments related to code consistency.

As a follow up, we should add this to the docs side bar
https://github.com/deislabs/porter/blob/7da5cffdf3581c27dfab03af88df2df005baa02d/docs/config.toml#L43-L47

cmd/porter/explain.go

pkg/porter/explain.go

carolynvs · 2019-09-25T15:38:01Z

pkg/porter/testdata/explain/expected-table-output.txt

@@ -0,0 +1,20 @@
+Name: HELLO


Is there supposed to be an emoji here? I see a square :/

GITHUB Y U NO HAVE STARSTUCK EMOJI!

jeremyrickard · 2019-09-26T01:22:31Z

Updated this to use our pkg/printer, new table format is thus:

$ porter explain --tag jeremyrickard/porter-do-bundle:v0.4.1
Name: spring-music
Description: Run the Spring Music Service on Kubernetes and Digital Ocean PostgreSQL
Version: 0.4.1

Credentials:
Name               Description                                       Required
do_access_token    Access Token for Digital Ocean Account            false
do_spaces_key      DO Spaces API Key                                 false
do_spaces_secret   DO Spaces API Secret                              false
kubeconfig         Kube config file with permissions to deploy app   false

Parameters:
Name            Description                                                     Type      Default             Required   Applies To
database_name   Name of database to create                                      string    jrrportertest       false      All Actions
helm_release    Helm release name                                               string    spring-music-helm   false      All Actions
namespace       Namespace to install Spring Music app                           string    default             false      All Actions
node_count      Number of database nodes                                        integer   1                   false      All Actions
porter-debug    Print debug information from Porter when executing the bundle   boolean   false               false      All Actions
region          Region to create Database and DO Space                          string    nyc3                false      All Actions
space_name      Name for DO Space                                               string    jrrportertest       false      All Actions

Outputs:
Name         Description                                Type     Applies To
service_ip   IP Address assigned to the Load Balancer   string   All Actions

No custom actions defined

carolynvs

LGTM 🚀

carolynvs · 2019-09-26T19:18:01Z

docs/config.toml

@@ -221,7 +221,11 @@ defaultContentLanguage = "en"
    identifier = "wiring"
    weight = 303
    parent = "authoring-bundles"
-
+[[menu.main]]


oh my gosh! I hope you didn't think that I was trying to say that you should write net new docs! I mean that's great that you did, I was just saying that you should link to the autogenerated docs for porter explain from the nav. Sorry about that if I was unclear. No worries, we can add the link in a follow-up.

oh i thought i added that one too :) sorrrry.

carolynvs · 2019-09-26T19:19:55Z

examples/kubernetes-mixin-example/porter.yaml

@@ -13,6 +13,11 @@ invocationImage: deislabs/porter-kubernetes:latest
 tag: deislabs/porter-kube-bundle:v0.1.0

 install:
+  - exec:


Did you intend to add this permanently to the example? Or was this accidentally included from our debugging session last night?

embarassed emoji.....

let me go clean that up :)

Add a porter explain command

9ab0fb9

This PR adds a new `explain` command that prints usage information for a bundle Closes: getporter#635

jeremyrickard requested review from carolynvs and vdice as code owners September 24, 2019 19:52

vdice approved these changes Sep 24, 2019

View reviewed changes

carolynvs requested changes Sep 25, 2019

View reviewed changes

Updated per review comments, added docs

edd4c06

s/rhe/the

e3b1622

carolynvs approved these changes Sep 26, 2019

View reviewed changes

carolynvs merged commit e70ea38 into getporter:master Sep 26, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a porter explain command #646

Add a porter explain command #646

jeremyrickard commented Sep 24, 2019 •

edited

Loading

vdice left a comment •

edited

Loading

vdice Sep 24, 2019

vdice Sep 24, 2019 •

edited

Loading

jeremyrickard Sep 24, 2019

vdice Sep 24, 2019

jeremyrickard Sep 24, 2019

vdice Sep 24, 2019

jeremyrickard Sep 25, 2019

carolynvs left a comment •

edited

Loading

carolynvs Sep 25, 2019

jeremyrickard Sep 26, 2019

carolynvs Sep 26, 2019

jeremyrickard commented Sep 26, 2019

carolynvs left a comment

carolynvs Sep 26, 2019

jeremyrickard Sep 26, 2019

carolynvs Sep 26, 2019

jeremyrickard Sep 26, 2019

jeremyrickard Sep 26, 2019

Add a porter explain command #646

Add a porter explain command #646

Conversation

jeremyrickard commented Sep 24, 2019 • edited Loading

What does this change

What issue does it fix

Notes for the reviewer

Checklist

vdice left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vdice Sep 24, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremyrickard commented Sep 26, 2019

carolynvs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeremyrickard commented Sep 24, 2019 •

edited

Loading

vdice left a comment •

edited

Loading

vdice Sep 24, 2019 •

edited

Loading

carolynvs left a comment •

edited

Loading