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. 🔒