Getting Started

This guide walks you through everything you need to start using Kubeasy — from installing the CLI to completing your first challenge.

Prerequisites

• Docker (or a compatible container runtime) — required by Kind to run the local Kubernetes cluster
• kubectl — the Kubernetes CLI (install guide)

Install the CLI

Choose the installation method that works best for your system.

Install script (Linux, macOS)

curl -fsSL https://raw.githubusercontent.com/kubeasy-dev/kubeasy-cli/main/install.sh | bash

Homebrew (macOS, Linux)

brew install kubeasy-dev/tap/kubeasy

NPM (cross-platform)

npm install -g kubeasy

Scoop (Windows)

scoop bucket add kubeasy https://github.com/kubeasy-dev/scoop-bucket
scoop install kubeasy

Manual download

Download the latest binary for your platform from the GitHub Releases page, make it executable, and add it to a directory in your PATH.

# Example for Linux amd64
chmod +x kubeasy-linux-amd64
sudo mv kubeasy-linux-amd64 /usr/local/bin/kubeasy

Verify installation

kubeasy version

Generate an API key

1. Go to kubeasy.dev and sign in or create an account
2. Navigate to your Profile page
3. Generate a new API key and copy it

Authenticate

kubeasy login

You'll be prompted to enter your API key. It is stored securely:

• macOS: System Keychain
• Windows: Windows Credential Manager
• Linux: Secret Service (falls back to ~/.config/kubeasy-cli/credentials)

For CI/CD environments, set KUBEASY_API_KEY as an environment variable instead.

Set up the local environment

kubeasy setup

This creates a local Kubernetes cluster using Kind and installs all the infrastructure components that challenges depend on. Run it once per machine.

What gets installed:

Setup typically takes 1–3 minutes depending on your connection speed.

$ kubeasy setup

Creating Kind cluster 'kubeasy' (Kubernetes v1.35.0)   [18s]
Installing infrastructure components                    [52s]

Environment ready! Start a challenge with:
  kubeasy challenge start <slug>

Browse available challenges

Visit kubeasy.dev/challenges to browse all available challenges. Each listing shows the difficulty, estimated time, and theme.

You can also preview a challenge's details before starting:

kubeasy challenge get pod-evicted

Start your first challenge

kubeasy challenge start pod-evicted

This command:

1. Creates a dedicated namespace (pod-evicted) in the cluster
2. Pulls the challenge OCI artifact and deploys all resources
3. Waits for the initial setup to complete
4. Switches your kubectl context to the challenge namespace

$ kubeasy challenge start pod-evicted

Challenge: Pod Evicted
Creating namespace
Deploying challenge
Kubectl context configured

Challenge environment is ready!
Namespace: pod-evicted

Your kubectl is now pointing at the challenge namespace. Start investigating:

kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl get events --sort-by='.lastTimestamp'

Solve the challenge

There's no walkthrough. Read the challenge description, explore the cluster state, and figure out what's wrong. Use any tools you're comfortable with — kubectl, Lens, k9s.

The description tells you what's broken (symptoms). The objective tells you what a successful outcome looks like. The root cause is yours to discover.

Submit your solution

kubeasy challenge submit pod-evicted

The CLI runs all validation objectives against the cluster:

$ kubeasy challenge submit pod-evicted

Condition Validation
  pod-running: PASSED - All condition checks passed

Event Validation
  no-crash-events: PASSED - No forbidden events found

All validations passed!
Congratulations! Challenge 'pod-evicted' completed! +50 XP

If some objectives fail, the output tells you exactly which ones and why. Fix the remaining issues and submit again.

Clean up

# Remove resources AND reset your progress on the platform
kubeasy challenge reset pod-evicted

# Remove local resources only (keeps your progress)
kubeasy challenge clean pod-evicted

Next steps

• How It Works — understand the technical architecture
• Challenge Types — learn the difference between fix, build, and migrate
• CLI Reference — full reference for all commands
• Troubleshooting — solutions to common issues