Deploying custom plug-ins

Review the information in this topic to understand the steps that an administrator performs to deploy custom plug-ins after a fresh installation of BMC Helix Service Management.

The following diagram shows the overview of the process of deploying custom plug-ins:

Before you begin

Make sure you have your custom Plug-in.jar file.
Set up a local harbor registry.
Download the pluginservice.zipfile.

Task 1: Prepare the plug-in files and create a custom plug-in image

Prepare the plug-ins files by performing the following steps and then create a custom plug-in image by using the Plug-in server base image from BMC Docker Trusted Registry (DTR).

On the Jenkins server or a LINUX machine that has Docker Engine - Community 20.10.17 or later installed, create a working directory named customplugin.
Use this directory to organize the files required to create a custom plugin.

Navigate to the customplugin directory, and create a sub directory named image.
Navigate to the image directory, and create a new file named Dockerfile by using a text editor.
In the Dockerfile file, add the following details:
# Dockerfile to create an image for a custom plug-in server.
FROM <registry_server>/containers.bmc.com/bmc/pluginsvr_base:23301-RTM
ADD --chown=bmcuser:bmc --chmod=g+rw pluginsvr /opt/bmc/ARSystem/pluginsvr
In the <registry_server> parameter, specify the name of the registry server from where you have synced the plug-in server base image from containers.bmc.com.
This file is used to prepare the Docker image of custom plug-in.
Important
The --chmod option requires BuildKit. To learn how to build images with BuildKit enabled, see Build images with BuildKit in the Docker documentation.
Navigate to the image directory and create a sub directory named pluginsvr.

Navigate to the pluginsvr directory.
In the pluginsvr directory, copy all the custom plug-in jar files and the supporting files.
In the pluginsvr directory, create a new pluginsvr_config.xml file and add the following details to the file:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<pluginsvr_config>
<port>__CUSTPLUGINPORT__</port>
<regPortMapper>false</regPortMapper>
<encryptionPolicy>2</encryptionPolicy>
<publicKeyAlg>4</publicKeyAlg>
<publicKeyExpiry>86400</publicKeyExpiry>
<dataEncryptionAlg>1</dataEncryptionAlg>
<dataKeyExpiry>2700</dataKeyExpiry>
<numCoreThreads>5</numCoreThreads>
<numSelectorThreads>2</numSelectorThreads>
<workQueueMonitorLogInterval>0</workQueueMonitorLogInterval>
<workQueueTaskThreshold>5</workQueueTaskThreshold>
<pluginSvrName> PluginServer_Service___ARSERVERCONNECTNAME_____CUSTPLUGINPORT__ </pluginSvrName>
<reloadDelay>30000</reloadDelay>
<enableNativeBridge>false</enableNativeBridge>
<maxThreads>10</maxThreads>
<excessCoreThreadsIdleKeepAliveTimeInSecond>0</excessCoreThreadsIdleKeepAliveTimeInSecond>
<supportNativePluginHost>false</supportNativePluginHost>
<loadNativePluginHost>false</loadNativePluginHost>
<pluginSvrLogEnable>True</pluginSvrLogEnable>
<pluginSvrLogFile>/opt/bmc/ARSystem/db/__CUSTOMPLUGINNAME___arjavaplugin___CUSTPLUGINPORT__.log</pluginSvrLogFile>
<pluginSvrLogLevel>INFO</pluginSvrLogLevel>
<pluginSvrLogMaxFileSize>5242880</pluginSvrLogMaxFileSize>
<pluginSvrLogMaxHistory>10</pluginSvrLogMaxHistory>
<pluginSvrAlwaysOnLogName> /opt/bmc/ARSystem/db/__CUSTOMPLUGINNAME_____CUSTPLUGINPORT___alwayson.log </pluginSvrAlwaysOnLogName>
<pluginSvrAlwaysOnCopies>20</pluginSvrAlwaysOnCopies>
<pluginSvrAlwaysOnBufferSize>0</pluginSvrAlwaysOnBufferSize>
<plugins>
</plugins>
</pluginsvr_config>
This file is used to add the custom plug-in configuration information.
To add the custom plug-in information, in the pluginsvr_config.xml file, enter a plug-in configuration block for your plug-in by using the <plugins> and </plugins> tags as shown in the following template:
</plugins>
<plugin>
    <name><Name of your custom plugin></name>
        <classname>Name of the plugin class</classname>
            <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/JAR file 1</pathelement>
            <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/JAR file 2</pathelement>
   <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/JAR file n</pathelement>
            <userDefined>
                    <KeepResultsSeconds>Keep result value in seconds</KeepResultsSeconds>
                    <KeepCacheSeconds>Keep cache value in seconds</KeepCacheSeconds>
                    <Timeout>Timeout value in seconds</Timeout>
                    <AlwaysLogDetails></AlwaysLogDetails>
                    <ProxyServer></ProxyServer>
                    <ProxyPort></ProxyPort>
                    <ProxyUser></ProxyUser>
                    <ProxyPass></ProxyPass>
                    <KeyStoreAlgorithm></KeyStoreAlgorithm>
                    <KeyStoreFormat></KeyStoreFormat>
                    <KeyStoreFile></KeyStoreFile>
                    <KeyStorePass></KeyStorePass>
                    <KeyStoreProtocol></KeyStoreProtocol>
                    <TemplateFieldDelimiter></TemplateFieldDelimiter>
                    <ArrayDelimiter></ArrayDelimiter>
            </userDefined>
