Install - Java Agent Controller on a Containerized App running a Linux image using Sidecars

Overview

Docker Sidecars can be used for the vFunction Controller installation to separate the vFunction components from the main application so that each component is running in a separate Container.

The vFunction Docker Sidecar Installation does the following:

  1. In the Build process of the Init Container, move the vFunction Controller Installation TGZ and application-specific YAML files onto the Container
  2. In the Build process of the Init Container, unpack the vFunction Controller TGZ and install the Controller, Agent and (potentially) Viper to the /tmp/ directory
  3. In the Startup process of the Init Container, move the /tmp/vfunction/ contents to a /shared/ folder that is used by each of the Sidecar Containers
  4. Optional if running Viper as a Sidecar in the same environment: In the Startup process of the Viper Container, start the vFunction Controller process from within the /shared/ folder
  5. In the Startup process of the Application Container, add the vFunction Agent parameters as environmental variables and start the Application

Configuring the Init Container

  1. Download the latest vFunction Sudoless Controller Installation TGZ
  2. Create the Init Container’s startup-init.sh script
#!/usr/bin/env bash

set -x

echo "Moving controller files to shared folder"
mv /tmp/vfunction /shared/

### If you plan to deploy the Viper container as well
mkdir /shared/binaries-for-viper
  1. Create a folder for vFunction Init Container’s artifacts on the Docker Build Machine
  2. Add the vFunction Sudoless Controller Installation TGZ and the startup-init.sh to the folder you created
  3. Create the Init Container’s Dockerfile
FROM almalinux:9                 

### Modify this line to match the user that runs the Application
RUN adduser -l -u "1500" "appuser"

ARG VF_CONTROLLER_DEFAULT_JAVA_AGENT_APPLICATION_SERVER="other"
ARG VF_CONTROLLER_DEFAULT_JAVA_AGENT_APPLICATION_JAVA_VERSION=11

### See https://kb.vfunction.com/installations/configurable-settings/mono-dynamic-agent/java/linux for more details about each of the settings below
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_HOST="http://vfunction.myorg.com"
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_NAME="docker-agent"
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_ORG_ID="1111-11-11-1111"
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_APP_ID="1111-11-11-1111"
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_CLIENT_ID="1111-11-11-1111"
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_CLIENT_SECRET="1111-11-11-1111"
ARG VF_CONTROLLER_DEFAULT_JAVA_CONTROLLER_INSTANCE_ID="container"

### If installing Viper here also
ARG VF_CONTROLLER_VIPERINST_VIPER_ARCHIVES='["/shared/binaries-for-viper/*.*"]'
### See https://kb.vfunction.com/installations/configurable-settings/mono-static-agent/java/linux for more details about each of the settings below
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_HOST="http://vfunction.myorg.com"
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_NAME="docker-viper"
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_ORG_ID="1111-11-11-1111"
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_APP_ID="1111-11-11-1111"
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_CLIENT_ID="1111-11-11-1111"
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_CLIENT_SECRET="1111-11-11-1111"
ARG VF_CONTROLLER_VIPERINST_CONTROLLER_INSTANCE_ID="vipercont"

COPY vfunction-controller-sudo-less-installation*.tgz /tmp/vfunction-controller-sudo-less-installation.tgz
COPY startup-init.sh /usr/bin/startup-init.sh

RUN mkdir /shared && cd /shared && mv /tmp/vfunction-controller-sudo-less-installation.tgz /shared/     && \
   tar zxvf /shared/vfunction-controller-sudo-less-installation.tgz      && \
   rm -rf /shared/vfunction-controller-sudo-less-installation.tgz        && \
   ### If installing Viper here also
   bash /shared/vfunction/opt/vfunction/controller-installation/create-instance.sh -i viperinst -t java -v   && \
   bash /shared/vfunction/opt/vfunction/controller-installation/install.sh -i default-java -n   && \
   ### If installing Viper here also
   bash /shared/vfunction/opt/vfunction/controller-installation/install.sh -i viperinst -n   && \
   mv /shared/vfunction /tmp/      && \
   rm -rf /shared                  && \
   chmod +x /usr/bin/startup-init.sh      && \
   chmod -R 777 /usr/bin/ /tmp/vfunction  && \
   ### Modify this line to match the user that runs the Application
   chown -R appuser:appuser /tmp/vfunction/

### Modify this line to match the user that runs the Application
USER 1500

ENTRYPOINT ["/bin/sh"]
CMD ["/usr/bin/startup-init.sh"]
  1. Build the Init Dockerfile
docker build . -t vf-init-container
  1. Push the Init Image to your Image Repository
docker push repository/vf-init-container:1

Optional: Configuring the Viper Container

