Install - Java Agent on Jenkins Pipeline for Dynamic Analysis



Overview

A Jenkins Pipeline can be used to deploy the vFunction Agent and Viper. At a high level, the deployment process includes:

  1. Setting Environment Variables for the vFunction installation script to pick up during installation
  2. Moving the vFunction installation TGZ onto the machine running the application and unpacking this TGZ
  3. Running a pre-installation script to create the directory structure and files associated with the vFunction instance that will be used
  4. Running the vFunction installation script
  5. Creating a Cron task that checks that the vFunction background processes are running (if applicable) and restarts the processes if they are not

Installation

Take the following steps to install the vFunction Agent for Dynamic Analysis through a Jenkins Pipeline:

  1. Download the vFunction Controller Linux Sudoless Installation TGZ
  2. Configure a Pipeline to set the vFunction Environment Variables and run the vFunction Scripts for installation. This Pipeline Template can also be downloaded instead of copy-and-pasted.
pipeline {
  agent { label 'vFunctionAgent' }
  parameters {
    ### Replace INSTANCE_NAME in the Environment Variable Keys with the actual instance name, such as "omsAgent" or "omsViper"
    ### Replace NAME with an identifier for the Application in the VF Server UI, e.g. qa-oms
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_NAME', defaultValue: 'NAME')
    ### Replace http://VF_SERVER_ADDRESS with the URL to log into the VF Server UI
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_HOST', defaultValue: 'http://VF_SERVER_ADDRESS')
    ### Replace orgId with the UUID for this Application found in the vFunction Server UI's Learning > Select Controllers > Installation Instructions dialog box
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_ORG_ID', defaultValue: 'orgId')
    ### Replace appId with the UUID for this Application found in the vFunction Server UI's Learning > Select Controllers > Installation Instructions dialog box
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_APP_ID', defaultValue: 'appId')
    ### Replace clientId with the UUID for this Application found in the vFunction Server UI's Learning > Select Controllers > Installation Instructions dialog box
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_CLIENT_ID', defaultValue: 'clientId')
    ### Replace clientSecret with the UUID for this Application found in the vFunction Server UI's Learning > Select Controllers > Installation Instructions dialog box
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_CLIENT_SECRET', defaultValue: 'clientSecret')
    ### Replace instanceId with a string that is distinct for this instance, such as jenkinsQA
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_INSTANCE_ID', defaultValue: 'instanceId')
    ### Replace TAG1,TAG2 with strings to organize Agents by functionality, environment or other logical groupings, such as "all,qa,web"
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_CONTROLLER_TAGS', defaultValue: 'TAG1,TAG2')
    ### This variable is required only if the Agent is running with this instance
    ### Replace LIBERTY value with the lowercase string for the App Server: weblogic, websphere85, websphere9, liberty, tomcat, wildfly, payara, other
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_AGENT_APPLICATION_SERVER', defaultValue: 'LIBERTY')
    ### This variable is required only if the Agent is running with this instance
    ### Replace 8 with the Java Major Version used to run the Application, e.g. 8, 11, 17, 21 
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_AGENT_APPLICATION_JAVA_VERSION', defaultValue: '8')

    ### This variable is required only if the Agent is running with this instance
    ### This variable will only work if there is a single JVM running on the machine. If multiple JVMs run on the machine, inject the Java Options elsewhere
    ### Replace INSTANCE_NAME with the actual Instance
    string(name: 'JAVA_TOOL_OPTIONS', defaultValue: '-agentpath:BASE_DIR/vfunction/opt/vfunction/agent/libJVMTIAgent.so=conf=BASE_DIR/vfunction/etc/sysconfig/vfunction/agent/instances/INSTANCE_NAME/native-conf.json -javaagent:BASE_DIR/vfunction/opt/vfunction/agent/runtime-agent.jar=ConfigLocation=BASE_DIR/vfunction/etc/sysconfig/vfunction/agent/instances/INSTANCE_NAME/vfunction-runtime-override.properties -Dcom.vfunction.runtime.offload.tmpFolder=BASE_DIR/vfunction/opt/vfunction/agent/instances/INSTANCE_NAME/temp/ -Dcom.vfunction.logging.logFile=BASE_DIR/vfunction/var/log/vfunction/instances/INSTANCE_NAME/vfagent.log')
    ### This variable is required only if Viper is running with this instance
    ### Replace /PATH/TO/*.WAR with the path to the Binaries for the Application. Wildcards can be used
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_VIPER_ARCHIVES', defaultValue: '/PATH/TO/*.WAR')
    ### This variable is required only if Viper is running with this instance
    ### Replace the 2g Xmx Max Heap Size based on the classes in the application. "2g" for < 8k classes. "4g" for > 8K and < 20k. "6g" for > 20k classes
    string(name: 'VF_CONTROLLER_INSTANCE_NAME_VIPER_JVM_MEMORY_PARAMS', defaultValue: '-Xms300m -Xmx2g -Xss50m')
    
  }
  stages {
    stage('vFunctionUnpackTGZ') {
      steps {
        ### Find-and-replace VERSION with the actual installation package version
        ### Find-and-replace /path/to/vfunction with the actual TGZ location 
        ### Find-and-replace /BASE_DIR with the location you want to install vFunction
        tar -xvzf /path/to/vfunction/vfunction-controller-sudo-less-installation.vVERSION.tgz -C /BASE_DIR/
      }
    }
    stage('vFunctionCreateInstance') {
      steps {
        ### In Controller v4.0, a vFunction Instance can be either in AgentMode or ViperMode. The -a AgentMode and -v ViperMode flags were introduced to this script with this release. See the two examples below and choose the appropriate script
        ### Find-and-replace INSTANCE_NAME with the desired instance name, such as "omsAgent" or "omsViper"
        # bash /BASE_DIR/vfunction/opt/vfunction/controller-installation/create-instance.sh -i INSTANCE_NAME -t java -a
        # bash /BASE_DIR/vfunction/opt/vfunction/controller-installation/create-instance.sh -i INSTANCE_NAME -t java -v
        bash /BASE_DIR/vfunction/opt/vfunction/controller-installation/create-instance.sh -i INSTANCE_NAME -t java
      }
    }
    stage('vFunctionInstallInstance') {
      steps {
        ### The -n NoServices flag is used to ensure no process, such as the Viper or Controller processes, are started during the Jenkins Pipeline Build. Because these processes need to communicate with the vFunction Server, the startup of these processes will fail during the Jenkins Pipeline Build.
        bash /BASE_DIR/vfunction/opt/vfunction/controller-installation/install.sh -i INSTANCE_NAME -n
      }
    }
    stage('vFunctionAddProcessRestartToCron') {
      steps {
        ### This is only valid for versions below 4.0 where the Controller process is still used
        ### Replace APP_USER with the username that runs the Application Server
        ### Replace INSTANCE_NAME with the vFunction Instance Name
        crontab -u APP_USER -l | grep -q "controller --instance=INSTANCE_NAME"; if [ $? -ne 0 ]; then (echo -e "$(crontab -u APP_USER -l 2>/dev/null)\n*/10 * * * * (ps xu | grep 'controller --instance=INSTANCE_NAME' | grep -v grep > /dev/null) || bash /BASE_DIR/vfunction/opt/vfunction/controller-installation/restart-controller.sh -i INSTANCE_NAME" | crontab -u APP_USER -); fi
        ### This is only valid for installations that include Viper
        ### Replace APP_USER with the username that runs the Application Server
        ### Replace INSTANCE_NAME with the vFunction Instance Name
        crontab -u APP_USER -l | grep -q "viper.jar --instance=INSTANCE_NAME"; if [ $? -ne 0 ]; then (echo -e "$(crontab -u APP_USER -l 2>/dev/null)\n*/10 * * * * (ps xu | grep 'viper.jar --instance=INSTANCE_NAME' | grep -v grep > /dev/null) || bash /BASE_DIR/vfunction/opt/vfunction/controller-installation/restart-controller.sh -i INSTANCE_NAME" | crontab -u APP_USER -); fi
      }
    }
  }
}
  1. Build and deploy the Application