Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Build and Load BYOI Custom Plug-in Images

To send data to Paragon Insights using Bring Your Own Ingest (BYOI) custom plug-ins, you must code the input plug-in and create a plug-in ingest image file with a shell script and a process file. The ingest image also contains a Kubernetes YAML file for the ingest container. Paragon Insights executes the shell script when configurations of the BYOI ingest and device group (mapped to the ingest) change. The Kubernetes YAML file contains configurations that instruct the Kubernetes engine to start and to stop the service for a BYOI plugin ingest.

The workflow to build and load the BYOI custom plug-in image is as follows:

  1. Create an ingest image to write data to the Paragon Automation database and a shell script for configuration updates.

  2. Tag the image file and export the image as a compressed tar file.

    See Tag and Export the BYOI Custom Plugin Image for commands to tag and export the image file.

  3. Modify the Kubernetes Jinja template to create a YAML file for the Kubernetes container pod. The container pod is where the BYOI ingest is deployed in Paragon Insights.

    See Configure Kubernetes YAML File for a sample Kubernetes Jinja template file.

  4. Assign a different IP address if you want the BYOI plugin to be accessible for external applications.

    See (Optional) Assign Virtual IP Address to Plugin for a Kubernetes Jinja template in which you can assign a custom virtual IP address for the BYOI plug-in.

  5. Load the compressed tar file and Kubernetes YAML file to the Paragon Insights primary node.

    See Load the BYOI Custom Plugin to load the BYOI plug-in image file and the Kubernetes YAML file.

Use JSON Configuration File Attributes in Ingest Image

You can create a Python file, such as the following example file, and include it in the BYOI plug-in image. When you run the image in a Kubernetes container, Paragon Insights executes the Python file. The following sample Python file uses the attributes described in Table 1 to send a key (a random integer between 0 and 9 in the example file) for the measurement (topic/rule/sensor_name/byoi) to the database.

In the Python file, use the following URL format to send data to Paragon Insights.

The entry in the database (db) field must follow the syntax database-name:device-group-name:device-name.

The line protocol (post body) contains a string in the following format.

When you create an instance of a custom BYOI plug-in, a JavaScript Object Notation (JSON) configuration file is attached inside the Kubernetes container for the BYOI ingest instance. The JSON configuration file contains information such as the device, device group, sensor path, hostname, and port of the backend service to which ingest data is sent. You can go through the JSON configuration using /etc/byoi/config.json for all the available attributes.

Table 1 lists several key attributes in the JSON configuration file.

Table 1: Attributes in the JSON Configuration File



How to Access Attributes


Host name of the backend service to which the plug-in sends the ingest data.

Environment Variable $TAND_HOST


Port number of the backend service to which the plug-in sends the ingest data.

Environment Variable $TAND_PORT


Name of database where the ingest data is stored.

The value for this attribute differs for each Paragon Insights node.



Measurement of database in line protocol. See the InfluxDB documentation to learn more about measurement.

For example, topic/rule/sensor_name/byoi.

The value of sensor_name differs from sensor to sensor.



Metric-value pairs, separated by comma without space.

For example, cpu_usage=50,memory_utilization=12.



Unix Epoch timestamp in nanoseconds.



Encoded password of the device that receives the streaming data.

See Decode Device Password for decoding device password.


Decode Device Password

The JSON configuration file can contain encoded sensitive information such as the password of the device that streams data.

To decode the data, you can initiate a POST call using the API api-server:9000/api/v2/junos-decode inside the plugin container, with the encoded data in the post body.

The following sample POST call decodes an encoded password present in the JSON configuration file.

Create a Shell Script for Configuration Updates

When the BYOI ingest image configuration or the Paragon Insights device group configuration changes, the JSON configuration file is updated. When there is a change in configuration, Paragon Insights must re-read the configuration file by invoking the shell script located at /jfit_scripts/ When you build the ingest plugin image, you can name your shell script and copy the script to /jfit_scripts/ folder.

In the shell script, you can send a SIGHUP signal to the main process or simply kill old processes and start new ones. The following example shell script sends a SIGHUP signal to the main plug-in process:

Tag and Export the BYOI Custom Plugin Image

After you build the custom plugin, you must tag the plug-in image and export it as a tar file. You can tag the plug-in image in the healthbot_plugin_name:your_version format. The plug-in image must be exported as a compressed tar file using the following command:

docker save tag -o healthbot_plugin_name.tar.gz

Configure Kubernetes YAML File

The Kubernetes Jinja template file has the basic configuration required to deploy Kubernetes resources such as containers for the for the BYOI ingest pod.

You can use the following sample Kubernetes Jinja template to create a YAML file. You must replace:

  • Placeholders for commands and args, <ADD_COMMAND> and <ADD_ARGUMENTS>. For example, replace <ADD_COMMAND> with python3 and ADD_ARGUMENTS> with the name of your Python file.

  • <PLUGIN_NAME_CAPITALIZED> with your plugin name in uppercase letters.

You can add other properties to the ’containers’ part, such as volumes or Kubernetes secrets, in the template. After you modify the sample Kubernetes Jinja template, change the name of the file to healthbot_<plugin_name>.yaml.j2 and save it.

Sample Kubernetes Jinja template

(Optional) Assign Virtual IP Address to Plugin

For a custom BYOI plug-in to be reachable from an external network, the plug-in needs to be exposed as a Kubernetes load balancer service. This is an optional configuration. By default, the plug-in uses virtual IP address of the Paragon Insights gateway. You can also assign a custom virtual IP address and add the following template to the end of the Kubernetes Jinja template file in Configure Kubernetes YAML File.

Ensure that you replace <PLUGIN_PORT> and <PROTOCOL> in the given template with your desired values such as port 80 for protocol HTTP. See Kubernetes documentation for supported protocols.

To configure a custom virtual IP for the BYOI plugin, replace <custom_load_balancer_ip> with an IP address.

After you configure the port and protocol, external applications can communicate with the custom BYOI plug-in via <gateway_IP>:<PLUGIN_PORT>. If you configured a custom virtual IP for the plug-in to act as a load balancer service, external applications can communicate with the plugin via custom_load_balancer_ip:PLUGIN_PORT.

Use<PLUGIN_PORT> to connect to the server running inside the plug-in from the Kubernetes host.

You can configure different ports for different applications in the given Kubernetes Jinja template under the ports section.


If you configure different port numbers in the Kubernetes Jinja template, you must hard code the port number and the corresponding port name in your respective applications.

Load the BYOI Custom Plugin

Mount the BYOI custom plug-in image tar file and the modified Kubernetes YAML file to the Paragon Insights primary node and load the plug-in in the Paragon Insights management CLI.

  1. Mount the BYOI plugin image (compressed tar file) using the following command:

    export HB_EXTRA_MOUNT1=/path/to/healthbot_<plugin_name>.tar.gz

  2. Mount the Kubernetes YAML file using the following command:

    export HB_EXTRA_MOUNT2=/path/to/healthbot_<plugin_name>.yml.j2

  3. Load the plugin image and the Kubernetes YAML file using the following command:

    sudo -E healthbot load-plugin -i $HB_EXTRA_MOUNT1 -c $HB_EXTRA_MOUNT2

    You can see a confirmation message when the plugin loads successfully.

  4. (Optional) Select the Configuration > Data Ingest > Settings > BYO Ingest Plugins page and view the custom plug-in in the Custom Plugins tab.

After you load your plug-in, create an instance of the custom BYOI plug-in in the Bring Your Own Ingest page. Since custom plug-ins do not use the default Paragon Automation resources, you must configure a new rule and a playbook for the ingest plug-in.