Developers Guide on Krkn

Krkn-lib

Thu, 05 Jan 2017 00:00:00 +0000

krkn-lib

Krkn Chaos and resiliency testing tool Foundation Library

The Library contains Classes, Models and helper functions used in Kraken to interact with Kubernetes, Openshift and other external APIS. The goal of this library is to give to developers the building blocks to realize new Chaos Scenarios and to increase the testability and the modularity of the Krkn codebase.

Adding scenarios via plugin api

Mon, 01 Jan 0001 00:00:00 +0000

Scenario Plugin API:

This API enables seamless integration of Scenario Plugins for Krkn. Plugins are automatically detected and loaded by the plugin loader, provided they extend the AbstractPluginScenario abstract class, implement the required methods, and adhere to the specified naming conventions.

Plugin folder:

The plugin loader automatically loads plugins found in the krkn/scenario_plugins directory, relative to the Krkn root folder. Each plugin must reside in its own directory and can consist of one or more Python files. The entry point for each plugin is a Python class that extends the AbstractPluginScenario abstract class and implements its required methods.

Adding New Scenario to Krkn-hub

Mon, 01 Jan 0001 00:00:00 +0000

Adding/Editing a New Scenario to Krkn-hub

Create folder with scenario name under krkn-hub
Create generic scenario template with environment variables

a. See scenario.yaml for example

b. Almost all parameters should be set using a variable (these will be set in the env.sh file or through the command line environment variables)
Add defaults for any environment variables in an “env.sh” file

a. See env.sh for example
Create script to run.sh chaos scenario a. See run.sh for example

Adding New Scenario to Krknctl

Mon, 01 Jan 0001 00:00:00 +0000

Adding a New Scenario to Krknctl

For krknctl to find the parameters of the scenario it uses a krknctl input json file. Once this file is added to krkn-hub, krknctl will be able to find it along with the details of how to run the scenario.

Add KrknCtl Input Json

This file adds every environment variable that is set up for krkn-hub to be defined as a flag to the krknctl cli command. There are a number of different type of variables that you can use, each with their own required fields. See below for an example of the different variable types

Adding to Krkn Test Suite

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers how to add both unit tests and functional tests to the krkn project. Tests are essential for ensuring code quality and preventing regressions.

Unit Tests

Unit tests in krkn are located in the tests/ directory and use Python’s unittest framework with comprehensive mocking to avoid requiring external dependencies like cloud providers or Kubernetes clusters.

Creating a Unit Test

1. File Location and Naming

Place your test file in the tests/ directory with the naming pattern test_<feature>.py:

Testing your changes

Mon, 01 Jan 0001 00:00:00 +0000

This page gives details about how you can get a kind cluster configured to be able to run on krkn-lib (the lowest level of krkn-chaos repos) up through krknctl (our easiest way to run and highest level repo)

Configure Kind Testing Environment

Install kind
Create cluster using kind-config.yml under krkn-lib base folder

Health Check Plugins

Mon, 01 Jan 2024 00:00:00 +0000

Health Check Plugins

Health check plugins allow Krkn to continuously monitor the health of your services and infrastructure during chaos experiments. They run in background threads alongside the chaos scenario, detecting outages, tracking downtime duration, and collecting telemetry data.

Overview

The health check system uses a plugin architecture:

HealthCheckFactory — automatically discovers and loads all plugins from the krkn.health_checks package
AbstractHealthCheckPlugin — base class all plugins must extend
Plugins run in separate threads and write telemetry to a shared queue
The factory tracks all active plugin instances and provides lifecycle management (increment_all_iterations, stop_all)

Exit Codes

Code	Meaning
`0`	Success — all health checks passed
`2`	Critical alert detected during the run
`3`	Health check failure (e.g. `exit_on_failure: true` triggered)

Built-in Plugins

HTTP Health Check (`health_checks`)

Monitors HTTP endpoints by making periodic GET requests. Tracks status changes, measures downtime duration, and records telemetry for each state transition.

Developers Guide on Krkn

Krkn-lib

krkn-lib

Krkn Chaos and resiliency testing tool Foundation Library

Contents

Adding scenarios via plugin api

Scenario Plugin API:

Plugin folder:

Adding New Scenario to Krkn-hub

Adding/Editing a New Scenario to Krkn-hub

Adding New Scenario to Krknctl

Adding a New Scenario to Krknctl

Add KrknCtl Input Json

Adding to Krkn Test Suite

Unit Tests

Creating a Unit Test

1. File Location and Naming

Testing your changes

Configure Kind Testing Environment

Health Check Plugins

Health Check Plugins

Overview

Exit Codes

Built-in Plugins

HTTP Health Check (health_checks)

HTTP Health Check (`health_checks`)