ChaosBlade-Box: A Chaos Engineering Platform with Rich Scenarios

English | 中文

Note: For more information about the resilience testing platform, see the main2 branch.

Introduction

ChaosBlade-Box is a comprehensive chaos engineering platform with rich fault injection scenarios. Currently supported scenarios include:

• chaosblade-exec-os: Implementation of basic resource experimental scenarios.
• chaosblade-exec-docker: Docker container experimental scenario implementation, standardized by calling the Docker API.
• chaosblade-operator: Kubernetes platform experimental scenario is implemented, chaos experiments are defined by Kubernetes standard CRD method, it is very convenient to use Kubernetes resource operation method To create, update, and delete experimental scenarios, including using kubectl, client-go, etc., and also using the chaosblade cli tool described above.
• chaosblade-exec-jvm: Java application experimental scenario implementation, using Java Agent technology to mount dynamically, without any access, zero-cost use. It also supports uninstallation and completely recycles various resources created by the Agent.
• chaosblade-exec-cplus: C++ application experimental scenario implementation, using GDB technology to implement method and code line level experimental scenario injection.
• litmus-chaos: A toolset to do cloud-native chaos engineering

Quick Start

📖 Deployment Documentation

We provide comprehensive deployment guides for both host and Kubernetes environments:

• English Deployment Guide - Detailed step-by-step deployment instructions
• 中文部署文档 - 详细的分步部署指南

The deployment documentation includes:

• ✅ System requirements and prerequisites
• ✅ Host environment deployment (Docker, direct deployment)
• ✅ Kubernetes environment deployment (Helm Chart)
• ✅ Configuration reference and best practices
• ✅ Troubleshooting guide
• ✅ Upgrade and uninstallation instructions

Compile

Go to the project root directory which you cloned and execute compile:

Build Project

# Build the entire project (including frontend and Java backend)
make build

Build Docker Image

# Build Docker image (optional parameters: IMAGE_NAME, IMAGE_REGISTRY, VERSION)
make docker-build

# Example: specify image registry
make docker-build IMAGE_REGISTRY=registry.example.com/

Build Helm Package

# Package Helm chart
make helm-package

Clean Build Artifacts

# Clean build artifacts
make clean

View All Available Commands

# Show help information, view all available commands
make help

Deployment Options

Option 1: Host Environment Deployment

Quick Start

1. Get Package: Download the latest jar package from RELEASES

2. Prepare MySQL: You can use a local database or cloud database. For dev/test environments, you can deploy MySQL using Docker

3. Configure Environment Variables (Recommended):

export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/chaosblade?characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai"
export SPRING_DATASOURCE_USERNAME="root"
export SPRING_DATASOURCE_PASSWORD="YourPassword123"

4. Start Application:

java -jar chaosblade-box-1.1.0.jar \
  --spring.datasource.url="${SPRING_DATASOURCE_URL}" \
  --spring.datasource.username="${SPRING_DATASOURCE_USERNAME}" \
  --spring.datasource.password="${SPRING_DATASOURCE_PASSWORD}"

Tip: For detailed deployment steps, please refer to the Deployment Guide

Option 2: Kubernetes Environment Deployment

Quick Start

1. Get Helm Chart Package: Download the latest helm package from RELEASES

2. Create Secret (Recommended):

kubectl create secret generic chaosblade-secret \
  --from-literal=mysql-password="YourPassword" \
  -n chaosblade

3. Deploy Application:

helm install chaosblade-box chaosblade-box-1.1.0.tgz \
  --set spring.datasource.password=$(kubectl get secret chaosblade-secret -n chaosblade -o jsonpath='{.data.mysql-password}' | base64 -d) \
  --namespace chaosblade

Tip: For detailed deployment steps, please refer to the Deployment Guide

Configuration Parameters

Parameter	Description	Default Value	Required
spring.datasource.url	MySQL connection URL. Not required if using Helm	-	Helm: No Host: Yes
spring.datasource.username	MySQL username. Not required if using Helm	root	Helm: No Host: Yes
spring.datasource.password	MySQL password	-	Yes
spring.data.redis.host	Redis host address	localhost	No
spring.data.redis.port	Redis port	6379	No
spring.data.redis.password	Redis password	-	No
chaos.cache.enable	Enable cache	false	No
chaos.function.sync.type	Init chaos data type. Use ALL for first start	ALL	No
chaos.agent.version	chaosblade-box-agent version	1.1.0	No
chaos.agent.repository	chaosblade-box-agent image repository	ghcr.io/chaosblade-io/chaosblade-box-agent	No
chaos.agent.url	chaosblade-box-agent binary package URL	[OSS Link]	No
chaos.agent.helm	chaosblade-box-agent helm package URL	[OSS Link]	No
chaos.server.domain	ChaosBlade Box access address (for Agent connection)	-	Required for host deployment

