CF app JVM method exception

CF app JVM method exception causes a Java based Cloud Foundry app's method to throw a given exception.

Use cases

CF app JVM method exception:

• Verifies an application's ability to recover gracefully from unexpected exceptions.
• Uncovers issues in error handling logic during development.
• Simulates real-world errors to strengthen the application's ability to handle them.
• Helps gain confidence in the application's ability to function during potential failures.
• Evaluates how exceptions impact resource allocation and de-allocation strategies.

Mandatory tunables

Tunable	Description	Notes
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.
class	The target Java class where the method lies. It should be provided in the format: package-name.class-name	For example, Inventory
method	The target Java class method.	For example, AddToInventory
exception	The exception which will be thrown by the method.	For example, NullPointerException("Something went wrong, NullPointerException!")
deploymentModel	The deployment model used for setting up the fault injector. It supports model-1 and model-2. Model-1 assumes that the fault-injector exists within a diego cell VM whereas Model-2 assumes that the fault-injector exists within a jumpbox VM.	Supports model-1 and model-2. For more information, go to Deployment Model.

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.
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.	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:

1. /etc/linux-chaos-infrastructure/cf.env file
2. Environment variables
3. 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

Class

The class input specifies the Java class whose method will be targeted. Provide it as: package-name.class-name.

The following YAML snippet illustrates the use of this input:

# class
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    class: com.appinventory.appinventory.appInventoryController
    duration: 30s
    app: cf-app
    organization: dev-org
    space: dev-space
    boshDeployment: cf

Exception

The exception input specifies the exception that is thrown by the target method.

The following YAML snippet illustrates the use of this input:

# exception
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    class: com.appinventory.appinventory.appInventoryController
    method: AddToInventory
    duration: 30s
    app: cf-app
    exception: NullPointerException("Some error occurred, NullPointerException!")
    organization: dev-org
    space: dev-space
    boshDeployment: cf

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.

The following YAML snippet illustrates the use of this input:

# bosh deployment
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    duration: 30s
    faultInjectorLocation: vSphere
    app: cf-app
    organization: dev-org
    space: dev-space
    boshDeployment: cf

Instance affected percentage

The instanceAffectedPercentage input specifies the percentage of total number of app instances that will be targeted. It defaults to 0 (1 instance).

The following YAML snippet illustrates the use of this input:

# instance affected percentage
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    duration: 30s
    faultInjectorLocation: vSphere
    app: cf-app
    organization: dev-org
    space: dev-space
    boshDeployment: cf
    instanceAffectedPercentage: 50

Fault injector location

The faultInjectorLocation input determines the location of the fault injector with respect to the infrastructure. It is the location where the fault-injector utility is executed.

• It can be local, that is, the same environment used by the infrastructure, or a remote machine.

The following YAML snippet illustrates the use of this input:

# cf deployment platform
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    duration: 30s
    faultInjectorLocation: vSphere
    app: cf-app
    organization: dev-org
    space: dev-space

Skip SSL validation

The skipSSLValidation input variable determines whether to skip SSL validation for calling the CF APIs.

The following YAML snippet illustrates the use of this input:

# skip ssl validation for cf
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    duration: 30s
    faultInjectorLocation: vSphere
    app: cf-app
    organization: dev-org
    space: dev-space
    skipSSLValidation: true

Fault injector port

The faultInjectorPort input determines the port used for the fault-injector local server.

The following YAML snippet illustrates the use of this input:

# fault injector port
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-jvm-method-exception
  labels:
    name: app-jvm-method-exception
spec:
  cfAppJVMChaos/inputs:
    duration: 30s
    faultInjectorLocation: local
    app: cf-app
    organization: dev-org
    space: dev-space
    faultInjectorPort: 50331