Java agent installation with VMware Tanzu Application Service

VMware Tanzu (Application Service formerly Pivotal Cloud Foundry) is a proprietary containerized Software as a Service (SaaS) environment. A Java buildpack that VMware releases makes the Contrast Java agent accessible. You install the buildpack in the container where you run your Java application.

Contrast service

The existence of a single, bound Contrast service activates and downloads the Java agent. The VCAP_SERVICES payload, containing a service name, label or tag with contrast-security as a substring, defines the Contrast service. You can use either of these methods to create the Contrast service:

User-provided service: A user-provided service is a simple way to bind a single application to the Java agent and configure authentication.
A service broker (Contrast tile): Use the service broker to bind multiple applications, providing access to the Java agent and authentication.

When the Contrast service is bound to your application, it provides the strings needed to activate Contrast (puts the javaagent flag in the JVM) and provides authentication to the Contrast web interface.

Java buildpacks

Java buildpacks contain the instructions and configuration information that the container needs to download and configure the Java agent. You can use an offline or online buildpack:

An offline buildpack is typically forked from the GitHub repo where you have made customizations. These repos might contain older agent versions.
An online buildpack is usually the latest version and pulled from GitHub when needed.

Requirements

Buildpacks
To instrument an application in a VMware Tanzu Network environment, your application must use one of these buildpacks:
- Cloud Foundry Java Buildpack, version 3.19 and later or version 4.2 and later
- IBM Liberty Buildpack, version 2.7.0.2 and later
Name or tag with contrast-security specified when you create the service
The credential payload must contain the standard YAML properties.

For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to the Configuration and Extension section of the Cloud Foundry Java Buildpack documentation.

Configuration options

You can configure the framework by modifying the config/contrast_security_agent.yml file in the buildpack fork. The framework uses the Repository utility support and supports the version syntax defined there.

Name	Description
`repository_root`	The URL of the Contrast Security repository index
`version`	The version of the Contrast agent to use

To specify a version of the Java agent to use, set the JBP_CONFIG_CONTRASTSECURITYAGENT environment variable and specify a version listed in the index. For example:

JBP_CONFIG_CONTRASTSECURITYAGENT='version: 4.13.1'

Example

This example shows how to create a user-provided service and bind it to an application called spring-petclinic:

This command pushes an application to Cloud Foundry, providing the buildpack to be used: (otherwise the default buildpack is used in the environment)
```
cf push myApp -p target/spring-petclinic-2.4.2.jar \
  -b 'https://github.com/cloudfoundry/java-buildpack.git'
```
This command creates a user-provided service:
```
cf create-user-provided-service contrast-security-service -p "teamserver_url, username, api_key, service_key"
```
The value for teamserver_url should include only the protocol and hostname. Do not include /contrast/ or /contrast/api.
This command binds the service to the application (this tåsk is essential):
```
cf bind-service myApp contrast-security-service
```
This command restages the application so it can connect to Contrast (essentially, restarts the container):
```
cf restage myApp
```