Build System

Understanding the Chaos Mesh build infrastructure and make targets

Chaos Mesh uses a sophisticated build system based on Make and containerized build environments. This guide explains the build infrastructure and available make targets.

Build Architecture

The build system uses two specialized Docker images for different purposes:

Build Environment (build-env)

Minimal environment for compiling binaries:

make image-build-env    # Build the build-env image
make enter-buildenv     # Enter interactive shell in build-env

Use this for:

• Compiling Go binaries
• Building C components (pause, fakeclock)
• Creating production artifacts

Development Environment (dev-env)

Full development environment with all tools:

make image-dev-env     # Build the dev-env image
make enter-devenv      # Enter interactive shell in dev-env

Use this for:

• Code generation (CRDs, clients, deepcopy)
• Linting and formatting
• Running tests
• Building protobuf definitions
• Generating Swagger specs

Each branch has its own image tag for build-env and dev-env, automatically determined by hack/env-image-tag.sh.

Environment Variables

Build Configuration

# Image tag for built images (default: latest)
export IMAGE_TAG=v2.6.0

# Enable debug symbols (default: disabled)
export DEBUGGER=1

# Include UI in builds (default: disabled)
export UI=1

# Go proxy for dependency downloads
export GOPROXY=https://proxy.golang.org,direct

# Build cache directory
export GO_BUILD_CACHE=/path/to/.cache/chaos-mesh

# Target platform (amd64 or arm64)
export TARGET_PLATFORM=amd64

Core Build Targets

Building Everything

make all               # Build CRD manifests and all container images
make image             # Build all component images
make manifests/crd.yaml # Generate combined CRD manifest

Building Components

Container Images

# Build individual component images
make image-chaos-daemon
make image-chaos-mesh              # Controller manager
make image-chaos-dashboard
make image-chaos-dlv               # Debugger (when DEBUGGER=1)
make image-e2e-helper              # E2E test helper

Local Binaries

Build binaries without Docker for local development:

make local/chaos-daemon
make local/chaos-controller-manager
make local/chaos-dashboard

Local builds require all development dependencies installed on your host. Using containerized builds (make image) is recommended for consistency.

Building the UI

The dashboard UI requires pnpm and is optional:

# Set UI=1 to include UI in builds
UI=1 make ui

# Or build manually
cd ui
pnpm install --frozen-lockfile
pnpm build

The UI assets are embedded into the chaos-dashboard binary using hack/embed_ui_assets.sh.

Code Generation Targets

Chaos Mesh generates significant code from CRD definitions and protobuf schemas.

Complete Generation

make generate          # Run all generation steps

This includes:

• CRD manifests (make config)
• Deepcopy methods (make generate-deepcopy)
• Kubernetes clients (make generate-client)
• Chaos builder code (make chaos-build)
• Swagger specs (make swagger_spec)
• Combined CRD YAML (make manifests/crd.yaml)

Individual Generation Steps

CRD Manifests

make config            # Generate CRD manifests with controller-gen

Generates:

