> 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/byoc/byoc-injector.md).

# BYOC Injector

BYOC (Bring Your Own Chaos) injector enables the execution of custom chaos faults using a special helper pod. The BYOC injector is designed to be flexible and easy to use, allowing users to define their own chaos experiments using a simple YAML specification.

![BYOC Injector](/files/7xOfmd2t8TAfG9N8O0Ti)

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

BYOC injector:

* Validates the resilience of an application by introducing custom faults in critical service dependencies and observing the impact on overall system functionality.
* Injects custom faults to simulate disaster scenarios, ensuring that the application's disaster recovery procedures are effective and efficient.
* Implements custom faults to verify that the system meets compliance and regulatory requirements under adverse conditions, such as data corruption or service outages.

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* Kubernetes > 1.16

#### Mandatory tunables <a href="#mandatory-tunables" id="mandatory-tunables"></a>

| Tunable             | Description                                                                    | Notes                                                                       |
| ------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| BYOC\_HELPER\_IMAGE | Image of the helper pod that contains the business logic for the custom fault. | For more information, go to [byoc helper image](#chaos-script-in-lib_image) |
| COMMAND             | Command to execute in the helper pod.                                          | For more information, go to [command](#chaos-script-contained-lib_image)    |
| ARGS                | Arguments to execute in the helper pod.                                        | For more information, go to [args](#chaos-script-contained-lib_image)       |

#### Optional tunables <a href="#optional-tunables" id="optional-tunables"></a>

| Tunable    | Description                                                   | Notes                                                                                                                                                                       |
| ---------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RAMP\_TIME | Period to wait before and after injecting chaos (in seconds). | For example, 30s. For more information, go to [ramp time.](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md#ramp-time) |

#### Examples <a href="#examples" id="examples"></a>

BYOC injector supports two modes of execution:

1. `Chaos script contained BYOC_HELPER_IMAGE`: The chaos script is included in the `BYOC_HELPER_IMAGE`.
2. `Chaos script mounted as volume`: The script is not be included in the `BYOC_HELPER_IMAGE`. Instead, it is mounted as a volume inside the helper pod, and `COMMAND` and `ARGS` will be used to execute the script.

**Chaos script in LIB\_IMAGE**

The `LIB_IMAGE` environment variable specifies the image of the helper pod that contains the business logic of the custom fault. Specify the `COMMAND` and `ARGS` for the helper pod to execute the custom fault.

The following YAML snippet illustrates the use of this environment variable:

```yaml
# run a self-contained lib image experiment <a href="#run-a-self-contained-lib-image-experiment" id="run-a-self-contained-lib-image-experiment"></a>
apiVersion: litmuschaos.io/v1alpha1
kind: ChaosEngine
metadata:
  name: engine-nginx
spec:
  engineState: active
  terminationGracePeriodSeconds: 30
  chaosServiceAccount: litmus-admin
  experiments:
    - name: byoc-injector
      imagePullPolicy: Always
      args:
        - -c
        - ./experiments -name byoc-injector
      command:
        - /bin/bash
      spec:
        components:
          secrets:
            - name: aws-secret
              mountPath: /etc/secret
          env:
            - name: SSH_USER
              value: "ec2-user"
            - name: SSH_HOST
              value: "ec2-host.us-east-2.compute.amazonaws.com"
            - name: SSH_KEY
              value: "/etc/secret/key.pem"
            - name: INTERVAL
              value: "2"
            - name: DURATION
              value: "120"
            - name: BYOC_HELPER_IMAGE
              value: "<lib image with chaos script>"
            - name: COMMAND
              value: "/bin/sh"
            - name: ARGS
              value: "-c,sh script.sh"
```

**Mounted chaos script**

The script is not included in the `BYOC_HELPER_IMAGE`. Instead, it is mounted as a volume inside the helper pod, and `COMMAND` and `ARGS` will be used to execute the script.

The following YAML snippet illustrates the use of this environment variable:

```yaml
# run a mounted chaos script experiment <a href="#run-a-mounted-chaos-script-experiment" id="run-a-mounted-chaos-script-experiment"></a>
apiVersion: litmuschaos.io/v1alpha1
kind: ChaosEngine
metadata:
  name: engine-nginx
spec:
  engineState: active
  terminationGracePeriodSeconds: 30
  chaosServiceAccount: litmus-admin
  experiments:
    - name: byoc-injector
      imagePullPolicy: Always
      args:
        - -c
        - ./experiments -name byoc-injector
      command:
        - /bin/bash
      spec:
        components:
          configMaps:
            # chaos script mounted as configMap
            - name: chaos-script
              mountPath: /etc/config
          secrets:
            - name: aws-secret
              mountPath: /etc/secret
          env:
            - name: SSH_USER
              value: "ec2-user"
            - name: SSH_HOST
              value: "ec2-host.us-east-2.compute.amazonaws.com"
            - name: SSH_KEY
              value: "/etc/secret/key.pem"
            - name: INTERVAL
              value: "2"
            - name: DURATION
              value: "120"
            - name: BYOC_HELPER_IMAGE
              value: "<lib image with ssh binary>"
            - name: COMMAND
              value: "/bin/sh"
            - name: ARGS
              value: "-c,sh /etc/config/script.sh"
```

#### Configure the advanced tunables <a href="#configure-the-advanced-tunables" id="configure-the-advanced-tunables"></a>

Configure the following advanced tunables for the BYOC injector:

{% hint style="info" %}
Specify these tunables in the chaos engine.
{% endhint %}

* `NodeSelector`: Map of key-value pairs. For the helper pod to be executed on the nodes with the corresponding labels, the `NodeSelector` field should be specified in the chaos engine.
* `Tolerations`: Tolerations for the helper pod to be executed on the nodes with the corresponding taints.
* `HostPID`: Whether the helper pod should share the PID namespace with the host.
* `ConfigMaps`: ConfigMaps that need to be mounted as volumes in the helper pod.
* `Secrets`: Secrets that need to be mounted as volumes in the helper pod.
* `HostFileVolumes`: Host file volumes that need to be mounted as volumes in the helper pod.
* `SecurityContext`: Security context for the helper pod.

The following YAML snippet illustrates the use of these advance tunables:

```yaml
# provide advanced tunables for the byoc-injector experiment <a href="#provide-advanced-tunables-for-the-byoc-injector-experiment" id="provide-advanced-tunables-for-the-byoc-injector-experiment"></a>
apiVersion: litmuschaos.io/v1alpha1
kind: ChaosEngine
metadata:
  name: engine-nginx
spec:
  engineState: active
  terminationGracePeriodSeconds: 30
  chaosServiceAccount: litmus-admin
  experiments:
    - name: byoc-injector
      imagePullPolicy: Always
      args:
        - -c
        - ./experiments -name byoc-injector
      command:
        - /bin/bash
      spec:
        components:
          # node selector to target a specific node
          nodeSelector:
            chaos-enabled: "true"
          # tolerations to target master nodes
          tolerations:
            - key: "node-role.kubernetes.io/master"
              operator: "Exists"
              effect: "NoSchedule"
          # hostPID to enable the hostPID
          hostPID: true
          # mounted configMaps
          configMaps:
            - name: chaos-script
              mountPath: /etc/config
          # mounted secrets
          secrets:
            - name: aws-secret
              mountPath: /etc/secret
          # hostFileVolumes to mount the host file
          hostFileVolumes:
            - mountPath: /run/containerd/containerd.sock
              name: socketPath
              nodePath: /run/containerd/containerd.sock
          # provide the security context
          securityContext:
            # pod security context to run the pod as root user
            podSecurityContext:
              runAsUser: 0
            # container security context to run the container in privileged mode
            containerSecurityContext:
              privileged: true
          env:
            - name: SSH_USER
              value: "ec2-user"
            - name: SSH_HOST
              value: "ec2-host.us-east-2.compute.amazonaws.com"
            - name: SSH_KEY
              value: "/etc/secret/key.pem"
            - name: INTERVAL
              value: "2"
            - name: DURATION
              value: "120"
            - name: BYOC_HELPER_IMAGE
              value: "<lib image with ssh binary>"
            - name: COMMAND
              value: "/bin/sh"
            - name: ARGS
              value: "-c,sh /etc/config/script.sh"
```