From 77d17e445a103e41886f80c82d5c6d1eb74157e4 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Tue, 21 Nov 2023 07:59:21 +0800 Subject: [PATCH] doc: update plugin spec (#809) Signed-off-by: Feynman Zhou --- specs/commandline/plugin.md | 101 +++++++++++++++++++++++++++++------- 1 file changed, 82 insertions(+), 19 deletions(-) diff --git a/specs/commandline/plugin.md b/specs/commandline/plugin.md index be34979ef..9cfdea42e 100644 --- a/specs/commandline/plugin.md +++ b/specs/commandline/plugin.md @@ -2,7 +2,7 @@ ## Description -Use `notation plugin` to manage plugins. See notation [plugin documentation](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. The `notation plugin` command by itself performs no action. In order to operate on a plugin, one of the subcommands must be used. +Use `notation plugin` to manage plugins. See notation [plugin documentation](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md) for more details. The `notation plugin` command by itself performs no action. In order to manage notation plugins, one of the subcommands must be used. ## Outline @@ -15,9 +15,9 @@ Usage: notation plugin [command] Available Commands: + install Install a plugin list List installed plugins - install Installs a plugin - remove Removes a plugin + uninstall Uninstall a plugin Flags: -h, --help help for plugin @@ -41,51 +41,114 @@ Aliases: ### notation plugin install ```text -Installs a plugin +Install a plugin Usage: - notation plugin install [flags] + notation plugin install [flags] <--file|--url> Flags: - -h, --help help for install - -f, --force force the installation of a plugin + -d, --debug debug mode + --file install plugin from a file in file system + --force force the installation of a plugin + -h, --help help for install + --sha256sum string must match SHA256 of the plugin source + --url install plugin from an HTTPS URL + -v, --verbose verbose mode Aliases: install, add ``` -### notation plugin remove +### notation plugin uninstall ```text -Removes a plugin +Uninstall a plugin Usage: - notation plugin remove [flags] + notation plugin uninstall [flags] Flags: -h, --help help for remove - + -y, --yes do not prompt for confirmation Aliases: - remove, rm, uninstall, delete + uninstall, remove, rm ``` ## Usage -### Install a plugin +## Install a plugin + +### Install a plugin from file system + +Install a Notation plugin from file system. Plugin file supports `.zip` and `.tar.gz` format. The checksum validation is optional for this case. ```shell -notation plugin install +$ notation plugin install --file +``` + +Upon successful execution, the plugin is copied to Notation's plugin directory. If the plugin directory does not exist, it will be created. The name and version of the installed plugin are displayed as follows. + +```console +Successfully installed plugin , version +``` + +If the entered plugin checksum digest doesn't match the published checksum, Notation will return an error message and will not start installation. + +```console +Error: failed to install the plugin: plugin checksum does not match user input. Expecting +``` + +If the plugin version is higher than the existing plugin, Notation will start installation and overwrite the existing plugin. + +```console +Successfully installed plugin , updated the version from to +``` + +If the plugin version is equal to the existing plugin, Notation will not start installation and return the following message. Users can use a flag `--force` to skip plugin version check and force the installation. + +```console +Error: failed to install the plugin: with version already exists. +``` + +If the plugin version is lower than the existing plugin, Notation will return an error message and will not start installation. Users can use a flag `--force` to skip plugin version check and force the installation. + +```console +Error: failed to install the plugin: . The installing plugin version is lower than the existing plugin version . +It is not recommended to install an older version. To force the installation, use the "--force" option. ``` +### Install a plugin from URL -Upon successful execution, the plugin is copied to plugins directory and name+version of plugin is displayed. If the plugin directory does not exist, it will be created. When an existing plugin is detected, the versions are compared and if the existing plugin is a lower version then it is replaced by the newer version. +Install a Notation plugin from a remote location and verify the plugin checksum. Notation only supports installing plugins from an HTTPS URL, which means that the URL must start with "https://". + +```shell +$ notation plugin install --sha256sum --url +``` ### Uninstall a plugin ```shell -notation plugin remove +notation plugin uninstall +``` + +Upon successful execution, the plugin is uninstalled from the plugin directory. + +```shell +Are you sure you want to uninstall plugin ""? [y/n] y +Successfully uninstalled +``` + +Uninstall the plugin without prompt for confirmation. + +```shell +notation plugin uninstall --yes ``` -Upon successful execution, the plugin is removed from the plugins directory. If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. +If the plugin is not found, an error is returned showing the syntax for the plugin list command to show the installed plugins. + +```shell +Error: unable to find plugin . +To view a list of installed plugins, use "notation plugin list" +``` ### List installed plugins @@ -99,6 +162,6 @@ An example of output from `notation plugin list`: ```text NAME DESCRIPTION VERSION CAPABILITIES ERROR -azure-kv Sign artifacts with keys in Azure Key Vault v0.5.0-rc.1 [SIGNATURE_GENERATOR.RAW] -com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.290 [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] +azure-kv Sign artifacts with keys in Azure Key Vault v1.0.0 Signature generation +com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.290 Signature envelope generation, Trusted Identity validation, Certificate chain revocation check ```