CF app JVM memory stress

CF app JVM memory stress injects memory stress into a Java based Cloud Foundry app's JVM.

CF App JVM Memory Stress

Use cases

CF app JVM memory stress applies memory stress to:

Evaluate the performance and efficiency of the garbage collector under high memory usage.
Identify the potential memory leaks and ensure proper resource cleanup.
Test the application's response and recovery mechanisms when facing OutOfMemoryError.
Simulate high memory usage to determine application performance and stability under peak memory load conditions.
Assess how well the application scales and handles large datasets or high user concurrency.

Mandatory tunables

Tunable	Description	Notes
deploymentModel	The deployment model being used for Linux Chaos Infrastructure + Cloud Foundry Fault Injector. For more information, refer here.	One of: `model-1`,`model-2`. No default value is assumed, if the tunable is not provided. For `model-1`, `boshDeployment` and `faultInjectorLocation` inputs are not required.
organization	Organization where the target app resides.	For example, `dev-org`.
space	Space where the target app resides.	The space must reside within the given organization. For example, `dev-space`.
app	The app in which chaos will be injected.	The app must reside within the given organization and space. For example, `cf-app`.

Optional tunables

Tunable	Description	Notes
javaHome	Value of the `JAVA_HOME` environment variable.	Not required if the Java binary file path is added to the Linux `PATH` env or `JAVA_HOME` env is added to the Linux `PATH` env.
memory	The type of memory to stress.	Default: `heap`. Can be one of: `heap` or `stack`.
instanceAffectedPercentage	Percentage of total number of app instances that will be targeted.	Default: 0 (1 instance). For more information, go to instance affected percentage.
faultInjectorPort	Local server port used by the fault-injector utility.	Default: `50320`. If the default port is unavailable, a random port in the range of `50320-51320` is selected. For more information, go to fault injector port.
duration	Duration through which chaos is injected into the target resource (in seconds).	Default: 30s. For more information, go to chaos duration.
skipSSLValidation	Skip SSL validation while invoking CF APIs.	Supports `true` and `false`. Default: `false`. For more information, go to skip SSL validation.
rampTime	Period to wait before and after injecting chaos (in seconds).	Defaults to 0.
boshDeployment	The bosh deployment under which the CF components are being managed.	It can be obtained using the BOSH CLI command `bosh deployments`. For more information, go to BOSH deployment.
faultInjectorLocation	Location of the fault injector with respect to the cloud foundry vms.	Default: `local`. Supports `local` and `vSphere`. For more information, go to Fault Injector location.

CF secrets

The following Cloud Foundry secrets reside on the same machine where the chaos infrastructure is executed. These secrets are provided in the /etc/linux-chaos-infrastructure/cf.env file in the following format:

CF_API_ENDPOINT=XXXXXXXXXXXXXXXXXXX
CF_USERNAME=XXXXXXXXXXXXXXXXXXXXXXX
CF_PASSWORD=XXXXXXXXXXXXXXXXXXXXXXX
UAA_SERVER_ENDPOINT=XXXXXXXXXXXXXXX
BOSH_CLIENT=XXXXXXXXXXXXXXXXXXXXXXX
BOSH_CLIENT_SECRET=XXXXXXXXXXXXXXXX
BOSH_CA_CERT=XXXXXXXXXXXXXXXXXXXXXX
BOSH_ENVIRONMENT=XXXXXXXXXXXXXXXXXX

info

If the secrets file is not provided, the secrets are attempted to be derived from environment variables and the config file by the fault-injector.

ENV name	Description	Example
CF_API_ENDPOINT	API endpoint for the CF setup	`https://api.system.cf-setup.com`
CF_USERNAME	Username for the CF user	`username`
CF_PASSWORD	Password for the CF user	`password`
UAA_SERVER_ENDPOINT	API endpoint for the UAA server for the CF setup	`https://uaa.system.cf-setup.com`
BOSH_CLIENT	Used by the `bosh` CLI, the BOSH client	`admin`
BOSH_CLIENT_SECRET	Used by the `bosh` CLI, the BOSH client secret	`UBu9Fu3oW35sO6fw12auPH76gsRTy7`
BOSH_CA_CERT	Used by the `bosh` CLI, the file path for BOSH CA certificate	`/root/root_ca_certificate`
BOSH_ENVIRONMENT	Used by the `bosh` CLI, the BOSH environment	`bosh.corp.local`

Fault injector ENVs and config file

If /etc/linux-chaos-infrastructure/cf.env file is not provided, fault-injector attempts to derive the secrets from environment variables or a configuration file. Any secret that is re-declared will be overridden in the following order of decreasing precedence:

/etc/linux-chaos-infrastructure/cf.env file
Environment variables
Configuration file

The configuration file should be provided at /etc/linux-chaos-infrastructure/cf-fault-injector.yaml:

