Install - .NET 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. In the Startup process of the Controller Container, start the vFunction Controller process from within the /shared/ folder
  5. 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
  6. 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. Download a sample installation.yaml
  3. Modify the installation.yaml to be relevant to your environment
### Modify the CHANGE_ME values below 
controller:
 name: CHANGE_ME #... use a string that indicates what and where this is, e.g. UAT tomcat1
 host: CHANGE_ME #... use the VF Server's address, e.g. http://10.0.0.49
 org_id: CHANGE_ME #... taken from the VF Server UI after you've created the Application
 app_id: CHANGE_ME #... taken from the VF Server UI after you've created the Application
 client_id: CHANGE_ME #... taken from the VF Server UI after you've created the Application
 client_secret: CHANGE_ME #... taken from the VF Server UI after you've created the Application
 instance_id: CHANGE_ME # ... use the same string as used in the "name" field
 type: dotnet
 agent_port: 9778
 instrconf_additions:
   inclusions:
#      - a.b.c.
   exclusions:
#      - a.b.c.
 tags:
#    - CHANGE_ME # ... use the same string as used in the "name" field

server_application:
#  name: 
#  include_classes: 
#  allowed_users:

agent:
#  application_name:
#  architecture: x86
#  application_command:

viper:
 port: 8091
 assemblies:
   - /shared/binaries-for-viper/ # ... If planning to run Viper as its own Sidecar Container
  1. 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/
mkdir /shared/binaries-for-viper
  1. Create a folder for vFunction artifacts in the Artifact Repository accessible by the Docker Build
  2. Add the vFunction Sudoless Controller Installation TGZ, the installation.yaml and the startup.sh to the Artifact Repository
  3. Create a vFunction specific branch to add the vFunction artificats to the Init Container’s Dockerfile
  4. Create the Init Container’s Dockerfile
### In the Dockerfile, replace ARTIFACT_REPOSITORY with the actual path to the Build location where the vFunction artifacts are stored
### If planning to just run the Agent without Viper in the Sidecars, add the -a flag to the end of the bash line. This will run the installation in AgentMode 
FROM almalinux:9

ARG NAME
ARG VERSION
ARG RELEASE

ENV SUMMARY="Linux .NET Sidecar application wrapper for vFunction Controller."          \
   DESCRIPTION="Linux .NET Sidecar application wrapper for vFunction Controller."

LABEL summary="$SUMMARY"                                \
     description="$DESCRIPTION"                        \
     io.k8s.description="$DESCRIPTION"                 \
     name="vfunction/$NAME"                            \
     vendor="vFunction"                                \
     version="$VERSION"                                \
     release="$RELEASE"                                

RUN adduser -l -u "1500" "appuser"

