Developer Guide

Learn how to create, test, and contribute new challenges to the Kubeasy platform.

Welcome to the Kubeasy Developer Guide.

This guide covers everything you need to create and contribute Kubernetes challenges — from understanding the challenge format to testing locally and submitting a pull request.

What is a challenge?

A Kubeasy challenge is a self-contained Kubernetes scenario with a defined initial state and measurable success criteria. It can be broken (a fix challenge), empty (a build challenge), or suboptimal (a migrate challenge). See Challenge Types for details.

Each challenge consists of:

challenge.yaml — metadata, description, and validation objectives
manifests/ — the initial Kubernetes state deployed to the cluster
policies/ — Kyverno policies that prevent bypasses
image/ (optional) — a custom Docker image for the challenge application

Prerequisites

Basic Kubernetes knowledge (pods, deployments, services, RBAC)
Experience writing Kubernetes YAML manifests
The Kubeasy CLI installed (kubeasy setup to create the local cluster)
Git and a GitHub account (for contributing to the official repository)

The development workflow

# 1. Scaffold a new challenge
kubeasy dev create

# 2. Write your manifests, policies, and objectives

# 3. Lint the challenge.yaml (no cluster needed)
kubeasy dev lint

# 4. Deploy and test locally
kubeasy dev test --clean

# 5. Iterate with watch mode
kubeasy dev apply --watch    # terminal 1
kubeasy dev validate --watch # terminal 2

# 6. Clean up
kubeasy dev clean

Guide structure

Page	What it covers
Challenge Structure	Complete anatomy of a challenge — all files and fields
Creating Your First Challenge	Step-by-step tutorial
Validation Overview	Philosophy, objective structure, anti-patterns
Condition	Check resource conditions
Status	Check status fields with operators
Log	Check container logs
Event	Check Kubernetes events
Connectivity	Test HTTP connectivity
RBAC	Test ServiceAccount permissions
Spec	Check resource manifest fields
Triggered	Run an action then validate
Testing Challenges	Testing locally before submission
Contributing	PR guidelines and quality standards

Repositories

Repository	Purpose
kubeasy-dev/challenges	Challenge definitions and manifests
kubeasy-dev/kubeasy-cli	CLI tool (validation engine, dev commands)
kubeasy-dev/monorepo	Web platform, API, and documentation

Get help

Questions: GitHub Discussions
Bug reports: GitHub Issues