Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add guide for managing plugins #219

Merged
merged 1 commit into from
Jun 21, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
76 changes: 76 additions & 0 deletions content/en/docs/how-to/plugin-management.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
title: Install and manage notation plugins
description: Install and manage notation plugins
weight: 9
---

Plugins for `notation` provide functionality and integration with key stores and signing services. For example:
- The [notation-azure-kv](https://github.com/Azure/notation-azure-kv) plugin allows you to sign a Notation-generated payload with a private key in [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/general/overview?wt.mc_id=azurelearn_inproduct_oss_notaryproject).
- The [AWS Signer plugin for Notation](https://docs.aws.amazon.com/signer/latest/developerguide/image-signing-prerequisites.html) lets you sign and verify images using Notation with keys and certificates managed by [AWS Signer](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html), a signing service.

## Install a plugin

To install a plugin, download the plugin binary, create a `{plugin-name}` directory in `{NOTATION_LIBEXEC}/plugins/`, and add the plugin binary to that directory. Alternatively, if you are using an application that bundles a plugin and the `notation` binary together, such as [AWS Signer](https://docs.aws.amazon.com/signer/latest/developerguide/image-signing-prerequisites.html), see the installation instructions from the vendor.

{{% alert title="Warning" color="warning" %}}
iamsamirzon marked this conversation as resolved.
Show resolved Hide resolved
Before creating the `{plugin-name}` directory, confirm you are using a name that follows the [naming structure](#plugin-naming-structure) for plugins. Plugins that do not follow the naming structure will not be recognized by `notation`.
{{% /alert %}}

The following example downloads and installs version 0.6.0 of [notation-azure-kv](https://github.com/Azure/notation-azure-kv) plugin for on macOS with Apple Silicon using the default location for the Notation installation.
zr-msft marked this conversation as resolved.
Show resolved Hide resolved

{{% alert title="Warning" color="warning" %}}
The following example only works for version 0.6.0 of the *notation-azure-kv* plugin on macOS with Apple Silicon using the default location for the Notation installation. You will need to update the filenames, location, and commands for other plugins, versions, and platforms. For more details on the default location of that directory on each platform, see [Notation directory structure for system configuration]({{< ref "/docs/concepts/directory-structure" >}}).
{{% /alert %}}

```console
toddysm marked this conversation as resolved.
Show resolved Hide resolved
curl -Lo notation-azure-kv_0.6.0_darwin_arm64.tar.gz "https://github.com/Azure/notation-azure-kv/releases/download/v0.6.0/notation-azure-kv_0.6.0_darwin_arm64.tar.gz"
mkdir -p ~/Library/Application\ Support/notation/plugins/azure-kv
tar xvzf notation-azure-kv_0.6.0_darwin_arm64.tar.gz -C ~/Library/Application\ Support/notation/plugins/azure-kv notation-azure-kv
```

To confirm you plugin is installed, run `notation plugin list`. For example:

```console
notation plugin list
```

Confirm the plugin is listed in the output. For example:

```console
$ notation plugin list
NAME DESCRIPTION VERSION CAPABILITIES ERROR
azure-kv Sign artifacts with keys in Azure Key Vault 0.6.0 [SIGNATURE_GENERATOR.RAW] <nil>
com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.290 [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] <nil>
```
zr-msft marked this conversation as resolved.
Show resolved Hide resolved

## Uninstall a plugin

To remove a plugin, delete the entire `{NOTATION_LIBEXEC}/plugins/{plugin-name}/` directory.

To confirm your plugin is uninstalled, run `notation plugin list`. For example:

```console
notation plugin list
```

FeynmanZhou marked this conversation as resolved.
Show resolved Hide resolved
## Plugin naming structure

The `notation` CLI strictly follows the [Notary Project specification for plugins](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-mechanism). This includes the naming structure for the plugin binary and the plugin directory. All plugins must be named `notation-{plugin-name}` and placed in the `{NOTATION_LIBEXEC}/plugins/{plugin-name}/` directory. Also, you can't modify the filename of the plugin binary from the `tar.gz` file when installing a plugin.

For example, the full path to the [notation-azure-kv](https://github.com/Azure/notation-azure-kv) plugin is `{NOTATION_LIBEXEC}/plugins/azure-kv/notation-azure-kv`.

If the plugin name or plugin directory does not match the naming structure or the plugin name is altered, `notation` will not recognize the plugin.

## Security best practices for plugins
zr-msft marked this conversation as resolved.
Show resolved Hide resolved
zr-msft marked this conversation as resolved.
Show resolved Hide resolved

Plugins are binaries that run on your host and can receive sensitive information from `notation` such as signatures, private keys, and payload data. As a result, it is strongly recommended that you follow these security best practices when using plugins:

- Ensure that you only download plugins and their checksums from known, trusted sources
- When available, use checksum verification or signature verification to confirm the plugin binary is not corrupted

## Available plugins

The following plugins are currently available for `notation`:

- [AWS Signer](https://docs.aws.amazon.com/signer/latest/developerguide/image-signing-prerequisites.html) plugin for Notation. For more details on using this plugin for sign and verify images, see [Notation with AWS Signer](https://aws.amazon.com/blogs/containers/announcing-container-image-signing-with-aws-signer-and-amazon-eks/)
- [notation-azure-kv](https://github.com/Azure/notation-azure-kv). For more details on using this plugin, see [Sign a Notation-generated payload with a certificate in Azure Key Vault](https://learn.microsoft.com/azure/container-registry/container-registry-tutorial-sign-build-push?wt.mc_id=azurelearn_inproduct_oss_notaryproject).
zr-msft marked this conversation as resolved.
Show resolved Hide resolved