COPY ARTIFACT_REPOSITORY/vfunction/vfunction-controller-sudo-less-installation*.tgz /tmp/vfunction-controller-sudo-less-installation.tgz
COPY ARTIFACT_REPOSITORY/vfunction/vfunction/*.yaml /tmp/
COPY ARTIFACT_REPOSITORY/vfunction/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        && \
   mv /tmp/installation.yaml /shared/vfunction/etc/sysconfig/vfunction/installation/instances/default-dotnet/  && \
   bash /shared/vfunction/opt/vfunction/controller-installation/install.sh -i default-dotnet -n  && \
   mv /shared/vfunction /tmp/      && \
   rm -rf /shared                  && \
   chmod +x /usr/bin/startup-init.sh      && \
   chmod -R 777 /usr/bin/ /tmp/vfunction  && \
   chown -R appuser:appuser /tmp/vfunction/

USER 1500

ENTRYPOINT ["/bin/sh"]
CMD ["/usr/bin/startup-init.sh"]
  1. Build the Init Dockerfile

Configuring the Controller Container

  1. Create the Controller Container’s startup-controller.sh script
#!/usr/bin/env bash

set -x

echo "Starting the controller"

bash /shared/vfunction/opt/vfunction/controller/instances/default-dotnet/bin/vf-controller start || echo "Failed to start the controller"

while true; do
 sleep 600
 echo "Still alive..." 
done
  1. Add the startup-controller.sh script to the folder for vFunction artifacts in the Artifact Repository accessible by the Docker Build
  2. Create the Controller Container’s Dockerfile
### In the Dockerfile, replace ARTIFACT_REPOSITORY with the actual path to the Build location where the vFunction artifacts are stored 
FROM almalinux:9

ARG NAME
ARG VERSION
ARG RELEASE

ENV SUMMARY="Linux .NET Sidecar application wrapper for vFunction Controller."          \
   DESCRIPTION="Linux .NET Sidecar application wrapper for vFunction Controller."

LABEL summary="$SUMMARY"                                \
     description="$DESCRIPTION"                        \
     io.k8s.description="$DESCRIPTION"                 \
     name="vfunction/$NAME"                            \
     vendor="vFunction"                                \
     version="$VERSION"                                \
     release="$RELEASE"                                

RUN adduser -l -u "1500" "appuser"

COPY ARTIFACT_REPOSITORY/vfunction/startup-controller.sh /usr/bin/startup-controller.sh

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

USER 1500

ENTRYPOINT ["/bin/sh"]
CMD ["/usr/bin/startup-controller.sh"]
  1. Build the Controller Dockerfile

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 the Viper Container’s startup-viper.sh script
#!/usr/bin/env bash

set -x

echo "Starting Viper"

bash /shared/vfunction/opt/vfunction/viper/instances/default-dotnet/bin/vf-viper start || echo "Failed to start viper"
  1. Add the startup-viper.sh script to the folder for vFunction artifacts in the Artifact Repository accessible by the Docker Build
  2. Create the Viper Container’s Dockerfile
### In the Dockerfile, replace ARTIFACT_REPOSITORY with the actual path to the Build location where the vFunction artifacts are stored
### Replace the APPLICATION_ASSEMBLIES with the path to the DLLs for the Application 
FROM almalinux:9

ARG NAME
ARG VERSION
ARG RELEASE

ENV SUMMARY="Linux .NET Sidecar application wrapper for vFunction Controller."          \
   DESCRIPTION="Linux .NET Sidecar application wrapper for vFunction Controller."

LABEL summary="$SUMMARY"                                \
     description="$DESCRIPTION"                        \
     io.k8s.description="$DESCRIPTION"                 \
     name="vfunction/$NAME"                            \
     vendor="vFunction"                                \
     version="$VERSION"                                \
     release="$RELEASE"                                

RUN adduser -l -u "1500" "appuser"                                                          && \
   mkdir -p /opt/application/lib

COPY /APPLICATION_ASSEMBLIES /shared/binaries-for-viper/
COPY ARTIFACT_REPOSITORY/vfunction/startup-viper.sh /usr/bin/startup-viper.sh

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

USER 1500

ENTRYPOINT ["/bin/sh"]
CMD ["/usr/bin/startup-viper.sh"]
  1. Build the Viper Dockerfile

Configuring the Application Container

  1. Create the Application Container’s startup-application.sh script
### Add the workflow to run the application after the line #RunApp 
#!/usr/bin/env sh

set -x

echo "Adding vFunction environmental variables"

export VF_AGENT_CONF_LOCATION=/shared/vfunction/etc/sysconfig/vfunction/agent/instances/default-dotnet/conf.json
export CORECLR_PROFILER_PATH_64=/shared/vfunction/opt/vfunction/agent/libvfagent.net.so
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={cd7d4b53-96c8-4552-9c11-6e41df8eab8a}
export DOTNET_TailCallOpt=0

echo "Starting Application"

#RunApp
  1. Add the startup-application.sh script to the folder for vFunction artifacts in the Artifact Repository accessible by the Docker Build
  2. Modify the Application Container’s Dockerfile
### Note that this is meant to be a sample where you copy-and-paste the relevant vFunction details into your existing Dockerfile, hence the references to EXISTING_DOCKER_IMAGE and EXISTING_WORKFLOW
### In the Dockerfile, replace ARTIFACT_REPOSITORY with the actual path to the Build location where the vFunction artifacts are stored 
FROM EXISTING_DOCKER_IMAGE

COPY EXISTING_WORKFLOW


# vFunction 
COPY ARTIFACT_REPOSITORY/vfunction/startup-application.sh /usr/bin/startup-application.sh

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

ENTRYPOINT ["/bin/sh"]
CMD ["/usr/bin/startup-application.sh"]
  1. Build the Application Dockerfile

Configuring the Deployment Manifest

  1. Modify the manifest for the environment to ensure that the Volumes are created and accessible for each Container
### Find-and-replace
### In the Dockerfile, replace ARTIFACT_REPOSITORY with the actual path to the Build location where the vFunction artifacts are stored 
apiVersion: apps/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:
       - image: <init-image>
         imagePullPolicy: IfNotPresent
         name: init
         securityContext:
           runAsNonRoot: true
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
     containers:
       - name: application
         image: <application-image>
         imagePullPolicy: Always
         ports:
           - containerPort: 8080
             protocol: TCP
         securityContext:
           runAsNonRoot: true
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
       - name: controller
         image: <controller-image>
         imagePullPolicy: IfNotPresent
         securityContext:
           runAsNonRoot: true
           runAsUser: 1500
         volumeMounts:
           - mountPath: /shared/
             name: shared
       - name: viper
         image: <viper-image>
         imagePullPolicy: IfNotPresent
         securityContext:
           runAsNonRoot: true
           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 17 Jul 2024