Getting Started

Ready to dive into your first Kubernetes challenge with Kubeasy? This guide will walk you through the full setup -- from prerequisites to your first submission.

Prerequisites

Make sure you have the following installed on your machine:

• Docker (used to run the local Kubernetes cluster) or other container runtime compatible with Kind
• kubectl (used to inspect and interact with your cluster)

Step-by-step Setup

1. Install the Kubeasy CLI

Choose the installation method that works best for you.

Install script (macOS / Linux):

The fastest way to install. Automatically detects your OS and architecture:

curl -fsSL https://download.kubeasy.dev/install.sh | sh

Homebrew (macOS / Linux):

brew install kubeasy-dev/tap/kubeasy

NPM:

npm install -g @kubeasy-dev/kubeasy-cli

Scoop (Windows):

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

Manual download:

Download the binary for your platform from GitHub Releases and add it to your PATH.

Verify the installation:

kubeasy version

2. Generate your API Key

Go to your Kubeasy profile and generate a personal API key. This key allows the CLI to fetch available challenges and submit your results.

3. Login to Kubeasy

kubeasy login

Enter your API key when prompted. The key is stored securely in your system keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service). On headless environments, it falls back to ~/.config/kubeasy-cli/credentials.

You can also set the KUBEASY_API_KEY environment variable for CI/CD use.

4. Set up the local environment

kubeasy setup

This will:

• Create a Kind Kubernetes cluster named kubeasy (if it doesn't exist yet)
• Install required infrastructure components (Kyverno, local-path-provisioner)

You only need to run this once on a machine.

5. Pick a challenge

Visit the challenge list and choose one that interests you. Each challenge comes with a short description, difficulty, and estimated time.

You can also view challenge details from the CLI:

kubeasy challenge get <challenge-slug>

6. Start the challenge

kubeasy challenge start <challenge-slug>

This command will:

• Create a dedicated namespace for the challenge
• Pull and deploy the challenge manifests (broken scenario)
• Apply Kyverno policies to prevent bypasses
• Switch your kubectl context to the challenge namespace

7. Play and fix the challenge

Use kubectl, logs, and events to investigate what's wrong.

You can edit objects, apply new resources, and debug freely -- just like in a real cluster.

8. Submit your solution

kubeasy challenge submit <challenge-slug>

The CLI will:

• Load validation objectives from the challenge definition
• Execute each validation against the cluster
• Send structured results to the platform

9. Review your submission

Go to the web platform to see:

• Which objectives passed or failed
• Helpful messages for failed checks
• Whether the challenge is considered complete

10. (optional) Clean up

kubeasy challenge clean <challenge-slug>

This removes all resources created for the challenge, including the namespace.

If you want to start over (including resetting your progress on the platform):

kubeasy challenge reset <challenge-slug>

That's it! You're ready to start learning Kubernetes by solving real problems.