The ChaosEngine is the main user-facing chaos custom resource with a namespace scope and is designed to hold information
around how the chaos experiments are executed. It connects an application instance with one or more chaos experiments,
while allowing the users to specify run level details (override experiment defaults, provide new environment variables and
volumes, options to delete or retain experiment pods, etc.,). This CR is also updated/patched with status of the chaos
experiments, making it the single source of truth with respect to the chaos.
This section describes the fields in the ChaosEngine spec and the possible values that can be set against the same.
State Specification
Field
.spec.engineState
Description
Flag to control the state of the chaosengine
Type
Mandatory
Range
active, stop
Default
active
Notes
The engineState in the spec is a user defined flag to trigger chaos. Setting it to active ensures successful execution of chaos. Patching it with stop aborts ongoing experiments. It has a corresponding flag in the chaosengine status field, called engineStatus which is updated by the controller based on actual state of the ChaosEngine.
Application Specification
Field
.spec.appinfo.appns
Description
Flag to specify namespace of application under test
Type
Mandatory
Range
user-defined (type: string)
Default
n/a
Notes
The appns in the spec specifies the namespace of the AUT. Usually provided as a quoted string.
Field
.spec.appinfo.applabel
Description
Flag to specify unique label of application under test
The applabel in the spec specifies a unique label of the AUT. Usually provided as a quoted string of pattern key=value. Note that if multiple applications share the same label within a given namespace, the AUT is filtered based on the presence of the chaos annotation litmuschaos.io/chaos: "true". If, however, the annotationCheck is disabled, then a random application (pod) sharing the specified label is selected for chaos.
Field
.spec.appinfo.appkind
Description
Flag to specify resource kind of application under test
Type
Mandatory
Range
deployment, statefulset, daemonset
Default
n/a (depends on app type)
Notes
The appkind in the spec specifies the Kubernetes resource type of the app deployment. The Litmus chaos operator supports chaos on deployments, statefulsets and daemonsets. Application health check routines are dependent on the resource types, in case of some experiments.
Field
.spec.auxiliaryAppInfo
Description
Flag to specify one or more app namespace-label pairs whose health is also monitored as part of the chaos experiment, in addition to a primary application specified in the .spec.appInfo.
The auxiliaryAppInfo in the spec specifies a (comma-separated) list of namespace-label pairs for downstream (dependent) apps of the primary app specified in .spec.appInfo in case of pod-level chaos experiments. In case of infra-level chaos experiments, this flag specifies those apps that may be directly impacted by chaos and upon which health checks are necessary.
Note: Irrespective of the nature of the chaos experiment, i.e., pod-level (single-app impact/lesser blast radius) or infra-level(multi-app impact/higher blast radius), the .spec.appinfo is a must-fill where the experiment is pointed to at least one primary app whose health is measured as an indicator of the resiliency / success of the chaos experiment.
RBAC Specification
Field
.spec.chaosServiceAccount
Description
Flag to specify serviceaccount used for chaos experiment
Type
Mandatory
Range
user-defined (type: string)
Default
n/a
Notes
The chaosServiceAccount in the spec specifies the name of the serviceaccount mapped to a role/clusterRole with enough permissions to execute the desired chaos experiment. The minimum permissions needed for any given experiment is provided in the .spec.definition.permissions field of the respective chaosexperiment CR.
Runtime Specification
Field
.spec.annotationCheck
Description
Flag to control annotation checks on applications as prerequisites for chaos
Type
Optional
Range
true, false
Default
true
Notes
The annotationCheck in the spec controls whether or not the operator checks for the annotation "litmuschaos.io/chaos" to be set against the application under test (AUT). Setting it to true ensures the check is performed, with chaos being skipped if the app is not annotated, while setting it to false suppresses this check and proceeds with chaos injection.
Field
.spec.monitoring
Description
Flag to enable collection of simple chaos metrics
Type
Optional
Range
true, false
Default
false
Notes
monitoring in the spec enables or disables collection of chaos metrics with an exporter pod. Metrics include count of experiments in a chaosengine & individual experiment status. It is recommended to keep this disabled.
Field
.spec.jobCleanupPolicy
Description
Flag to control cleanup of chaos experiment job post execution of chaos
Type
Optional
Range
delete, retain
Default
delete
Notes
jobCleanupPolicy controls whether or not the experiment pods are removed once execution completes. Set to retain for debug purposes (in the absence of standard logging mechanisms).
Component Specification
Field
.spec.components.runner.image
Description
Flag to specify image of chaos runner pod
Type
Optional
Range
user-defined (type: string)
Default
n/a (refer Notes)
Notes
The .components.runner.image allows developers to specify their own debug runner images. Defaults for the runner image can be enforced via the operator env CHAOS_RUNNER_IMAGE
Field
.spec.components.runner.imagePullPolicy
Description
Flag to specify image pull policy for the chaos runner
Type
Optional
Range
Always, IfNotPresent
Default
IfNotPresent
Notes
The .components.runner.imagePullPolicy allows developers to specify the pull policy for chaos-runner. Set to Always during debug/test.
Experiment Specification
Field
.spec.experiments[].name
Description
Name of the chaos experiment CR
Type
Mandatory
Range
user-defined (type: string)
Default
n/a
Notes
The experiment[].name specifies the chaos experiment to be executed by the chaos operator.
Field
.spec.experiments[].spec.components.env
Description
Environment variables passed to the chaos experiment
The experiment[].spec.components.env specifies the array of tunables passed to the experiment pods. Though the field is optional from a chaosengine definition viewpoint, it is almost always necessary to provide experiment tunables via this definition. While some of the env variables override the defaults in the experiment CR and some of the env are mandatory additions filling in for placeholders/empty values in the experimet CR. For a list of "mandatory" & "optional" env for an experiment, refer to the respective experiment documentation.
The experiment[].spec.components.configMaps provides for a means to insert config information into the experiment. The configmaps definition is validated for correctness and those specified are checked for availability (in the cluster/namespace) before being mounted into the experiment pods.
The experiment[].spec.components.secrets provides for a means to push secrets (typically project ids, access credentials etc.,) into the experiment pods. These are especially useful in case of platform-level/infra-level chaos experiments. The secrets definition is validated for correctness and those specified are checked for availability (in the cluster/namespace) before being mounted into the experiment pods.