Plugins

Waypoint can be extended using custom plugins. Waypoint supports custom builders, deployment platforms, registries, release managers, and more. This allows you to extend the Waypoint workflow and featureset anywhere. This page will focus on using plugins. To learn more about how to write plugins, see the Extending Waypoint guide.

Waypoint ships with dozens of built-in plugins. These plugins are available out-of-the-box with Waypoint and are built directly on the same plugin system as external plugins. To see a list of supported plugins, see the integrations library.

Available Plugins

You can see a list of all built-in plugins in our integrations library.

We maintain a list of external plugins here, and we plan to incorporate them into our integrations library in the future.

Using an External Plugin

External plugins are distributed as executable binaries. To use an external plugin, you must download the correct binary for your operating system, place it at the correct location, and use it within your waypoint configuration.

Installing an External Plugin - Local Operations

To install an external plugin, the binary must first be named waypoint-plugin-<name> where <name> is the same label that is used with the use stanza in your Waypoint configuration. For the example below, our binary must be named waypoint-plugin-hashicloud. If you're on Windows, the binary must end in ".exe".

app {
  # ...

  deploy {
    use "hashicloud" {}
  }
}

Once the plugin is named, it must be copied into the correct location. Waypoint will look for plugins in the following locations in the following order:

1. In the same directory as the waypoint.hcl file.
2. In ./.waypoint/plugins/ relative to the waypoint.hcl file.
3. In $XDG_CONFIG_HOME/waypoint/plugins

Once a plugin is found, it will not search the later paths.

Installing an External Plugin - Remote Operations

In order to use a custom plugin with remote operations, the plugin must be built-in to the Docker image used for the on-demand runner profile configured to execute your remote operations. The default on-demand runner image, hashicorp/waypoint-odr:latest, contains only the plugins which are built-in to the Waypoint binary. To add a custom plugin, you may extend this image to add your own plugin:

FROM hashicorp/waypoint-odr:latest

COPY ./waypoint-plugin-myplugin $HOME/.config/waypoint/plugins/waypoint-plugin-myplugin

How to configure your runner profile to use the new image is detailed here.

Troubleshooting

If you're seeing waypoint init errors that a plugin cannot be found, run waypoint init with the -vv flag and look for the line that says "plugin search path". This will list the search path that Waypoint is using for finding your plugins.

If the path isn't correct, this is usually due to unset environment variables (typically XDG_CONFIG_HOME). Please verify these are set properly and try again.

2020-10-17T11:32:12.743-0700 [DEBUG] waypoint.runner: plugin search path: job_id=01EMVXARPMVCPYWE4FPECZY30B path=[, .waypoint/plugins, /Users/mitchellh/.config/waypoint/plugins]

Using the External Plugin

The external plugin is used in the same manner as a built-in plugin. Continuing our example above, you can use an external plugin with a use stanza. The existence of a use stanza with a plugin name will notify Waypoint that it requires that plugin.

app {
  # ...

  deploy {
    use "hashicloud" {}
  }
}

Checksumming

You can also use the explicit plugin stanza to define plugins.

This stanza provides additional functionality when loading plugins. The most important is that you can specify a SHA-256 checksum for the plugin binary which helps prevent tampering with the plugin binary.

Verify

To verify the plugin works, run waypoint init against your project. This will find the plugin, load it, and also validate any configuration.

Authoring a Plugin

To write a plugin, see the Extending Waypoint guide.