CF app route unmap

Last updated on Jun 25, 2026

CF app route unmap is a Cloud Foundry chaos fault that detaches a specific route (host, path, optional port) from app in organization/space for duration seconds, then re-maps it. The app itself keeps running; only its inbound route is disrupted.

Use this fault to validate how consumers behave when an app stops being reachable via one of its routes: gateway retries, fallback responses, alerting on 404s from the router, and DNS-level fallbacks.

Run your first experiment

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

Gateway resilience: Confirm an upstream gateway or load balancer fails over correctly when one route returns 404 from the CF router.
Failover routes: Validate that secondary routes mapped to the same app continue serving traffic.
Consumer behavior: Test consumer retry, fallback, and circuit-breaker logic when a known endpoint disappears.
Operational drills: Practice the runbook for unintentional route removal.

Before you begin

Chaos infrastructure: A Linux chaos infrastructure (LCI) that can reach the Cloud Foundry API and UAA endpoints.
CF credentials: CF_API_ENDPOINT, CF_USERNAME, CF_PASSWORD, and UAA_SERVER_ENDPOINT available on the LCI host.
Target identifiers: You know the organization, space, app, host, and (if non-root) path and port of the route to unmap.
Route mapping exists: The route is currently mapped to the app (run cf routes to confirm).

Supported environments

Platform	Support status
Cloud Foundry (TAS, PCF, open-source)	Supported
Apps with only a default route	Supported (the default route is unmapped and re-mapped)

Permissions required

Action	Required role	Required OAuth scope
List apps and routes the user can access	`SpaceDeveloper`, `SpaceAuditor`, `OrgManager`, or `OrgAuditor`	`cloud_controller.read` or `cloud_controller.admin`
Unmap and re-map the route	`SpaceDeveloper` in the app's space	`cloud_controller.write` or `cloud_controller.admin`

Authentication

Layer	Where to provide	Tunables
Cloud Foundry API	`/etc/linux-chaos-infrastructure/cf.env` on the LCI host	`CF_API_ENDPOINT`, `CF_USERNAME`, `CF_PASSWORD`, `UAA_SERVER_ENDPOINT`
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
`organization`	CF organization that owns the app.	(required)
`space`	CF space within the organization.	(required)
`app`	Name of the app whose route is unmapped.	(required)
`host`	Host (subdomain) component of the route to unmap. For example, `my-app` for `my-app.apps.example.com`.	(required)

Chaos parameters

Tunable	Description	Default
`path`	Path component of the route. Leave empty to target the root route.	`""`
`port`	TCP port of the route. Required only for TCP routes.	`""`
`duration`	Total chaos duration. The route is re-mapped after this period.	`30s`
`faultInjectorLocation`	Where the fault-injector runs. Supports `local` and `vSphere`.	`local`
`faultInjectorPort`	Local port used by the fault-injector.	`50320`
`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, locates the route specified by host/path/port mapped to app, calls the CF API to unmap it, waits duration seconds, then re-maps the same route. Consumers hitting the route during the fault receive 404 from the CF router because the route no longer points at any app.

Expected behavior during fault execution

Requests to the unmapped route receive 404 Not Found from the Cloud Foundry router.
The app itself continues to serve other routes normally.
After the fault ends, the route is re-mapped and requests succeed again.

Signals to watch

Route reachability: Use an HTTP probe on the route under test and assert the expected failure mode during the chaos window.
Secondary route health: Probe alternative routes mapped to the same app and confirm they keep returning 2xx.

Recovery and cleanup

The fault re-maps the route automatically when duration elapses.
If the experiment is aborted, the fault still attempts to re-map the route on exit.

Limitations

Affects only the specific route identified by host/path/port. Other routes on the same app are unaffected.
The fault does not delete the route from CF, only its mapping to the app. The route definition itself remains.

Troubleshooting

CF app route unmap fails with 'route not found' in Harness Chaos Engineering

Run cf routes from the LCI host as CF_USERNAME and confirm the host/path/port combination is currently mapped to the app. The host must be the subdomain only (not the full FQDN).

Route was not re-mapped after the experiment ended

The fault attempts a re-map on cleanup. If it failed, manually re-map with cf map-route <app> <domain> --hostname <host> --path <path>.

Common configurations

Unmap a path-based route

apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-route-unmap
  labels:
    name: app-route-unmap
spec:
  cfAppRouteUnmap/inputs:
    duration: 60s
    faultInjectorLocation: local
    app: cf-app
    organization: dev-org
    space: dev-space
    host: my-app
    path: /api/v1

Unmap a TCP route

apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-route-unmap
  labels:
    name: app-route-unmap
spec:
  cfAppRouteUnmap/inputs:
    duration: 30s
    faultInjectorLocation: local
    app: cf-app
    organization: dev-org
    space: dev-space
    host: my-app
    port: "1024"

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

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`

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

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

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`

CF app stop: Stop the entire app rather than only its route.
CF app container kill: Kill a container instance instead of unmapping a route.

Use cases​

Before you begin​

Supported environments​

Permissions required​

Authentication​

Fault tunables​

Fault execution in brief​

Expected behavior during fault execution​

Signals to watch​

Recovery and cleanup​

Limitations​

Troubleshooting​

Common configurations​

Unmap a path-based route​

Unmap a TCP route​

CF secrets​

Fault injector ENVs and config file​

vSphere secrets​

Related faults​