How to apply changes to the Controller environment
Changes in the installation.yaml can be applied by running the install script or the upgrade script. Note that re-running the install script will delete any information that would have been stored previously.
Required fields in installation.yaml
| Variable Name |
Key Value |
Explanation of the Variable and Key Values |
controller.name |
String |
This will be the identifier used in the VF Server UI. So, this should be as precise a name as possible, e.g. "UAT Viper" or "Prod App1" |
controller.host |
String |
The controller.host is the address that the vFunction Server address with which the Controller will connect. The value needs to start with http:// or https://. The value can be an IP Address or a FQDN |
controller.org_id
controller.app_id
controller.client_id
controller.client_secret
|
Strings |
Once the Server is installed, the Admin can log into the UI and create the App. In the UI's Install Controller dialog box, the YAML values for the org_id, app_id, client_id and client_secret will be displayed. The values for this YAML file should be copied for the Server UI to here |
controller.type |
String |
"java" |
agent.disable_jdbc |
Boolean |
The default value is "false." The Agent will try to profile the database connection using JDBC-based tracking by default. When set to, "true", the Agent uses an alternate method to profile the database connection for non-JDBC -based tracking. This adjustment is typically made as a troubleshooting step |
agent.disable_spring |
Boolean |
The default value is "false." The Agent will try to profile Spring Resources like Singletons, Sessions, Requests, Websockets, etc. by default. When set to, "true", this tracking will be disabled. This adjustment is typically made as a troubleshooting step |
agent.application_server |
String |
By default, the value here is set to "other". This value can be used for Uber Jars or Springboot Applications, for example. Other strings that can be used here are weblogic, websphere85, websphere9, liberty, tomcat, wildfly, and payara |
agent.application_java_version |
Integer |
By default, the value here is assumed to be "8" if this key is left commented out. Uncomment the key and change the value to "11" or "17" based on the Java version used by the App |
Sample with required fields in installation.yaml
controller:
name: Prod App1
host: http://10.0.0.143
org_id: 3cf59199-0a0a-0a0a-0a0a-7c63ffac776e
app_id: 7b1ab58d-0a0a-0a0a-0a0a-098a113ad721
client_id: 20761b99-0a0a-0a0a-0a0a-94c2e0bc1859
client_secret: 6b5b7bc1-0a0a-0a0a-0a0a-2bd10db75e2f
type: java
instrconf_additions:
inclusions:
# - a.b.c.
exclusions:
# - a.b.c.
tags:
# - tag1
server_application:
# name:
# include_classes: com.
# allowed_users:
# new_user_default_password:
agent:
### Disable JDBC DB Tracking ###
disable_jdbc: false
### Disable Spring Tracking ###
disable_spring: false
### Optional application servers: weblogic, websphere85, websphere9, liberty, tomcat, wildfly, payara, other ###
application_server: tomcat
### Indicate the application java version when greater than 8. (optional - default to 8) ###
# application_java_version: 11
override_properties:
# - key=value
Optional fields in installation.yaml
agent.override_properties
| Installation.yaml Configuration |
Details |
agent:
override_properties:
- com.vfunction.runtime.config.aop.xml.db.tracking.enabled=true
- com.vfunction.runtime.config.aop.xml.db.tracking.jdbcdriver.enabled=false
|
- The vfunction-runtime-override.properties define the vFunction Agent's runtime parameters. Changes to this file can be applied in a persistent way via the installation.yaml's agent.override_properties field
- Any key and value can be taken from the vfunction-runtime-override.properties and added into this installation.yaml field
- Add new values as a list of Strings
|
controller.instance_id
| Installation.yaml Configuration |
Details |
controller:
instance_id: containerized
|
- Used for containerized vFunction controllers
- Can be set to any String value (e.g., ID1234)
- Used to prevent an ongoing increase in the number of Down Controllers in the vFunction Server UI's Select Controllers page when Controllers are down
- Maps a restarted controllers (i.e., a container that went down and came back up) with a controller in the down state that has the same ID
|
controller.instrconf_additions
| Installation.yaml Configuration |
Details |
controller:
instrconf_additions:
inclusions:
# - a.b.c.
exclusions:
- com.vfunction.newmodule.
|
- This field acts like an additional filter to include or exclude some part of an application's Namespace
- The exclusions are useful when separating out modules from a monolith. For example, if the monolith uses com.vfunction. as the top-level Namespace but com.vfunction.newmodule. has been removed from the monolith. In this scenario, it may not be useful to conduct Learning nor Analysis on the newmodule's code so adding it to the exclusions would filter it out of the Learning
|
| Installation.yaml Configuration |
Details |
controller:
tags:
- applicationName
- moduleName
|
- Tags can be used during Learning to make sure that Learning occurs on one or all Controllers with a specific Tag. This ensures that, even if a Controller with a specific UUID goes down, Learning will still occur on live Controllers with the desired Tag name
- See Controller Tags for more details
|
server_application.name
| Installation.yaml Configuration |
Details |
server_application:
name: "OMS Java"
|
- Two workflows are available to allow the Agent to communicate with the vFunction Server: (1) Use the UUIDs gathered after creating the vFunction Application in the UI or (2) Create the Application from the Agent itself. The server_application.name is used in the second workflow
- This key must be used in conjunction with the server_application.include_classes, server_application.server_username and server_application.server_password fields
- The value associated with this Key will be the vFunction UI's Application Name
- During the Agent installation process, if these fields are present then the vFunction Application will be created in the vFunction UI
|
server_application.include_classes
| Installation.yaml Configuration |
Details |
server_application:
include_classes: "com.vfunction.oms."
|
- Two workflows are available to allow the Agent to communicate with the vFunction Server: (1) Use the UUIDs gathered after creating the vFunction Application in the UI or (2) Create the Application from the Agent itself. The server_application.name is used in the second workflow
- This key must be used in conjunction with the server_application.name, server_application.server_username and server_application.server_password fields
- The value associated with this Key will be the Classes to Include / Namespace / Top-Level Package to be filtered into the vFunction Analysis
- During the Agent installation process, if these fields are present then the vFunction Application will be created in the vFunction UI
|
server_application.allowed_users
| Installation.yaml Configuration |
Details |
server_application:
allowed_users: "name@email.com, name2@email.com"
|
- This allows non-Administrators to access a vFunction Application
- The Key takes a list of comma-separated email addresses
|
server_application.new_user_default_password
| Installation.yaml Configuration |
Details |
server_application:
new_user_default_password: "Password1!"
|
- New users need a one-time password to finish their Account Creation. This allows for the Default New User Password to be created automatically
|
Optional fields in global.yaml
agent.use_java_6_or_7_jre
| Global.yaml Configuration |
Details |
agent:
use_java_6_or_7_jre: true
|
- By default, the vFunction installation is configured to install an Agent intended to work with Applications that run using Java 8, 11 or 17
- This global.yaml setting is commented out to the default value of false
- By uncommenting this Key and setting the value to true, the vFunction Agent intended to work with Applications that run using Java 6 or 7 will be installed
|
controller.poll_interval_secs
| Global.yaml Configuration |
Details |
controller:
poll_interval_secs: 10
|
- Polling is the interval for the Controller to ask the vFunction Server what it should be doing
- If the Controller is not in a state of active learning, the Controller will poll the server to see what it should be doing
- If not explicitly defined, the default interval of 5 seconds is used
|
controller.upload_interval_secs
| Global.yaml Configuration |
Details |
controller:
upload_interval_secs: true
|
- The interval when the Controller will attempt to upload all of the Application's Call Stacks to the vFunction Server
- If not explicitly defined, the default interval of 15 seconds is used
|
general.custom_logs_folder
| Global.yaml Configuration |
Details |
general:
custom_logs_folder: C:\custom_log_directory\
|
- If not explicitly defined, the default logs directory is BASE_INSTALL_DIRECTORY\logs\
|
general.custom_sleep_after_service_start
| Global.yaml Configuration |
Details |
general:
custom_sleep_after_service_start: 10
|
- The amount of wait time after the Controller or Viper Services are started before looking for an associated Process ID
- If not explicitly defined, the default value of 1 is used
|
general.custom_sleep_after_service_stop
| Global.yaml Configuration |
Details |
general:
custom_sleep_after_service_stop: 10
|
- The amount of wait time after the Controller or Viper Services are stopped before looking for an associated Process ID
- If not explicitly defined, the default value of 1 is used
|
proxy.url
| Global.yaml Configuration |
Details |
proxy:
url: http://proxy_url:8172
|
- If traffic from a Controller to a vFunction Server needs to be routed through an intermediary, the Proxy address and Port can be defined here
|
viper.use_machine_java_for_viper
| Global.yaml Configuration |
Details |
viper:
use_machine_java_for_viper: true
|
- The vFunction Controller Installation ZIP includes an OpenJDK JRE for Viper
- Use this value if Java 17 is already installed on the machine and a separate version is not required
- To reduce the size of the vFunction Controller Installation ZIP, the OpenJDK JRE can also be removed from the ZIP and this value can be set to true to be able to reduce the package size by roughly 30mb
|
Client Certificates for a Controller
Adding a Client Certificate and Key to the Controller allows for the vFunction Server and Controller to have some form of verification.
The Controller loads and sends the Client Certificates to a Server that verifies the source of the traffic. That Server could be set up as an intermediary that manages token validation, such as an IBM DataPower Gateway, before being sent onto the vFunction Server.
The vFunction Nginx Container could also be configured to “ssl_verify_client on” and point to the Client Certificate which would be loaded on the Nginx Container’s filesystem somewhere like /etc/nginx/certs/ca.crt.
To use Client Certificates, place a client_certificate.crt and client_certificate.key file into the vFunction Instance’s Configuration directory. For example:
- C:\vfunction\config\installation\instances\default-java\client_certificate.crt
C:\vfunction\config\installation\instances\default-java\client_certificate.key
The contents of the client_certificate.crt should be formatted as:
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
The contents of the client_certificate.key should be formatted as:
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----