17. Using external plugins with ArmoniK.Core

17.1. Queue adaptors as external plugins

We have the possibility to have a queue adaptor as an external project and to use it as a plugin to ArmoniK.Core when needed. More about adaptors is available here. Using a queue adaptor as an external plugin was possible thanks to dynamic loading of adaptors, and the use of docker images.

17.1.1. Loading queue adaptor into a C# project

ArmoniK.Core is based on C# projects where queue adaptors are dynamically loaded. Dynamic assembly loading allows to create dotnet applications with plugins. The hosting application refers to the application to which the plugins will be connected.

The hosting application should define an interface that all plugins need to implement. This interface serves as a base for each plugin. In our case, the base interface that should be implemented in any plugin is in NuGet package ArmoniK.Core.Base. Any plugin should have a reference to this package.

17.1.2. Packing a plugin

Once the queue adaptor is implemented, we need to pack it to be loaded in ArmoniK.Core.

To pack the plugin to ArmoniK.Core, we modify the docker images of the polling agent and the control plane. We should create two images:

  • one based on a specific version of the polling agent, with the plugin project added on top

  • one based on a specific version of the control plane image, also with the plugin project added on top

This is an example of docker file that allows you to build a new image consisting of the image of polling agent with your plugin.

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS mypluginimage
WORKDIR /src
COPY . .
WORKDIR "/src/MyPlugin/"
RUN dotnet publish "MyPlugin.csproj" -c Release -o /app/publish/myplugin /p:UseAppHost=false

FROM dockerhubaneo/armonik_pollingagent:0.14.3 AS final
COPY --from=mypluginimage /app/publish/plugin /plugins/myplugin

In this file, we first copy the source files of the project MyPlugin, then we compile the project using dotnet publish. The files resulting from dotnet publish command are saved in the folder /app/publish/myplugin in the image mypluginimage . After that, we start from dockerhubaneo/armonik_pollingagent:0.14.3 as a base image , and copy the plugin application files from /app/publish/myplugin in the image mypluginimage to the folder /plugins/myplugin in the resulting image.

In that way, the resulting image consisted of the image dockerhubaneo/armonik_pollingagent:0.14.3 plus the plugin project. The same is to be done to build a second image that starts from the control plane image dockerhubaneo/armonik_control:0.14.3 and adds the plugin.

17.1.3. Connecting a plugin to ArmoniK.Core

17.1.4. Modify environment variables

Now that the images containing the plugin are ready, you can deploy ArmoniK.Core locally using these two images. To do so, you are provided environment variables in the justfile to modify in order to use specific images. You will need to change the values of the variables : POLLING_AGENT_IMAGE and SUBMITTER_IMAGE to pass the new images of polling agent and control plane that you created with your plugin.

You may need to pass environment variables that are specific to the plugin. To do so, you can overwrite the variable: TF_VAR_custom_env_vars and fill it with your variables. These environment variables help to complete the configuration to be able to use your plugin. The two main parameters that you will need are:

  • the path of plugin assembly in the containers

  • the name of the class that implements IDependencyInjectionBuildable (an adaptor must implement IDependencyInjectionBuildable as explained here).

export TF_VAR_custom_env_vars='{ "Components__QueueAdaptorSettings__ClassName" = "MyPlugin.MyClassName", "Components__QueueAdaptorSettings__AdapterAbsolutePath" = "/plugins/myplugin/MyPlugin.dll" }'

17.1.5. Deploy Core

If your adaptor uses a queue that can already be deployed by ArmoniK.Core(rabbitmq or activemq), you can specify this queue to the deployment of Core. To know how to deploy ArmoniK.Core and how to specify the queue, see Local deployment of ArmoniK.Core.

If you use another queue, you should deploy the corresponding service. First of all, you should create the docker network armonik_network

docker network create armonik_network

Inside this docker network, deploy your queue. This means that your queue should run as a container in the network armonik_network. After that, run:

cd [ArmoniK.Core repository]
terraform -chdir=./terraform import docker_network.armonik $(docker network inspect armonik_network | jq -r '.[].Id')

Finally, supposing you already modified the needed environment variables, you need to deploy ArmoniK.Core using:

cd [ArmoniK.Core repository]
just queue=none deploy