Improved UX for Plugin installation/uninstallation

[yizha1]

What is the areas you would like to add the new feature to?

Notation CLI

Is your feature request related to a problem?

For remote signing, users need to install a signing plugin into notation. Here is the current UX of plugin installation:

1. Download the plugin from the plugin vender repository
2. Figure out what is notation configuration directory based on the OS type
3. Make a directory named plugins under notation configuration directory
4. Make a sub-directory under plugins for the vendor plugin (of cause, users can use command mkdir -p)
5. Extract the plugin package (if needed) and copy the plugin file into directory created in step 4
6. Use command notation plugin ls to make sure the plugin is installed

It takes so many steps to just install a plugin, and it is also error prone since most steps are manual steps and user need to figure out the directory path accordingly.

What solution do you propose?

To improve the plugin installation UX and meet the timeline of v1.0 release. A phased approach is recommended. This issue only addressed the solution for the first phase.

The goal of the first phase is that users don't need to create directories, remember the names, and verify the installation using notation plugin ls. The solution is to introduce two new sub-commands for notation plugin:

• notation plugin --name <plugin name> import <plugin file>
• notation plugin delete <plugin name>

With that, the steps of plugin installation can be reduced to two steps

1. Users download the plugin from the plugin vendor repository.
2. Users execute command notation plugin import <plugin package>. The result of the execution indicates the success or failure of installation.

Users can easily delete plugin as well using just one command: notation plugin delete <plugin name>. If users forget the plugin name when deleting, users can use the existing command notation plugin ls to check the name.

What alternatives have you considered?

None

Any additional context?

No response

[yizha1]

Update to RC-3 milestone per community discussion on Configuration UX improvement

[duffney]

@yizha1 is there anyone actively working on this feature? If not, I'd like to start working on it. My team and I ran into this exact scenario where each of us were on a different OS and had to figure out how to install the plugins. Imo, adding this feature would greatly improve the user experience and I'd like to help. :)

[yizha1]

@duffney Great and your contributions are welcome! 👍

Currently it is not assigned to anyone yet. You can take it. Here are some steps we are now practicing on a feature development:

• Share the design/solution of the feature in the community.
• PRs to update the specification if it is necessary, for CLI command, we should update the specs under the directory. For this feature, it is plugin.md. I can work with you on the spec if you need any support on it.
• PRs for implementation

This feature is planned for rc.3, and the current target date is around the first week Apr. Let me know if you have further questions.

[duffney]

Awesome! I appreciate you sharing the timeline with me also. My next question is, what do you mean by "in the community"? Are you referring to posting the solution in the Slack community or as agenda item for a community call? Either way I'll get started with that and tag you in the PR for the plugin spec changes.

Thank you so much @yizha1 ! :)

[yizha1]

@duffney No problem.

WRT to the Share the design/solution of the feature in the community, you can choose the best way to do it as long as it is open discussed and tracked in GitHub. I saw some practices today. In some cases, the solution was discussed in the Github issue directly maybe due to size of feature or solution is small. In some cases, folks use hackmd.io to share and present the solution in the community call, especially for big size of solution or feature. It is a good practice to request an offline review first before presenting in the community call, and then, give a brief intro and address critical comments during community call. In this way we can improve the efficiency of review and save time for other people. Hope it helps, and you can decide the best way to do it.

[duffney]

That makes perfect sense, thank you for the explanation. Here's what I was thinking based on the information in the issue:

Solution: Improve the plugin installation user experience by adding two subcommands to the notation plugin command that install and delete plugins for the user when provided with the plugin package and or name.

• notation plugin install will create the necessary directories, remember plugin names, and verify the installation for notation plugins.
• notation plugin remove will remove a specific plugin from notation given the plugin name and delete the plugin package files.

I chose the words install and remove to match the list subcommand's wording. If import and delete are preferred, lmk. I don't have a strong opinion.

Please let me know if you think this size of issue warrants a hackmd.io post and community presentation.

[duffney]

Here's a link to the spec PR. If it's easier to collaborate outside the PR, please lmk. :)

[yizha1]

@priteshbandi @vaninrao10 @shizhMSFT @FeynmanZhou PTAL at Josh's proposal for this issue starting from this comment #549 (comment). If needed, we can invite Josh to the community meeting for further discussion.

[yizha1]

Move this feature to post v1 release.

[sajayantony]

Been having a chat with @toddysm about the challenges of installation right and it seems to be an challenging problem.
There are some opportunities to streamline plugin installation and I would like to recommend we provide a simpler experience.

For e.g.
Can we enable a brew install like semantics for plugins?

notation plugin install ghcr.io/wabbit-networks/notation-plugin@sha256:....

The goal of this to ensure that plugin installation is taken care of by an OCI artifact that will include the binary and also download and install the binary in the appropriate config location. Second it is digest verified and the binary executable blob can be verfiied against the manifest hash. Lastly if there is a signature attached with the plugin itself, notation can verify it at and we can implement this at a later phase.

[FeynmanZhou]

@sajayantony If the plugin file is packaged into an OCI artifact, then it can be downloaded and installed from an OCI registry. Plugin developers can sign and add SBOM to the OCI artifact type of plugin to ensure security and integrity in its distribution. I like this idea.

@notaryproject/notaryproject-notation-maintainers Could you take a look at this proposal? If we have an agreement on this proposal, I think the next step would be to update the Spec plugin-extensibility.md and related CLI spec to define the overall plugin conventions and CLI experience.

[yizha1]

LGTM

@duffney Please take a look at this proposal by @sajayantony . Since this issue is out of v1 scope now, we have more time, maybe we can aim at the final experience.

@FeynmanZhou I agree with your last comment, besides that, we also need to add user document for plugin on website.

[sajayantony]

Sharing an implementation by @noelbundick-msft ratify-project/ratify#519

[shizhMSFT]

notation plugin install should also support at least one local resource in case of airgapped networks.

notation plugin install <registry>/<repository>@<digest>          # remote source
notation plugin install --file <tarfile_path> --checksum <digest> # local source

[yizha1]

notation plugin install should also support at least one local resource in case of airgapped networks.

notation plugin install <registry>/<repository>@<digest>          # remote source
notation plugin install --file <tarfile_path> --checksum <digest> # local source

This is a really good point.

[yizha1]

Closed as completed by PR

• feat: notation plugin install command #827
• feat: add notation plugin uninstall command #842
• fix: notation plugin install error messages and tests #855