</plugin>
</plugins>
In the <pathelement type="location"> parameter, /opt/bmc/ARSystem/pluginsvr/ is the path of the platform container directory.
The following block shows an example plug-in configuration:
</plugins>
<plugin>
    <name>APL.ARDBC.RESTFULARDBCPLUGIN</name>
        <classname>com.apl.RestfulARDBCPlugin</classname>
            <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/APLRestfulARDBCPlugin.jar</pathelement>
            <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/json-20200518.jar</pathelement>
            <userDefined>
                    <KeepResultsSeconds>300</KeepResultsSeconds>
                    <KeepCacheSeconds>86400</KeepCacheSeconds>
                    <Timeout>90</Timeout>
                    <AlwaysLogDetails></AlwaysLogDetails>
                    <ProxyServer></ProxyServer>
                    <ProxyPort></ProxyPort>
                    <ProxyUser></ProxyUser>
                    <ProxyPass></ProxyPass>
                    <KeyStoreAlgorithm></KeyStoreAlgorithm>
                    <KeyStoreFormat></KeyStoreFormat>
                    <KeyStoreFile></KeyStoreFile>
                    <KeyStorePass></KeyStorePass>
                    <KeyStoreProtocol></KeyStoreProtocol>
                    <TemplateFieldDelimiter></TemplateFieldDelimiter>
                    <ArrayDelimiter></ArrayDelimiter>
            </userDefined>
</plugin>
</plugins>

Important
Make sure that you do not change any other sections in the file.

Task 2: To build the plug-in image

Navigate to the image directory and build the plug-in image by using the following command:
DOCKER_BUILDKIT=1 docker build -t <plugin_image_name> .
For example:
DOCKER_BUILDKIT=1 docker build -t my_custom_pluginserver .
After the image is built, use the following command to verify that the new image is available:
docker image ls
Add a new tag to the image and push it to the registry server that is used to share images to the Kubernetes cluster.
For example:
$ docker tag my_custom_pluginserver <your_registry_server>
$ docker push <your_registry_server> containers.bmc.com/bmc/pluginsvr_base:23301-RTM
The push refers to repository [<your_registry_server>/bmc/lp00x]
0f6166511e27: Pushed
a03dea7d0030: Pushed
e18e4d781654: Pushed
5f70bf18a086: Pushed
0e6256a1564b: Pushed
7c182eac9297: Pushed
55431d70b0c0: Pushed
9ac4b6907c58: Pushed
78b22de90ed3: Pushed
91a447ce5fb0: Pushed
6d9467619955: Pushed
e3d8f5d76e6c: Pushed
61c70a5bb3ed: Pushed
d48ce3932dae: Pushed
174f56854903: Layer already exists
aplrest-213004: digest: sha256:6fc86a5939044eb1b80183c1bf7ab3c2b44c2038861703d3c0fa9aa84fc3daae size: 3465

Task 3: To create a Helm chart for the plug-in server image

Navigate to your working directory customplugin and download and extract the zip file.

In the values.yaml file, add the following parameter values:

Parameter name	Description
registry	Name of the registry server where the custom plug-in server image is saved.
pluginimage	Name of your custom plug-in.
pluginimagetag	Tag of the image pushed to the registry server.
AR_SERVER_DOMAIN	Name of your domain.
CUSTOM_PLUGINSVR_NAME	Name of your custom plug-in server.
(Optional) CUSTOM_PLUGINSVR_PORT	Custom plug-in port value. The default value is 9822.
JAVA_MAX_HEAP_SIZE	Maximum memory size for JVM.
JAVA_MIN_HEAP_SIZE	Minimum memory size for JVM.
name in the imagePullSecrets section	The IMAGESECRET_NAME parameter value from the HELIX_ONPREM_DEPLOYMENT pipeline that is used to deploy BMC Helix Service Management. Alternatively, you can use the following command to find the value: kubectl get secret -n <BMC Helix Innovation Suite namespace> --field-selector type=kubernetes.io/dockerconfigjson
AR_SERVER_APP_SERVICE_PASSWORD	The AR_SERVER_APP_SERVICE_PASSWORD parameter value from the HELIX_ONPREM_DEPLOYMENT pipeline used to deploy BMC Helix Service Management. Alternatively, you can use the following command to find the value: kubectl get secret platform-fts -n <helix_itsm_namespace> -o=jsonpath='{.data.AR_SERVER_APP_SERVICE_PASSWORD}' \| base64 -d

Important

In the env section, add the environment variables required for your custom plug-in.

If you are using Openshift with restricted SCC enabled, navigate to the deployment.yaml file located at pluginservice/templates/, and update the file as follows:
1. In the deployment.yaml file, in the securityContext section, delete the runAsUser: 1000 and fsGroup: 1000 parameters.
2. Add the runAsGroup: 1000 parameter as shown in the following image:

Task 4: To deploy the custom plug-in

In your BMC Helix Innovation Suite namespace, deploy the plug-in server container by using the following command:
helm --namespace=<BMC Helix Innovation Suite namespace> upgrade --install <plugin_server_name> . -f values.yaml
For example:
helm --namespace=itsm123 upgrade --install customplugin . -f values.yaml
Verify that the custom plug-in server is running by using the following command:
kubectl get pods -n <BMC Helix Innovation Suite namespace>
To view the Helm deployments, run the following command:
helm ls -n <BMC Helix Innovation Suite namespace>
Log in to Mid Tier and confirm that the deployed plug-ins are registered in the Plugin Server Configuration form.
For more information, see Form Permissions plug-in configuration in BMC Helix Innovation Suite documentation.

Where to go from here

Next task	Proceed with Moving-your-CMDB-customizations-to-a-new-target-system
Back to process	If you are finished moving your customization to a new target system, return to the Migrating-Remedy-on-premises-to-BMC-Helix-Service-Management-on-premises.