Rethink interactive commands?

[carolynvs]

I was reading the PR for adding porter parameters generate (where we are considering adding branching logic to skip adding parameters or default them based on the values in the bundle) and realized that these interactive generation commands have become complicated and I'm not confident that they are the most helpful UX.

Due to limited terminal space, and a bug in the survey library that we use, we are trying to keep the questions as short as possible. When people really may need more documentation and context to understand what is going on.

A mistroke in the workflow means that you have to keep going and then start over or manually edit the file anyway.

We already have similar commands, which work differently:

• porter create generates a well commented porter.yaml with links to our documentation site, ready for the user to edit.
• porter credentials edit pops the user into their preferred editor to edit the credentials in YAML.

Before we keep doubling down on this UX (for parameters), and a codebase that honestly I am unconfident of every time I have to review (because of its interactive nature is difficult to automate testing), I'd like us to step back and think about our preferred UX for editing files. Is there a commonality between the porter.yaml, credentials/parameter sets, and eventually the porter user config file? What is a good way to create it and make it easy for the user to edit it while giving them support so that they understand the various configuration options available?

I'm leaning towards an apache-style config where we generate a well-commented file (perhaps with comented out config that doesn't yet apply), with links to our website that we provide commands to assist with listing, finding the file location and opening in an editor. Without the interactive prompts.

Are there other examples from existing tools that we like? Suggestions welcome!

[jeffersonbenson]

I would be in favor of generating a config file that is documented well enough that the user can type in their creds rather than the interactive menu. As fun as it is to have the menus be available, it would be much cleaner to have a flat-file for configuration.

[vdice]

I definitely agree that the interactive approach to creds/params/etc generation, while neat and handy for users, presents maintenance and testing issues that perhaps outweigh its benefits. I don't have strong opinions here and would support transitioning to non-interactive generation of well-documented cred/param sets as an alternative.

In the immediate term, I'd vote to merge #1078 (or some variant thereof, depending on code review), which achieves parity between both cred and param set generation (interactive). The work has already been done and this would ensure we at least have consistency between how these sets are generated. This would tide us over until the rework that develops out of this issue is ventured, which may or may not occur within the next few releases.

[squillace]

I like the interactive experience, but I see no reason whatsoever that it should be in porter itself. I'd much prefer it being a standalone tool or a VS Code thing or something else..... fwiw....

[carolynvs]

Here's the extra commands that we need to implement for this issue:

porter credentials create NAME [--reference REFERENCE] [--dry-run] [--output yaml|plain]
porter parameters create NAME [--reference REFERENCE] [--dry-run] [--output yaml|plain]

I realize that we used to have dry run on this command and I removed it years ago. 🤦‍♀️ We have since had a lot of feedback about how people want to use this command (to generate the file for use in CI, not saving it to Porter's storage). With this someone can generate a template with:

porter credentials create k8s -r example.com/kubernetes:v1.2.3 --dry-run -o json > k8s-creds.json

The saved file would look something like below. Even though credential sets are stored in Porter as json, since we wanted to add comments, I'm using yaml for the allowed output. Since CredentialSet and ParameterSet(?) are in cnab-go, we can use mapstructure's decoderconfig to tell it to use the json tags instead of looking for mapstructure tags.

---
# Generated by Porter
# Credentials generated from example.com/kubernetes:v1.2.3
schemaVersion: 1.0.0-DRAFT+b6c701f
# Name of the credential set
name: k8s
custom:
  bundleReference: example.com/kubernetes:v1.2.3
created: '2021-06-30T17:11:34.075214-05:00'
modified: '2021-06-30T17:11:34.075214-05:00'
credentials:
# kubeconfig applies to: All Actions
- name: kubeconfig
  source:
    # Replace the value field below with any of the following: secret, env, path, command or value
    value: TODO
# token applies to: install, upgrade
- name: token
  source:
    # Replace the value field below with any of the following: secret, env, path, command or value
    value: TODO

I am collecting a new custom value that I think will help people fill out these files, bundleReference, so that they can remember what bundle a credentialset came from.

[carolynvs]

$ porter credentials create foo ...
Created credential foo. Run porter credentials edit foo to customize it.
$ porter credentials edit foo
# opens vim/notepad

We may also want an import command too. TBD

[carolynvs]

We will keep the existing generate commands but avoid adding new features to them. 🔒

[vdice]

@carolynvs should we be good to close this ticket then, now that #1787 exists?

[carolynvs]

The two issues are about slightly different things. This one is about being able to generate a credential set/parameter set based on a bundle. It will iterate over what's defined in the bundle and make a template specifically for it. The other is about just helping you get a template file for making a resource from scratch.

I clarified on the other what the command should look like, and here's what this one should do now that we want two commands:

• create - just drops a template for the file onto the file system
• generate - make a resource based on the specified bundle

porter credential generate [FILE] --reference REFERENCE [-o yaml|json]

When a file is not specified, you get an interactive prompt that saves directly to Porter's database

$ porter credential generate --reference getporter/whalegap:v0.1.1
Name of the credential set [whalegap]: ?
Walks through setting each credential ...

Created credential set whalegap.

When a file is specified, we generate the file.

$ porter credential generate whalegap.yaml --reference getporter/whalegap:v0.1.1
Created credential whalegap.yaml. Run porter credentials apply whalegap.yaml to save it in Porter's database.

The NAME argument would be removed from the command (that's why it's a question now in the interactive prompt version above), and we would use FILE instead to switch between an interactive and silent version of the command.

[joshuabezaleel]

@carolynvs By saved in Porter's database do you mean that the file will be stored in the ~/.porter/credentials directory?

[carolynvs]

Porter has a pluggable backend datastore. In v0.38, we have plugins for storing data in the filesystem (in the ~/.porter directory), or in azure table storage. The datastore in the v1 prerelease is MongoDB, so it would store the credential in the credentials collection in mongo.

[joshuabezaleel]

@carolynvs Is this still in discussion or the decision that we are going with this direction (removing NAME from the current porter credentials generate command and use FILE instead) has been taken? I think I'm interested in this issue.

[carolynvs]

@joshuabezaleel I think we are still unsure if the interactive part of the command should stay or not. I really like the work you did in #1838, and am leaning towards making the generate command behave similarly, then getting rid of the interactive implementation entirely.

@vdice Care to weigh in on if you think there's large enough demand/value provided by the interactive part to justify keeping that complexity vs having our VS Code extension handle something like that instead?

[vdice]

👍 With the momentum behind creds/params creation thanks to @joshuabezaleel, I'm definitely comfortable with removing the interactive logic once creation is all in.

[carolynvs]

Let's keep generate since it does work and it useful to some people. But we can update our docs to encourage people to use create instead, or at least make sure people know that create exists now and is more script friendly.

[carolynvs]

A lot of our docs explain how to use porter credentials generate and porter parameters generate. Moving forward we want to encourage people to use the create and apply commands instead of the interactive ones.

We need to look through our quickstarts and docs to find where we are using generate and replace the instructions with asking them to create a file using the provided contents in the docs, and have them use the porter credentials apply or porter credentials apply command (like we do here). In the quickstarts, call out that you can make a new parameter or credential set file to get started with by running porter credentials create or porter parameters create, or use the interactive generate command to be prompted for each value.

[github-actions]

Closed by #2302.