Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

CF app route unmap

Temporarily unmap a route from a Cloud Foundry app so you can test how upstream consumers behave when the app becomes unreachable via that route.

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 --hostname --path .

Common configurations

Unmap a path-based route

Unmap a TCP route

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:

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:

  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:

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

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:

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

Last updated

Was this helpful?