Version: Next

ChaosExperiment

ChaosExperiment CR is the heart of litmus and contains the low-level execution information. They serve as off-the-shelf templates that one needs to "pull" (install on the cluster.md) before including them as part of a chaos run against any target applications (the binding being defined in the ChaosEngine). The experiments are installed on the cluster as Kubernetes custom resources and are designed to hold granular details of the experiment such as image, library, necessary permissions, chaos parameters (set to their default values). Most of the ChaosExperiment parameters, are essentially tunables that can be overridden from the ChaosEngine resource. The ChaosExperiment CRs are the primary artifacts hosted on the ChaosHub

This section describes the fields in the ChaosExperiment spec and the possible values that can be set against the same.

Scope Specification#

Field	`.spec.definition.scope`
Description	Flag to specify the scope of the ChaosExperiment
Type	Optional
Range	`Namespaced`, `Cluster`
Default	n/a (depends on experiment type)
Notes	The `.spec.definition.scope` specifies the scope of the experiment. It can be `Namespaced` scope for pod level experiments and `Cluster` for the experiments having a cluster wide impact.

Field	`.spec.definition.permissions`
Description	Flag to specify the minimum permission to run the ChaosExperiment
Type	Optional
Range	user-defined (type: list)
Default	n/a
Notes	The `.spec.definition.permissions` specify the minimum permission that is required to run the ChaosExperiment. It also helps to estimate the blast radius for the ChaosExperiment.

Component Specification#

Field	`.spec.definition.image`
Description	Flag to specify the image to run the ChaosExperiment
Type	Mandatory
Range	user-defined (type: string)
Default	n/a (refer Notes)
Notes	The `.spec.definition.image` allows the developers to specify their experiment images. Typically set to the Litmus `go-runner` or the `ansible-runner`. This feature of the experiment enables BYOC (BringYourOwnChaos), where developers can implement their own variants of a standard chaos experiment

Field	`.spec.definition.imagePullPolicy`
Description	Flag that helps the developers to specify imagePullPolicy for the ChaosExperiment
Type	Mandatory
Range	`IfNotPresent`, `Always` (type: string)
Default	`Always`
Notes	The `.spec.definition.imagePullPolicy` allows developers to specify the pull policy for ChaosExperiment image. Set to `Always` during debug/test

Field	`.spec.definition.args`
Description	Flag to specify the entrypoint for the ChaosExperiment
Type	Mandatory
Range	user-defined (type:list of string)
Default	n/a
Notes	The `.spec.definition.args` specifies the entrypoint for the ChaosExperiment. It depends on the language used in the experiment. For litmus-go the `.spec.definition.args` contains a single binary of all experiments and managed via `-name` flag to indicate experiment to run(`-name (exp-name)`).

Field	`.spec.definition.command`
Description	Flag to specify the shell on which the ChaosExperiment will execute
Type	Mandatory
Range	user-defined (type: list of string).
Default	`/bin/bash`
Notes	The `.spec.definition.command` specifies the shell used to run the experiment `/bin/bash` is the most common shell to be used.

Experiment Tunables Specification#

Field	`.spec.definition.env`
Description	Flag to specify env used for ChaosExperiment
Type	Mandatory
Range	user-defined (type: [name: string, value: string])
Default	n/a
Notes	The `.spec.definition.env` specifies the array of tunables passed to the experiment pods as environment variables. It is used to manage the experiment execution. We can set the default values for all the variables (tunable) here which can be overridden by ChaosEngine from `.spec.experiments[].spec.components.env` if required. To know about the variables that need to be overridden check the list of "mandatory" & "optional" env for an experiment as provided within the respective experiment documentation.

Configuration Specification#

Field	`.spec.definition.securityContext.containerSecurityContext.privileged`
Description	Flag to specify the security context for the ChaosExperiment pod
Type	Optional
Range	true, false (type:bool)
Default	n/a
Notes	The `.spec.definition.securityContext.containerSecurityContext.privileged` specify the securityContext params to the experiment container.

Field	`.spec.definition.labels`
Description	Flag to specify the label for the ChaosPod
Type	Optional
Range	user-defined (type:map[string]string)
Default	n/a
Notes	The `.spec.definition.labels` allow developers to specify the ChaosPod label for an experiment.

Field	`.spec.definition.securityContext.podSecurityContext`
Description	Flag to specify security context for ChaosPod
Type	Optional
Range	user-defined (type:corev1.PodSecurityContext)
Default	n/a
Notes	The `.spec.definition.securityContext.podSecurityContext` allows the developers to specify the security context for the ChaosPod which applies to all containers inside the Pod.

Field	`.spec.definition.configMaps`
Description	Flag to specify the configmap for ChaosPod
Type	Optional
Range	user-defined
Default	n/a
Notes	The `.spec.definition.configMaps` allows the developers to mount the ConfigMap volume into the experiment pod.

Field	`.spec.definition.secrets`
Description	Flag to specify the secrets for ChaosPod
Type	Optional
Range	user-defined
Default	n/a
Notes	The `.spec.definition.secrets` specify the secret data to be passed for the ChaosPod. The secrets typically contains confidential information like credentials.

Field	`.spec.definition.experimentAnnotations`
Description	Flag to specify the custom annotation to the ChaosPod
Type	Optional
Range	user-defined (type:map[string]string)
Default	n/a
Notes	The `.spec.definition.experimentAnnotations` allows the developer to specify the Custom annotation for the chaos pod.

Field	`.spec.definition.hostFileVolumes`
Description	Flag to specify the host file volumes to the ChaosPod
Type	Optional
Range	user-defined (type:map[string]string)
Default	n/a
Notes	The `.spec.definition.hostFileVolumes` allows the developer to specify the host file volumes to the ChaosPod.

Field	`.spec.definition.hostPID`
Description	Flag to specify the host PID for the ChaosPod
Type	Optional
Range	true, false (type:bool)
Default	n/a
Notes	The `.spec.definition.hostPID` allows the developer to specify the host PID for the ChaosPod.