cf-api-endpoint: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
username: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
password: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uaa-server-endpoint: XXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-client: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-client-secret: XXXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-ca-cert: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
bosh-environment: XXXXXXXXXXXXXXXXXXXXXXXXXXXXX

A mapping between all the three formats for providing the secrets is as follows:

cf.env	ENV	cf-fault-injector.yaml
CF_API_ENDPOINT	CF_API_ENDPOINT	cf-api-endpoint
CF_USERNAME	USERNAME	username
CF_PASSWORD	PASSWORD	password
UAA_SERVER_ENDPOINT	UAA_SERVER_ENDPOINT	uaa-server-endpoint
BOSH_CLIENT	BOSH_CLIENT	bosh-client
BOSH_CLIENT_SECRET	BOSH_CLIENT_SECRET	bosh-client-secret
BOSH_CA_CERT	BOSH_CA_CERT	bosh-ca-cert
BOSH_ENVIRONMENT	BOSH_ENVIRONMENT	bosh-environment

vSphere secrets

These secrets are provided only if vSphere is used as the deployment platform for CF.

The following vSphere secrets reside on the same machine where the chaos infrastructure is executed. These secrets are provided in the /etc/linux-chaos-infrastructure/vsphere.env file in the following format:

GOVC_URL=XXXXXXXXXXXXXXXXXXXXXX
GOVC_USERNAME=XXXXXXXXXXXXXXXXX
GOVC_PASSWORD=XXXXXXXXXXXXXXXXX
GOVC_INSECURE=XXXXXXXXXXXXXXXXX
VM_NAME=XXXXXXXXXXXXXXXXXXXXXXX
VM_USERNAME=XXXXXXXXXXXXXXXXXXX
VM_PASSWORD=XXXXXXXXXXXXXXXXXXX

ENV Name	Description	Notes
GOVC_URL	Endpoint for vSphere	For example, `192.168.214.244`
GOVC_USERNAME	Username for the vSphere user	For example, `username`
GOVC_PASSWORD	Password for the vSphere user	For example, `password`
GOVC_INSECURE	Skip SSL validation for govc commands	For example, `true`
VM_NAME	Name of the vSphere VM where the fault-injector utility is installed	For example, `cf-vm`
VM_USERNAME	Username for the VM guest user	For example, `root`
VM_PASSWORD	Password for the VM guest user	For example, `password`

Fault Permissions

List all applications the user or client has access to

Required Roles (any one):

SpaceDeveloper (in the app’s space)
SpaceAuditor (read-only role in the app’s space)
OrgManager or OrgAuditor (at the org level)

Required OAuth Scopes (for tokens):

cloud_controller.read
cloud_controller.admin
cloud_controller.global_auditor

List all BOSH deployments

Required Role:

BOSH user with read permissions (typically admin or a user with read access to deployments)

Required Auth:

Valid BOSH UAA token with bosh.read scope

Establish SSH session to a Diego Cell via BOSH SSH

Required Role:

BOSH user with SSH access permissions for the Diego Cell instance group

Required Auth:

BOSH UAA token with bosh.ssh or bosh.admin scope

Use `cfdot` to list LRPs and locate app containers

Required Role:

Operator with SSH access to a cell and executable access to cfdot

Required Auth:

Requires diego.read scope in BOSH UAA or access to the Diego BBS with a trusted client certificate

Use `ctr` (containerd CLI) to get container-level metadata and target PIDs

Required Role:

SSH-level access to the cell host and root access (or sudo) to interact with containerd

Required Auth:

None via API; local root or elevated user access is required

Download Byteman artifacts into the target container

Required Role:

Root or privileged access to copy files into the app container’s namespace using tools like nsenter or ctr

Required Auth:

None via API; file access is performed locally via root privileges

Inject JVM chaos using Byteman scripts inside target containers

Required Role:

Root access to attach Byteman agent and execute scripts within the JVM process namespace

Required Auth:

None via API; requires PID-level access to the target JVM and execution rights

Remove injected chaos by clearing Byteman rules

Required Role:

Same as above — continued root-level access to the JVM process namespace

Required Auth:

None via API; local cleanup via script execution with appropriate permissions

Deployment Model

The deploymentModel input specifies the LCI deployment model with respect to its placement in the host TAS VM.

It accepts one of: model-1, model-2.
No default value is assumed if the input is not provided, but the experiment execution fails with an error.

The following YAML snippet illustrates the use of this environment variable:

# deployment model for LCI
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-memory-stress
  labels:
    name: app-jvm-memory-stress
spec:
  cfAppJVMChaos/inputs:
    duration: 30s
    faultInjectorLocation: vSphere
    app: cf-app
    organization: dev-org
    space: dev-space
    deploymentModel: model-1

BOSH deployment

The boshDeployment input determines the BOSH deployment name under which all the CF resources are managed. You can obtain it using the BOSH CLI command bosh deployments.