Viper is the most resource intensive vFunction process when compared with the Agent and Controller. Some organizations choose to run Viper in a separate location and skip the step of setting up the Viper Container as a Sidecar.

  1. Create a folder for vFunction Viper Container’s artifacts on the Docker Build Machine
  2. Create the Viper Container’s startup-viper.sh script
#!/usr/bin/env bash

set -x

echo "Starting Viper"

bash /shared/vfunction/opt/vfunction/viper/instances/viperinst/bin/vf-viper start || echo "Failed to start viper"
  1. Add the startup-viper.sh script to the folder for vFunction Viper artifacts on the Docker Build Machine
  2. Create the Viper Container’s Dockerfile
FROM almalinux:9

### Modify this line to match the user that runs the Application
RUN adduser -l -u "1500" "appuser"                             && \
   mkdir -p /opt/application/lib

### Replace the APPLICATION_BINARIES with the path to the Archives for the Application
COPY /APPLICATION_ASSEMBLIES /shared/binaries-for-viper/
COPY startup-viper.sh /usr/bin/startup-viper.sh

RUN chmod +x /usr/bin/startup-viper.sh                     && \
   chmod -R 777 /usr/bin/

### Modify this line to match the user that runs the Application
USER 1500

ENTRYPOINT ["/bin/sh"]
CMD ["/usr/bin/startup-viper.sh"]
  1. Build the Viper Dockerfile
docker build . -t vf-viper-container
  1. Push the Viper Image to the Image Repository
docker push repository/vf-viper-container:1

Create a ConfigMap for the Application Container

This ConfigMap adds the vFunction Agent parameters to the Java Tool Options which will get picked up by the Application when the JVM launches.

  1. Create the Java Tool Options ConfigMap in a text editor
apiVersion: v1
kind: ConfigMap
metadata:
  name: java-tool-options-configmap
  namespace: default
data:
  ### Remove the line --add-opens=java.base/java.util=ALL-UNNAMED if using Java 8
  JAVA_TOOL_OPTIONS: |
        -agentpath:/shared/vfunction/opt/vfunction/agent/libJVMTIAgent.so=conf=/shared/vfunction/etc/sysconfig/vfunction/agent/instances/default-java/native-conf.json -javaagent:/shared/vfunction/opt/vfunction/agent/runtime-agent.jar=ConfigLocation=/shared/vfunction/etc/sysconfig/vfunction/agent/instances/default-java/vfunction-runtime-override.properties --add-opens=java.base/java.util=ALL-UNNAMED -Dcom.vfunction.runtime.offload.tmpFolder=/shared/vfunction/opt/vfunction/agent/instances/default-java/temp/ -Dcom.vfunction.logging.logFile=/shared/vfunction/var/log/vfunction/instances/default-java/vfagent.log
  1. Apply the ConfigMap to the Cluster
kubectl apply -f java-tool-options-configmap.yaml

Configuring the Deployment Manifest

  1. Modify the manifest for the environment to ensure that (A) the Volumes are created and accessible for each Container, (B) The Init Container is created, (C) The Controller Container is created, (D) The Viper Container is created [if applicable] and (E) The Java Tool Options are added to the JVM
apiVersion: v1
kind: Deployment
metadata:
 name: application-with-vfunction-controller
 namespace: vfunction
 labels:
   app: application-with-vfunction-controller
spec:
 replicas: 1
 selector:
   matchLabels:
     app: application-with-vfunction-controller
 template:
   metadata:
     labels:
       app: application-with-vfunction-controller
   spec:
     initContainers:
         ### Modify to match the Image Repository
       - image: REPOSITORY/vf-init-container:1
         imagePullPolicy: IfNotPresent
         name: init
         securityContext:
           runAsNonRoot: true
           ### Modify to match the user that runs the Application
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
     containers:
       - name: application
         image: REPOSITORY/APPLICATION
         imagePullPolicy: Always
         ports:
           - containerPort: 8080
             protocol: TCP
         securityContext:
           runAsNonRoot: true
           ### Modify to match the user that runs the Application
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
         envFrom:
           - configMapRef:
             name: java-tool-options-configmap
       - name: controller
         image: REPOSITORY/vf-controller-container
         imagePullPolicy: IfNotPresent
         securityContext:
           runAsNonRoot: true
           ### Modify to match the user that runs the Application
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
       - name: viper
         image: REPOSITORY/vf-viper-container:1
         imagePullPolicy: IfNotPresent
         securityContext:
           runAsNonRoot: true
           ### Modify to match the user that runs the Application
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
     volumes:
       - emptyDir: {}
         name: shared

Deploy the Application and vFunction Sidecars

  1. Apply the Deployment Manifest in the Cluster
  2. Confirm that the Application comes up and functions as expected
  3. If any issues arise:

Updated on 30 Apr 2025