Available chaos.function.sync.type Values

• ALL: Initialize all chaos experiment data (recommended for first deployment)
• ChaosBlade: Initialize only ChaosBlade related data
• UserApp: Initialize only user application data
• None: No data initialization (recommended for production subsequent startups)
• LITMUS_CHAOS: Initialize only Litmus Chaos data

Common Issues

1. Database Connection Failed

# Check MySQL service status
docker ps | grep mysql

# Test connection
mysql -h DATASOURCE_HOST -u DATASOURCE_USERNAME -p

2. Redis Connection Failed

# Check Redis service status
docker ps | grep redis

# Test connection
redis-cli -h REDIS_HOST -p 6379 ping

3. Kubernetes Pod Cannot Start

# View Pod logs
kubectl logs <pod-name> -n chaosblade

# Describe Pod
kubectl describe pod <pod-name> -n chaosblade

# Check events
kubectl get events -n chaosblade

4. More Issues

Please refer to the detailed Deployment Documentation for complete troubleshooting guide.

Architecture

Component Architecture

┌─────────────────────────────────────────────────────┐
│                  ChaosBlade Box                      │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │   Web UI     │  │   API Server │  │  Scheduler│ │
│  └──────────────┘  └──────────────┘  └───────────┘ │
└──────────────┬──────────────────────────────────────┘
               │
        ┌──────┴──────┐
        │             │
   ┌────▼────┐   ┌────▼────┐
   │  MySQL  │   │  Redis  │
   └─────────┘   └─────────┘
               │
        ┌──────┴──────────────────┐
        │                         │
   ┌────▼─────┐            ┌──────▼──────┐
   │  Agent   │            │   Agent     │
   │ (Host)   │            │ (K8s)       │
   └──────────┘            └─────────────┘

Supported Experiment Scenarios

• Basic Resources: CPU, memory, disk, network, etc.
• Container Scenarios: Docker container fault injection
• Kubernetes: Pod, Node, Service fault injection
• Application Layer: Java, C++ application-level fault injection
• Cloud Native: Cloud-native scenarios integrated with Litmus Chaos

Features

• ✅ Rich fault injection scenarios
• ✅ User-friendly Web UI
• ✅ Support for host and Kubernetes environments
• ✅ Experiment orchestration and automation
• ✅ Real-time monitoring and reporting
• ✅ Secure permission management
• ✅ Extensible plugin architecture
• ✅ Prometheus integration
• ✅ Multi-tenancy support

Upgrade Guide

Host Environment Upgrade

# 1. Backup database
mysqldump -u root -p chaosblade > backup.sql

# 2. Stop old version
kill $(cat chaosblade-box.pid)

# 3. Start new version
java -jar chaosblade-box-1.1.0.jar ...

Kubernetes Environment Upgrade

# Upgrade using Helm
helm upgrade chaosblade-box chaosblade-box-1.1.0.tgz \
  -f custom-values.yaml \
  --namespace chaosblade

Uninstallation

Host Environment

# Stop application
kill $(cat chaosblade-box.pid)

# Clean up data (optional)
docker stop mysql-8.0 redis
docker rm mysql-8.0 redis

Kubernetes Environment

# Uninstall Helm Release
helm uninstall chaosblade-box -n chaosblade

# Delete namespace
kubectl delete namespace chaosblade

Bugs and Feedback

For bug reports, questions, and discussions, please submit GitHub Issues.

You can also contact us via:

• DingTalk Group (recommended for Chinese users): 23177705
• Slack: chaosblade-io
• Gitter: chaosblade community
• Email: chaosblade.io.01@gmail.com
• Twitter: chaosblade.io

Contributing

We welcome every contribution, even if it is just punctuation. See details in CONTRIBUTING

Enterprise Registration

The original intention of our open source project is to lower the threshold for implementing chaos engineering in enterprises, so we highly value the use of the project in enterprises. Welcome to register here. After registration, you will be invited to join the enterprise mailing group to discuss challenges encountered during chaos engineering implementation and share experiences.

License

ChaosBlade-Box is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Related Projects

• ChaosBlade - Chaos engineering experiment execution tool
• ChaosBlade Operator - Kubernetes chaos engineering operator
• Litmus - Cloud-native chaos engineering framework

---

Star our project to get the latest updates! ⭐