CF app JVM modify return
CF app JVM modify return is a Cloud Foundry chaos fault that overrides the return value of a specific JVM method (class.method) inside a running Java app. Every invocation of the method returns the value you provide in return for duration seconds, after which the method behaves normally again.
Use this fault to simulate corrupted upstream data, unexpected null returns, stale cache values, or wrong-type responses, and validate the caller's defensive checks, fallbacks, and observability.
If you have not configured the chaos infrastructure yet, go to Quickstart to install the Linux chaos infrastructure and run an experiment end to end.
Use cases
- Null-safety validation: Confirm callers handle
nullreturns from a method that normally returns a value. - Corrupted-data resilience: Test the caller's response to obviously-wrong return values.
- Feature-flag bypass: Force a method to return a specific value (for example,
false) to short-circuit a flag and exercise the disabled code path. - Cache poisoning rehearsal: Simulate a poisoned cache layer returning incorrect values.
Before you begin
- Chaos infrastructure: A Linux chaos infrastructure (LCI) installed in one of the supported deployment models.
- CF and BOSH credentials: The LCI host has
CF_*,UAA_SERVER_ENDPOINT, andBOSH_*credentials configured. - Target identifiers: You know the
organization,space,app, and theboshDeployment. - Java app: The target app exposes a JVM agent on
port(default9091). - Return-type compatibility: The value you provide in
returnis assignable to the method's declared return type.
Supported environments
| Platform | Support status |
|---|---|
| Java apps deployed to Cloud Foundry | Supported |
| Non-Java workloads | Not supported |
Permissions required
| Action | Requirement |
|---|---|
| List apps the CF user can access | SpaceDeveloper, SpaceAuditor, OrgManager, or OrgAuditor; scopes cloud_controller.read or cloud_controller.admin |
| List BOSH deployments | BOSH user with bosh.read scope |
| SSH to a Diego cell via BOSH | BOSH UAA token with bosh.ssh or bosh.admin scope |
| Attach the JVM agent to the target container | Operator with sudo or root on the cell host |
Authentication
| Layer | Where to provide | Tunables |
|---|---|---|
| Cloud Foundry API + BOSH director | /etc/linux-chaos-infrastructure/cf.env on the LCI host | CF_API_ENDPOINT, CF_USERNAME, CF_PASSWORD, UAA_SERVER_ENDPOINT, BOSH_CLIENT, BOSH_CLIENT_SECRET, BOSH_CA_CERT, BOSH_ENVIRONMENT |
vSphere (only when faultInjectorLocation: vSphere) | /etc/linux-chaos-infrastructure/vsphere.env | GOVC_URL, GOVC_USERNAME, GOVC_PASSWORD, GOVC_INSECURE, VM_NAME, VM_USERNAME, VM_PASSWORD |
Fault tunables
Required parameters
| Tunable | Description | Default |
|---|---|---|
deploymentModel | LCI placement model. One of model-1 or model-2. | (required) |
organization | CF organization that owns the app. | (required) |
space | CF space within the organization. | (required) |
app | Java app whose method is targeted. | (required) |
class | Fully qualified class name. | (required) |
method | Method on class to instrument. | (required) |
return | Value to return from every invocation. Must be assignable to the method's declared return type (for example, null, false, 0, "failure"). | (required) |
Chaos parameters
| Tunable | Description | Default |
|---|---|---|
port | JVM agent port inside the container. | 9091 |
javaHome | Value of JAVA_HOME. | "" |
instanceAffectedPercentage | Percentage of instances to target. 0 targets exactly one. | 0 |
boshDeployment | BOSH deployment name. Required for deploymentModel: model-2. | "" |
faultInjectorLocation | local or vSphere. Required for deploymentModel: model-2. | local |
faultInjectorPort | Local port used by the fault-injector. | 50320 |
duration | Total chaos duration. | 30s |
skipSSLValidation | Skip SSL validation when calling CF APIs. | false |
rampTime | Wait period in seconds before and after the fault. | 0 |
Tunables that apply to every fault are documented in common tunables for all faults.
Fault execution in brief
Authenticates to Cloud Foundry and BOSH, locates the target app instance(s), attaches an agent to the JVM via the debug port, and installs a rule that returns the configured return value for every call to class.method. The rule is removed when duration elapses.
Expected behavior during fault execution
- Every invocation of the targeted method returns the configured
returnvalue, bypassing the method's normal body. - Callers observe whatever happens next given the unexpected value: fallbacks, defensive checks, downstream errors.
- After the fault ends, the method returns to its normal behavior.
Signals to watch
- Caller response: Use an HTTP probe on an endpoint that calls the method and assert the expected fallback or error response.
- Logs: Verify the caller logs the unexpected value at the right severity.
Recovery and cleanup
- The instrumentation is removed at the end of
duration, restoring the method's normal behavior.
Limitations
- Matches methods by name only; overloaded methods on the same class all receive the override.
- The return value must be expressible as a literal compatible with the declared return type. Complex object construction is not supported.
Troubleshooting
CF app JVM modify return: agent rejects the configured return value
The value in return must be assignable to the method's declared return type. For object returns, common choices are null or a static reference. For primitive returns use the literal form (true, false, 0, 42).
Caller still observes the original return value
The method may have been JIT-inlined before the agent attached. Restart the app instance and rerun the experiment so the method is recompiled with the instrumentation in place.
Common configurations
Force a method to return null
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
name: cf-app-jvm-modify-return
labels:
name: app-jvm-modify-return
spec:
cfAppJVMChaos/inputs:
duration: 30s
deploymentModel: model-2
faultInjectorLocation: vSphere
app: cf-app
organization: dev-org
space: dev-space
boshDeployment: cf
class: com.example.UserRepository
method: findById
return: "null"
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
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.envfile- 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 |
Related faults
- CF app JVM method exception: Make the method throw an exception instead of returning a wrong value.
- CF app JVM method latency: Make the method slow.