• config/crd/bases/*.yaml - Individual CRD files
• helm/chaos-mesh/crds/*.yaml - Copies for Helm chart

Deepcopy Methods

make generate-deepcopy # Generate DeepCopy methods for CRD types

Uses controller-gen to generate zz_generated.deepcopy.go files.

Kubernetes Clients

make generate-client   # Generate all client code

Or individually:

make generate-clientset  # Generate versioned clientset
make generate-lister     # Generate listers for CRDs
make generate-informer   # Generate informers for CRDs

Generated code goes to:

• pkg/client/versioned/ - Clientset
• pkg/client/listers/ - Listers
• pkg/client/informers/ - Informers

Chaos Builder

make chaos-build       # Generate chaos type implementations

Builds and runs bin/chaos-builder to generate boilerplate code for chaos types.

Protocol Buffers

make proto             # Generate .go files from .proto files

Generates gRPC code for:

• pkg/chaosdaemon/pb/ - Chaos daemon protocol
• pkg/chaoskernel/pb/ - Chaos kernel protocol

Swagger/OpenAPI

make swagger_spec      # Generate OpenAPI spec for dashboard API

Generates pkg/dashboard/swaggerdocs/ for frontend consumption.

Makefiles

make generate-makefile # Generate binary.generated.mk and container-image.generated.mk

These generated makefiles define targets for building all binaries and images.

Quality Checks

Complete Check Suite

make check             # Run all prerequisite checks for PR

This runs:

1. make generate - Regenerate all code
2. make vet - Run go vet
3. make lint - Run revive linter
4. make fmt - Format code with goimports
5. make tidy - Ensure go.mod is tidy
6. make install.sh - Regenerate install script
7. make helm-values-schema - Update Helm schema

Individual Quality Targets

Formatting

make fmt               # Format code with goimports

Runs goimports -w -l -local github.com/chaos-mesh/chaos-mesh on all Go files except generated code.

Linting

make lint              # Lint with revive

Uses configuration from revive.toml.

Vetting

make vet               # Run go vet

Runs static analysis to find potential bugs.

Tidy Dependencies

make tidy              # Run go mod tidy in all modules

This runs go mod tidy in multiple directories:

• Root directory
• api/
• e2e-test/
• e2e-test/cmd/e2e_helper/

All modules must remain tidy to pass CI.

Security Scanning

make gosec-scan        # Run security scanner

Uses gosec to find common security issues.

Testing Targets

Unit Tests

make test              # Run all unit tests with coverage

This:

1. Enables failpoint stubs
2. Runs tests with CGO_ENABLED=1
3. Generates coverage report (cover.out)
4. Disables failpoint stubs

Coverage Reports

make coverage          # Generate HTML coverage report

Creates:

• cover.json - JSON coverage data
• cover.xml - XML coverage data
• cover/index.html - HTML coverage report

E2E Tests

make e2e-build         # Build e2e test binaries
make e2e               # Run e2e tests in current cluster

With custom options:

GINKGO_FLAGS="-v -focus=PodChaos" make e2e
PAUSE_IMAGE=custom/pause:latest make e2e

Failpoint Control

Failpoints enable fault injection in tests:

make failpoint-enable  # Enable failpoint stubs
make failpoint-disable # Disable failpoint stubs

Always disable failpoints after testing. Don’t commit code with failpoints enabled.

Test Utilities

make test-utils        # Build test utility binaries

Builds:

• bin/test/timer - Time testing utility
• bin/test/multithread_tracee - Multi-thread tracing test
• pkg/time/fakeclock/*.o - Fake clock objects

Advanced Targets

Special Components

Pause Binary

make images/chaos-daemon/bin/pause

Builds the minimal pause binary from hack/pause.c.

Watchmaker

make watchmaker        # Build time injection tool

Builds the watchmaker binary for time chaos simulation.

Installation Scripts

make install.sh        # Generate install.sh script

Runs hack/update_install_script.sh to create the one-line installer.

Helm Values Schema

make helm-values-schema # Generate JSON schema for values.yaml

Creates helm/chaos-mesh/values.schema.json from helm/chaos-mesh/values.yaml.

Cleanup

make clean             # Remove all build artifacts
make clean-binary      # Remove built binaries
make clean-image-built # Remove image build markers

Build System Internals

Containerized Shell Execution

Many targets use SHELL:=$(RUN_IN_DEV_SHELL) or SHELL:=$(RUN_IN_BUILD_SHELL) to run commands inside Docker containers.

This is determined by:

$(ROOT)/build/get_env_shell.py dev-env
$(ROOT)/build/get_env_shell.py build-env

Generated Makefiles

The build system includes generated makefiles:

• binary.generated.mk - Binary build targets
• container-image.generated.mk - Container image targets
• local-binary.generated.mk - Local binary targets

Generate these with:

make generate-makefile

LDFLAGS

Build flags are set via:

export LDFLAGS="$(./hack/version.sh)"

This includes:

• Version information
• Git commit hash
• Build timestamp
• -s -w for stripping (unless DEBUGGER=1)

Common Build Workflows

Development Iteration

# Make code changes
vim pkg/controller/.../*.go

# Regenerate if needed
make generate

# Run checks
make check

# Run tests
make test

# Build locally for quick testing
make local/chaos-controller-manager

Full PR Preparation

# Complete quality check
make check

# Full test suite
make test

# Build all images
make image

# E2E tests
make e2e-build
make e2e

Release Build

# Set version
export IMAGE_TAG=v2.6.0

# Include UI
export UI=1

# Build everything
make all

# Build E2E helper
make e2e-image

Troubleshooting

Build Cache Issues

Clear the build cache:

rm -rf .cache/chaos-mesh

Environment Image Issues

Rebuild environment images:

IMAGE_BUILD_ENV_BUILD=1 make image-build-env
IMAGE_DEV_ENV_BUILD=1 make image-dev-env

Module Issues

Ensure all modules are tidy:

make tidy

Generated Code Out of Sync

Regenerate everything:

make generate
git diff  # Check what changed

Next Steps

• Review Developer Guide for development workflows
• Understand Controller Design Principles
• Check Contributing Guidelines for PR process