Test Secretless Connector Plugins

After you build and secure your plugin, the next step is to validate your plugin. You'll need to ensure that the connection established via the Secretless Broker operates in the same way as a direct connection — except that the client does not need to provide credentials.

General guidelines

The following sections provide general guidelines and tips for validating your plugin. Note that these are general guidelines only since the requirements for each environment can vary significantly.

1. Build your Secretless Connector Plugin

Build your Secretless Connector Plugin for the same target operating system as the Secretless binary that will consume your plugin following the instructions in Build the shared library file and then continue with Step 2 below.

If you're going to volume-mount the plugins into a Secretless container, it is highly likely that you'll need to build the plugin for Linux.

2. Set up the target service

Set up the target service and make sure it is network-accessible by both Secretless and your clients. This is necessary because the validation consists of ensuring direct connections and connections via Secretless are more or less the same.

3. Create a Secretless configuration

Create a Secretless configuration secretless.yml that uses your plugin (see Secretless Configuration).

4. Run Secretless

Run Secretless with the newly-created secretless.yml file, as follows:

./secretless-broker -f /path/to/secretless.yml -p /path/to/plugins/ -s PLUGINS_SHA256SUM.txt

Note the following:

In order for Secretless to incorporate the external plugin it must know its location; this is specified by the -p flag.
The plugin .so file must be available in the /path/to/plugins/ folder specified as the value to the -p flag.
By default Secretless, looks for plugins in /usr/local/lib/secretless .

5. Test your plugin

To confirm that there is no degradation in functionality, test your plugin against multiple clients to your target service. Repeat the steps for as many clients as you feel are appropriate for your environment.

We recommend that you run tests using at least two clients: a programming language (Go) client and a CLI client. We also recommend that you verify you are able to make a direct connection to the target service using each client and that each client is able to connect to the target service via Secretless, without supplying valid credentials.

6. Use supplied templates to create integration tests

Testing can be made more robust and repeatable by creating integration tests. To facilitate this, the Secretless repository contains the secretless-broker/examples/connector_templates/template_connector_test/ directory with templates to help you write integration tests for your plugin.

The templates include test scripts and files to help you stand up networked containers using docker-compose as the validation environment. The docker-compose.yml file contains one service each for Secretless, the Target Service, and Client/Tests.

Each file provides instructions on the steps that are required to set up your test suite, with areas that need your input clearly marked with TODO.

If you experience problems, it might be useful to use a tool like Wireshark for debugging.