> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-route-unmap.md).

# CF app route unmap

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.

{% hint style="info" %}
**RUN YOUR FIRST EXPERIMENT**

If you have not configured the chaos infrastructure yet, go to [Quickstart](/resilience-testing/chaos-engineering/new-to-chaos-engineering/quickstart.md) to install the Linux chaos infrastructure and run an experiment end to end.
{% endhint %}

***

### Use cases <a href="#use-cases" id="use-cases"></a>

* **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 <a href="#before-you-begin" id="before-you-begin"></a>

* **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 <a href="#supported-environments" id="supported-environments"></a>

| 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 <a href="#permissions-required" id="permissions-required"></a>

| 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 <a href="#authentication" id="authentication"></a>

| 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 <a href="#fault-tunables" id="fault-tunables"></a>

**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](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md).

***

### Fault execution in brief <a href="#fault-execution-in-brief" id="fault-execution-in-brief"></a>

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 <a href="#expected-behavior-during-fault-execution" id="expected-behavior-during-fault-execution"></a>

* 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 <a href="#signals-to-watch" id="signals-to-watch"></a>

* **Route reachability:** Use an [HTTP probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/http-probe.md) 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 <a href="#recovery-and-cleanup" id="recovery-and-cleanup"></a>

* 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 <a href="#limitations" id="limitations"></a>

* 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 <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>CF app route unmap fails with 'route not found' in Harness Chaos Engineering</summary>

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

</details>

<details>

<summary>Route was not re-mapped after the experiment ended</summary>

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

</details>

***

### Common configurations <a href="#common-configurations" id="common-configurations"></a>

#### Unmap a path-based route <a href="#unmap-a-path-based-route" id="unmap-a-path-based-route"></a>

```yaml
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 <a href="#unmap-a-tcp-route" id="unmap-a-tcp-route"></a>

```yaml
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"
```

***

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:

```env
CF_API_ENDPOINT=XXXXXXXXXXXXXXXXXXX
CF_USERNAME=XXXXXXXXXXXXXXXXXXXXXXX
CF_PASSWORD=XXXXXXXXXXXXXXXXXXXXXXX
UAA_SERVER_ENDPOINT=XXXXXXXXXXXXXXX
```

{% hint style="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.
{% endhint %}

| 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 <a href="#fault-injector-envs-and-config-file" id="fault-injector-envs-and-config-file"></a>

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

```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    |

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
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 <a href="#related-faults" id="related-faults"></a>

* [CF app stop](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-stop.md): Stop the entire app rather than only its route.
* [CF app container kill](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-container-kill.md): Kill a container instance instead of unmapping a route.