This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation

Details on how to install krkn and krkn-hub

1: Krkn
2: Krkn-lib
3: krkn-hub
4: krknctl

The following ways are supported to run Krkn:

Krkn CLI (recommended) - krknctl
Standalone python program through Git - See specific documentation for krkn
Containerized version using either Podman or Docker as the runtime via Krkn-hub
Kubernetes or OpenShift deployment ( unsupported )

Note

It is recommended to run Kraken external to the cluster ( Standalone or Containerized ) hitting the Kubernetes/OpenShift API as running it internal to the cluster might be disruptive to itself and also might not report back the results if the chaos leads to cluster’s API server instability.

Note

To run Kraken on Power (ppc64le) architecture, build and run a containerized version by following the instructions given here.

Note

Helper functions for interactions in Krkn are part of krkn-lib. Please feel free to reuse and expand them as you see fit when adding a new scenario or expanding the capabilities of the current supported scenarios.

1 - Krkn

Krkn aka Kraken

Installation

Clone the Repository

To clone and use the latest krkn version follow the directions below. If you’re wanting to contribute back to krkn in anyway in the future we recommend forking the repository first before cloning.

See the latest release version here

$ git clone https://github.com/krkn-chaos/krkn.git --branch <release version>
$ cd krkn

Fork and Clone the Repository

Fork the repository

$ git clone https://github.com/<github_user_id>/krkn.git
$ cd krkn

Set your cloned local to track the upstream repository:

cd krkn
git remote add upstream https://github.com/krkn-chaos/krkn

Disable pushing to upstream master:

git remote set-url --push upstream no_push
git remote -v

Install the dependencies

To be sure that krkn’s dependencies don’t interfere with other python dependencies you may have locally, we recommend creating a virtual enviornment before installing the dependencies. We have only tested up to python 3.9

$ python3.9 -m venv chaos
$ source chaos/bin/activate

$ pip install -r requirements.txt

Note

Make sure python3-devel and latest pip versions are installed on the system. The dependencies install has been tested with pip >= 21.1.3 versions.

Where can your user find your project code? How can they install it (binaries, installable package, build from source)? Are there multiple options/versions they can install and how should they choose the right one for them?

Getting Started with Krkn

If you are wanting to try to edit your configuration files and scenarios see getting started doc

Running Krkn

$ python run_kraken.py --config <config_file_location>

Run containerized version

Krkn-hub is a wrapper that allows running Krkn chaos scenarios via podman or docker runtime with scenario parameters/configuration defined as environment variables.

2 - Krkn-lib

Krkn-lib contains the base kubernetes python functions

Installation

Git

Clone the repository

git clone https://github.com/krkn-chaos/krkn-lib
cd krkn-lib

Install the dependencies

Krkn lib uses poetry for its dependency management and packaging. To install the proper packages please use:

$ pip install poetry
$ poetry install --no-interaction

Available Functions

You can find a list of available functions and modules here

Testing your changes

To see how you can configure and test your changes see testing changes

3 - krkn-hub

Krkn-hub aka kraken-hub

Hosts container images and wrapper for running scenarios supported by Krkn, a chaos testing tool for Kubernetes clusters to ensure it is resilient to failures. All we need to do is run the containers with the respective environment variables defined as supported by the scenarios without having to maintain and tweak files!

Set Up

You can use docker or podman to run kraken-hub

Install Podman your certain operating system based on these instructions

Install Docker on your system.

Docker is also supported but all variables you want to set (separate from the defaults) need to be set at the command line In the form -e <VARIABLE>=<value>

You can take advantage of the get_docker_params.sh script to create your parameters string This will take all environment variables and put them in the form “-e =” to make a long string that can get passed to the command

For example: docker run $(./get_docker_params.sh) --net=host -v <path-to-kube-config>:/home/krkn/.kube/config:Z -d quay.io/redhat-chaos/krkn-hub:power-outages

Tip

Because the container runs with a non-root user, ensure the kube config is globally readable before mounting it in the container. You can achieve this with the following commands:

kubectl config view –flatten > ~/kubeconfig && chmod 444 ~/kubeconfig && docker run $(./get_docker_params.sh) –name=<container_name> –net=host -v ~kubeconfig:/home/krkn/.kube/config:Z -d containers.krkn-chaos.dev/krkn-chaos/krkn-hub:<scenario>

4 - krknctl

how to install, build and configure the CLI

Binary distribution (Recommended):

The krknctl binary is available for download from GitHub releases for supported operating systems and architectures. Extract the tarball and add the binary to your $PATH.

Build from sources :

Linux:

Dictionaries:

To generate the random words we use the american dictionary, it is often available but if that’s not the case:

Fedora/RHEL: sudo dnf install words
Ubuntu/Debian: sudo apt-get install wamerican

Building from sources:

Linux:

To build the only system package required is libbtrfs:

Fedora/RHEL: sudo dnf install btrfs-progs-devel
Ubuntu/Debian: sudo apt-get install libbtrfs-dev

MacOS:

gpgme: brew install gpgme

Build command:

go build -tags containers_image_openpgp -ldflags="-w -s" -o bin/ ./...

Note

To build for different operating systems/architectures refer to GOOS GOARCH golang variables

Configure Autocompletion:

The first step to have the best experience with the tool is to install the autocompletion in the shell so that the tool will be able to suggest to the user the available command and the description simply hitting tab twice.

Bash (linux):

source <(./krknctl completion bash)

Tip

To install autocompletion permanently add this command to .bashrc (setting the krknctl binary path correctly)

zsh (MacOS):

autoload -Uz compinit
compinit
source <(./krknctl completion zsh)

Tip

To install autocompletion permanently add this command to .zshrc (setting the krknctl binary path correctly)

Container Runtime:

The tool supports both Podman and Docker to run the krkn-hub scenario containers. The tool interacts with the container runtime through Unix socket. If both container runtimes are installed in the system the tool will default on Podman.

Podman:

Steps required to enable the Podman support

Linux:

enable and activate the podman API daemon

sudo systemctl enable --now podman

activate the user socket

systemctl enable --user --now podman.socket

MacOS:

If both Podman and Docker are installed be sure that the docker compatibility is disabled

Docker:

Linux:

Check that the user has been added to the docker group and can correctly connect to the Docker unix socket
running the comman podman ps if an error is returned run the command sudo usermod -aG docker $USER