> 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-network-loss.md).

# CF app network loss

CF app network loss is a Cloud Foundry chaos fault that drops `packetLossPercentage` percent of egress packets from one or more app instances of `app` in `organization`/`space`. You can restrict the loss to specific destination hosts, IP ranges, source ports, or destination ports. The fault lasts for `duration` seconds.

Use this fault to test how the app and its callers handle a flaky or congested network: TCP retransmissions, application-level retries, timeouts, circuit-breaker decisions, and downstream error propagation.

{% 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>

* **Retry resilience:** Confirm the app retries lost requests within budget instead of giving up immediately or piling on.
* **Timeout tuning:** Validate timeouts are set high enough to absorb the added retransmissions.
* **Circuit-breaker thresholds:** Confirm the breaker opens at the configured loss/error rate.
* **Targeted partition:** Drop traffic only to a specific dependency to test single-dependency failure modes.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **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`, and `BOSH_*` credentials configured.
* **Target identifiers:** You know the `organization`, `space`, `app`, and the `boshDeployment`.
* **Network interface:** You know the interface name inside the container (typically `eth0`).
* **Destinations:** You know the host(s), IP range(s), or port(s) you want to disrupt. Leave blank to affect all egress.

***

### Supported environments <a href="#supported-environments" id="supported-environments"></a>

| Platform                                                                  | Support status |
| ------------------------------------------------------------------------- | -------------- |
| Cloud Foundry (TAS, PCF, open-source) running on BOSH-managed Diego cells | Supported      |

***

### Permissions required <a href="#permissions-required" id="permissions-required"></a>

| 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                                                                        |
| Apply traffic-shaping rules inside the target container's namespace | Operator with `sudo` or root on the cell host                                                                               |

***

### Authentication <a href="#authentication" id="authentication"></a>

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

**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`             | App whose egress traffic loses packets.             | (required) |

**Chaos parameters**

| Tunable                      | Description                                                                    | Default |
| ---------------------------- | ------------------------------------------------------------------------------ | ------- |
| `packetLossPercentage`       | Percentage of egress packets to drop (0-100).                                  | `100`   |
| `networkInterface`           | Network interface inside the container.                                        | `eth0`  |
| `destinationHosts`           | Comma-separated list of hostnames to affect. Leave empty to affect all egress. | `""`    |
| `destinationIPs`             | Comma-separated list of destination IPs or CIDRs to affect.                    | `""`    |
| `sourcePorts`                | Comma-separated list of source ports to affect.                                | `""`    |
| `destinationPorts`           | Comma-separated list of destination ports to affect.                           | `""`    |
| `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](/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 and BOSH, locates the target app instance(s), and installs a traffic-shaping rule on `networkInterface` inside the container's network namespace that drops `packetLossPercentage`% of packets matching the configured destinations/ports. The rule is removed when `duration` elapses.

***

### Expected behavior during fault execution <a href="#expected-behavior-during-fault-execution" id="expected-behavior-during-fault-execution"></a>

* TCP connections to affected destinations experience retransmissions; round-trip time may rise.
* Application-level retries fire if configured; otherwise requests fail with timeout or connection-reset errors.
* After the fault ends, packet loss returns to baseline.

#### Signals to watch <a href="#signals-to-watch" id="signals-to-watch"></a>

* **Caller error rate:** Use an [HTTP probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/http-probe.md) and assert error rate stays within SLO.
* **TCP retransmissions:** Inspect host-level network metrics on the cell hosting the affected instance.

***

### Recovery and cleanup <a href="#recovery-and-cleanup" id="recovery-and-cleanup"></a>

* The traffic-shaping rule is removed at the end of `duration`.
* If the experiment is aborted, the fault still attempts to remove the rule before exiting.

***

### Limitations <a href="#limitations" id="limitations"></a>

* Operates on the egress side only. Ingress packet loss is not simulated.
* Without a destination filter, ALL egress traffic loses packets, which can break control-plane communication.
* At `packetLossPercentage: 100`, the destination is effectively unreachable; use [CF app stop](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-stop.md) or [CF app route unmap](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-route-unmap.md) for cleaner outage simulation.

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>CF app network loss: no observable failures in Harness Chaos Engineering</summary>

Confirm packetLossPercentage is set (the default of 100 drops all matching traffic). Confirm networkInterface matches the interface inside the container. Confirm destination filters match actual traffic.

</details>

<details>

<summary>App becomes completely unreachable during the experiment</summary>

With no destination filters and packetLossPercentage of 100, all egress (including health checks and platform calls) is dropped. Add destinationHosts or destinationIPs to scope the loss to your dependency.

</details>

***

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

#### Drop 50% of traffic to one downstream <a href="#drop-50percent-of-traffic-to-one-downstream" id="drop-50percent-of-traffic-to-one-downstream"></a>

```yaml
apiVersion: litmuchaos.io/v1alpha1
kind: LinuxFault
metadata:
  name: cf-app-network-loss
  labels:
    name: app-network-loss
spec:
  cfAppNetworkChaos/inputs:
    duration: 60s
    deploymentModel: model-2
    faultInjectorLocation: vSphere
    app: cf-app
    organization: dev-org
    space: dev-space
    boshDeployment: cf
    networkInterface: eth0
    packetLossPercentage: 50
    destinationHosts: payments-api.internal
```

***

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
BOSH_CLIENT=XXXXXXXXXXXXXXXXXXXXXXX
BOSH_CLIENT_SECRET=XXXXXXXXXXXXXXXX
BOSH_CA_CERT=XXXXXXXXXXXXXXXXXXXXXX
BOSH_ENVIRONMENT=XXXXXXXXXXXXXXXXXX
```

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

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 network latency](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-network-latency.md): Delay packets instead of dropping them.
* [CF app network corruption](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/cloud-foundry/cf-app-network-corruption.md): Corrupt packets so the receiver discards them.