Building Challenges

In Layer5 Academy, a Challenge is a hands-on, scenario-based task. Where a Learning Path teaches a subject from the ground up and a Certification tests knowledge a learner already has, a Challenge gives them a concrete problem and asks them to solve it.

When to Use a Challenge 🔗

How to Create Your Challenge 🔗

Challenges are authored the same way as every other Academy content type: as Markdown in your organization’s Academy content repository, published through a Git-native workflow. If you have not set that repository up yet, start with Creating Content for the Academy, which covers the repository setup once for all three content types.

Find Your Organization UUID and Challenge ID 🔗

Each challenge is tied to a specific organization and identified by a UUID, which is how the Academy scopes your content to your organization and tracks learner progress against it.

You need two:

• Challenge ID - a unique identifier for this challenge, set as the id in the front matter of its _index.md.
• Organization ID - your organization’s UUID, used in the directory path.

The Create New Content tool in the Instructor Console generates both for you, along with a ready-to-paste front matter block. Choose Challenge as the Content Type. See Using the Content Creation Tool.

1. Set Up the Directory Structure 🔗

All challenges live under content/challenges/<your-organization-uuid>, each in its own folder named with a descriptive, URL-friendly slug. The final URL follows this pattern:

https://cloud.layer5.io/academy/content/challenges/<your-organization-uuid>/<challenge-folder-name>/

A challenge is typically one scenario broken into a few sections:

content/challenges/<your-organization-uuid>
└── keda-autoscaling-challenge/     <-- The <challenge-name> directory
    ├── _index.md                   <-- Defines the challenge's metadata
    ├── keda-icon.svg               <-- Banner image, referenced from the front matter
    └── autoscaling-with-keda/      <-- The task itself
        ├── _index.md               <-- The objective and prerequisites
        └── content/
            ├── description/        <-- What the challenge is about, and the steps
            ├── getting-started/    <-- How to set up and begin
            └── faq/                <-- Common questions

A challenge that ships an interactive lab and a graded exam adds them as their own sections alongside the task:

content/challenges/<your-organization-uuid>
└── heal-the-mesh/
    ├── _index.md
    ├── lab/
    │   └── _index.md               <-- The hands-on lab
    └── exam/
        └── _index.md               <-- The assessment that closes the challenge

2. Define the Challenge with Front Matter 🔗

The _index.md at the root of the challenge folder carries its metadata. Here is a complete example, taken from a published challenge:

---
title: "CNCF Autoscaling Challenge"
description: "Learn event-driven autoscaling in Kubernetes. Work with scaled objects in KEDA, monitoring with Prometheus, OpenTelemetry & CloudEvents and advanced KEDA configurations."
banner: "keda-icon.svg"
id: "<your-challenge-uuid>"
weight: 1
tags: [meshery, keda, open source]
level: "advanced"
categories: "platform"

prerequisite_knowledge:
  - title: "Access to Meshery"
    children:
      - title: "Self-hosted Meshery"
        link: "https://docs.meshery.io/installation"
      - title: "Meshery Playground"
        link: "https://play.meshery.io"

additional_attributes:
  - title: "Retake Policy"
    value: "3"
    description: "Up to three retakes allowed per exam"
---

Front Matter Fields Reference 🔗

Fields marked ✅ are required; those marked - are optional.

3. Write the Scenario 🔗

The task’s own _index.md is where you state the objective and the prerequisites, and the sections beneath it carry the detail:

• Description - what the challenge is about, and the numbered steps a learner must follow to complete it.
• Getting Started - how to get an environment ready, including any Meshery access the scenario needs.
• FAQ - the questions learners predictably ask.

Write the steps so that success is unambiguous. A challenge is scored, so a learner needs to know exactly what “done” looks like before they start.

4. Add the Assessment 🔗

Most challenges close with an exam that validates the learner’s work. Exams in a challenge follow the same unified Academy assessment standard as every other content type.

5. Publish 🔗

Publishing a challenge is the same two-stage release process as the rest of your Academy content: a GitHub Release on your content repository, followed by a Layer5 Cloud release. Until both have happened, your changes will not be live. See Publishing Your Content.

Monitoring Your Challenge 🔗

Once a challenge is live, the Instructor Console is where you watch how it is doing. Every widget there can be narrowed to challenges:

• Content Stats counts your published content by type; clicking the Challenge count opens the Academy Catalog filtered to your challenges.
• Content Metrics ranks your content by passes, so you can see where your challenge sits against your other material.
• All Learners Report lists individual registrations. Filter Content Type to Challenge to see only the people attempting yours, and filter Status to follow who is Registered, In Progress, Completed, Failed or Withdrawn.
• Test Stats and Test Metrics report pass rates per assessment, which is how you tell a challenge that is hard from one whose instructions are unclear.

A full tour of each widget, and what to do about what it tells you, is in the Academy Instructor Console Guide.

Learner Outcomes: Badges 🔗

Completing all the required components of a challenge earns the learner a digital badge - a verifiable credential they can share on their professional profiles. Unlike a Certification, a Challenge does not issue a paid Certificate of Completion; its outcome is the score, the rank, and the badge.

See Earning Badges and Certificates for the learner’s side of this.

Frequently Asked Questions 🔗

Related Reading

• Academy Instructor Console Guide
• Building Certifications
• Creating Content for the Academy
• Extending the Academy
• Integrating Assessments in the Academy
• Learner Guide