From 131543548ecc187014cd05c229dffec7d9f016c4 Mon Sep 17 00:00:00 2001 From: Katharina Sick Date: Fri, 29 May 2026 14:17:08 +0200 Subject: [PATCH] update docs to the new yaml format Signed-off-by: Katharina Sick --- .../00-lex-imperfecta/docs/beginner.md | 160 ------------------ .../00-lex-imperfecta/docs/beginner.yaml | 154 +++++++++++++++++ .../planned/00-lex-imperfecta/docs/index.md | 28 --- .../planned/00-lex-imperfecta/docs/index.yaml | 21 +++ 4 files changed, 175 insertions(+), 188 deletions(-) delete mode 100644 adventures/planned/00-lex-imperfecta/docs/beginner.md create mode 100644 adventures/planned/00-lex-imperfecta/docs/beginner.yaml delete mode 100644 adventures/planned/00-lex-imperfecta/docs/index.md create mode 100644 adventures/planned/00-lex-imperfecta/docs/index.yaml diff --git a/adventures/planned/00-lex-imperfecta/docs/beginner.md b/adventures/planned/00-lex-imperfecta/docs/beginner.md deleted file mode 100644 index 04fb7e9..0000000 --- a/adventures/planned/00-lex-imperfecta/docs/beginner.md +++ /dev/null @@ -1,160 +0,0 @@ -# đŸŸĸ Beginner: The Twelve Tables - -> **Best suited for:** Platform engineers, SREs, and developers curious about Kubernetes security — no prior Kyverno experience needed, but familiarity with basic `kubectl` and YAML will help. - -The Republic's legal scholars have been busy — perhaps too busy. In their haste to codify the Twelve Tables, the foundation of the Republic's legal system, they introduced errors that now threaten the city's order. Workloads that should be blocked are running freely, and workloads that should be allowed are being turned away at the gates. - -Another scholar left a note: "I tried to set up policies for privileged containers and required labels, but something's off — I can't figure out why the wrong things are getting through. There was also supposed to be a system for automatically issuing travel permits to foreign visitors, but that one is broken too." - -Your mission: investigate the Kyverno policies and restore proper admission control before chaos reaches the city. - -## 🏗ī¸ Architecture - -The defining principle of the Twelve Tables was that Roman law was enforced **at the gates** — before a citizen could act, not after the damage was done. Kubernetes admission control works exactly the same way: Kyverno intercepts every request to create or update a workload and checks it against your policies *before* it reaches the cluster. A misconfigured policy doesn't just fail to enforce — it fails silently, letting non-compliant workloads slip through unnoticed while you assume everything is fine. - -That's the situation you've inherited. Your Codespace comes with a Kubernetes cluster and Kyverno pre-installed. Three policies are already deployed — two `ValidatingPolicy` resources that validate workloads, and one `MutatingPolicy` that automatically stamps incoming pods with the right labels. All three are misconfigured. The policies live in `manifests/policies/`. You will edit them directly and re-apply with `kubectl`. - -The pods in `manifests/pods/` are there for reference only — **you don't need to edit them**. - -No GitOps, no dashboards — just you, the policies, and the cluster. - -## đŸŽ¯ Objective - -By the end of this level, you should have: - -- All workloads **missing the `republic.rome/gens` label** blocked at admission with a clear policy violation message -- All workloads **running as privileged containers** blocked at admission with a clear policy violation message -- All pods declaring **`republic.rome/traveler: peregrinus`** automatically receiving the **`republic.rome/travel-permit: granted`** label -- Confirmed that **all other workloads** deploy and run successfully in the cluster - -## 🧠 What You'll Learn - -- How Kyverno [`ValidatingPolicy`](https://kyverno.io/docs/policy-types/validating-policy/) resources and [CEL validation expressions](https://kubernetes.io/docs/reference/using-api/cel/) work -- The difference between [`Audit`, `Deny`, and `Warn`](https://kyverno.io/docs/policy-types/validating-policy/) validation actions -- How to use [custom label keys](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to enforce workload identity standards -- How Kyverno [`MutatingPolicy`](https://kyverno.io/docs/policy-types/mutating-policy/) resources automatically patch incoming workloads at admission - -## 🧰 Toolbox - -Your Codespace comes pre-configured with the following tools: - -| Tool | What it's for | -|------|---------------| -| `kubectl` | Apply and inspect cluster resources | -| `kyverno` CLI | Test and lint policies locally before applying | -| `k9s` | Explore cluster resources in a terminal UI | - -## ⏰ Deadline - -> ℹī¸ You can still complete the challenge after this date, but points will only be awarded for submissions before the -> deadline. - -## đŸ’Ŧ Join the discussion - -Share your solutions and questions in -the [challenge thread](TODO) -in the Open Ecosystem Community. - -## ✅ How to Play - -### 1. Start Your Challenge - -> 📖 **First time?** Check out the [Getting Started Guide](../../start-a-challenge) for detailed instructions on -> forking, starting a Codespace, and waiting for infrastructure setup. - -Quick start: - -- Fork the [repo](https://github.com/dynatrace-oss/open-ecosystem-challenges/) -- Create a Codespace -- Select "⚖ī¸ Adventure 00 | đŸŸĸ Beginner (The Twelve Tables)" -- Wait a couple of minutes for the environment to initialize (`Cmd/Ctrl + Shift + P` → `View Creation Log` to view progress) - -### 2. Explore the Cluster - -When your Codespace is ready, four pods are already running — or trying to. Open a terminal and check what's going on: - -```bash -kubectl get pods -``` - -Inspect why a pod was blocked or admitted: - -```bash -kubectl describe pod -``` - -Check the policies that are in place: - -```bash -kubectl get validatingpolicies -kubectl get validatingpolicy require-labels -o yaml -kubectl get validatingpolicy no-privileged-containers -o yaml - -kubectl get mutatingpolicies -kubectl get mutatingpolicy stamp-travel-permit -o yaml -``` - -You can also launch **k9s** for a terminal UI view of all cluster resources: - -```bash -k9s -``` - -Navigate to `ValidatingPolicy` resources with `:validatingpolicies` and `MutatingPolicy` resources with `:mutatingpolicies` to inspect all three policies. - -### 3. Fix the Policies - -Review the [đŸŽ¯ Objective](#objective) and investigate what's wrong in `manifests/policies/`. - -All three broken policies are in `manifests/policies/`. Read them carefully — each has a different kind of misconfiguration. - -#### Test Locally with the Kyverno CLI - -Before applying to the cluster, you can use the `kyverno` CLI to test your policy changes locally against the workload manifests: - -```bash -kyverno apply manifests/policies/require-labels.yaml --resource manifests/pods/missing-labels.yaml -kyverno apply manifests/policies/no-privileged-containers.yaml --resource manifests/pods/privileged.yaml -kyverno apply manifests/policies/stamp-travel-permit.yaml --resource manifests/pods/peregrinus.yaml -``` - -This gives you fast feedback without touching the cluster. - -#### Apply to the Cluster - -Once you're happy with your changes, re-apply everything: - -```bash -make apply -``` - -This re-applies the policies and re-deploys all workloads so you immediately see the effect of your changes. - -#### Helpful Documentation - -- [Kyverno ValidatingPolicy](https://kyverno.io/docs/policy-types/validating-policy/) -- [Kyverno MutatingPolicy](https://kyverno.io/docs/policy-types/mutating-policy/) -- [CEL Validation Expressions](https://kubernetes.io/docs/reference/using-api/cel/) -- [Kyverno Playground](https://playground.kyverno.io/#/) — test your CEL expressions interactively against sample resources before applying them to the cluster - -### 4. Verify Your Solution - -Once you think you've solved the challenge, run the verification script: - -```bash -./verify.sh -# or: make verify -``` - -**If the verification fails:** - -The script will tell you which checks failed and give you a hint. Fix the issues and run it again. - -**If the verification passes:** - -1. The script will check if your changes are committed and pushed. -2. Follow the on-screen instructions to commit your changes if needed. -3. Once everything is ready, the script will generate a **Certificate of Completion**. -4. **Copy this certificate** and paste it into - the [challenge thread](TODO) - to claim your victory! 🏆 diff --git a/adventures/planned/00-lex-imperfecta/docs/beginner.yaml b/adventures/planned/00-lex-imperfecta/docs/beginner.yaml new file mode 100644 index 0000000..0e3fd16 --- /dev/null +++ b/adventures/planned/00-lex-imperfecta/docs/beginner.yaml @@ -0,0 +1,154 @@ +level: beginner +emoji: đŸŸĸ +title: The Twelve Tables +devcontainer: lex-imperfecta_beginner +community_url: "" # TODO + +summary: Fix broken Kyverno policies to restore proper admission control. + +audience: >- + Platform engineers, SREs, and developers curious about Kubernetes security — no prior Kyverno experience needed, + but familiarity with basic `kubectl` and YAML will help. + +backstory: + - >- + The Republic's legal scholars have been busy — perhaps too busy. In their haste to codify the Twelve Tables, the + foundation of the Republic's legal system, they introduced errors that now threaten the city's order. Workloads + that should be blocked are running freely, and workloads that should be allowed are being turned away at the gates. + - >- + Another scholar left a note: "I tried to set up policies for privileged containers and required labels, but + something's off — I can't figure out why the wrong things are getting through. There was also supposed to be a + system for automatically issuing travel permits to foreign visitors, but that one is broken too." + - >- + Your mission: investigate the Kyverno policies and restore proper admission control before chaos reaches the city. + +objective: + - >- + All workloads **missing the `republic.rome/gens` label** blocked at admission with a clear policy violation message + - >- + All workloads **running as privileged containers** blocked at admission with a clear policy violation message + - >- + All pods declaring **`republic.rome/traveler: peregrinus`** automatically receiving the **`republic.rome/travel-permit: granted`** label + - >- + Confirmed that **all other workloads** deploy and run successfully in the cluster + +what_you_learn: + - >- + How Kyverno [`ValidatingPolicy`](https://kyverno.io/docs/policy-types/validating-policy/) resources and + [CEL validation expressions](https://kubernetes.io/docs/reference/using-api/cel/) work + - >- + The difference between [`Audit`, `Deny`, and `Warn`](https://kyverno.io/docs/policy-types/validating-policy/) + validation actions + - >- + How to use [custom label keys](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) to + enforce workload identity standards + - >- + How Kyverno [`MutatingPolicy`](https://kyverno.io/docs/policy-types/mutating-policy/) resources automatically + patch incoming workloads at admission + +architecture: + - >- + The defining principle of the Twelve Tables was that Roman law was enforced **at the gates** — before a citizen + could act, not after the damage was done. Kubernetes admission control works exactly the same way: Kyverno + intercepts every request to create or update a workload and checks it against your policies *before* it reaches the + cluster. A misconfigured policy doesn't just fail to enforce — it fails silently, letting non-compliant workloads + slip through unnoticed while you assume everything is fine. + - >- + That's the situation you've inherited. Your Codespace comes with a Kubernetes cluster and Kyverno pre-installed. + Three policies are already deployed — two `ValidatingPolicy` resources that validate workloads, and one + `MutatingPolicy` that automatically stamps incoming pods with the right labels. All three are misconfigured. + The policies live in `manifests/policies/`. You will edit them directly and re-apply with `kubectl`. + - >- + The pods in `manifests/pods/` are there for reference only — **you don't need to edit them**. + - >- + No GitOps, no dashboards — just you, the policies, and the cluster. + +toolbox: + - name: kubectl + url: "https://kubernetes.io/docs/reference/kubectl/" + description: Apply and inspect cluster resources + - name: kyverno CLI + url: "https://kyverno.io/docs/kyverno-cli/" + description: Test and lint policies locally before applying + - name: k9s + url: "https://k9scli.io/" + description: Explore cluster resources in a terminal UI + +services: [] + +how_to_play: + - id: explore + title: "Explore the Cluster" + content: | + When your Codespace is ready, four pods are already running — or trying to. Open a terminal and check what's going on: + + ```bash + kubectl get pods + ``` + + Inspect why a pod was blocked or admitted: + + ```bash + kubectl describe pod + ``` + + Check the policies that are in place: + + ```bash + kubectl get validatingpolicies + kubectl get validatingpolicy require-labels -o yaml + kubectl get validatingpolicy no-privileged-containers -o yaml + + kubectl get mutatingpolicies + kubectl get mutatingpolicy stamp-travel-permit -o yaml + ``` + + You can also launch **k9s** for a terminal UI view of all cluster resources: + + ```bash + k9s + ``` + + Navigate to `ValidatingPolicy` resources with `:validatingpolicies` and `MutatingPolicy` resources with `:mutatingpolicies` to inspect all three policies. + - id: fix-policies + title: Fix the Policies + content: | + Review the [Objective](#objective) and investigate what's wrong in `manifests/policies/`. + + All three broken policies are in `manifests/policies/`. Read them carefully — each has a different kind of misconfiguration. + + **Test Locally with the Kyverno CLI** + + Before applying to the cluster, you can use the `kyverno` CLI to test your policy changes locally against the workload manifests: + + ```bash + kyverno apply manifests/policies/require-labels.yaml --resource manifests/pods/missing-labels.yaml + kyverno apply manifests/policies/no-privileged-containers.yaml --resource manifests/pods/privileged.yaml + kyverno apply manifests/policies/stamp-travel-permit.yaml --resource manifests/pods/peregrinus.yaml + ``` + + This gives you fast feedback without touching the cluster. + + **Apply to the Cluster** + + Once you're happy with your changes, re-apply everything: + + ```bash + make apply + ``` + + This re-applies the policies and re-deploys all workloads so you immediately see the effect of your changes. + +helpful_links: + - title: Kyverno ValidatingPolicy + url: "https://kyverno.io/docs/policy-types/validating-policy/" + description: Reference docs for ValidatingPolicy — the resource type you'll fix to block non-compliant workloads + - title: Kyverno MutatingPolicy + url: "https://kyverno.io/docs/policy-types/mutating-policy/" + description: Reference docs for MutatingPolicy — the resource type you'll fix to auto-stamp travel permits + - title: CEL Validation Expressions + url: "https://kubernetes.io/docs/reference/using-api/cel/" + description: How CEL expressions work in Kubernetes admission — what you'll write inside the policy rules + - title: Kyverno Playground + url: "https://playground.kyverno.io" + description: Test your CEL expressions interactively against sample resources before applying them to the cluster \ No newline at end of file diff --git a/adventures/planned/00-lex-imperfecta/docs/index.md b/adventures/planned/00-lex-imperfecta/docs/index.md deleted file mode 100644 index ee14e63..0000000 --- a/adventures/planned/00-lex-imperfecta/docs/index.md +++ /dev/null @@ -1,28 +0,0 @@ -# ⚖ī¸ Adventure 00: Lex Imperfecta - -The Republic's legal system is in disarray — workloads run unchecked, required labels go missing, and privileged containers slip through the gates. As a newly appointed Praetor, your mission is to restore order by fixing broken Kyverno policies and enforcing proper admission control. - -**Technologies:** Kyverno, Kubernetes - -The entire **infrastructure is pre-provisioned in your Codespace** — you don't need to set up anything locally. Just focus on solving the problem. - -## đŸĒ The Backstory - -The Roman Republic has built a sophisticated legal system to protect its citizens — but the laws were written -in haste, and the exceptions were written too generously. Policies go unenforced, the wrong citizens are exempt, and -something has slipped through the gates unnoticed. As a newly appointed Praetor, your mission is to restore order before -chaos takes hold. - -## 🎮 Choose Your Level - -Each level is a standalone challenge with its own Codespace that builds on the story while being technically -independent — pick your level and start wherever you feel comfortable. - -### đŸŸĸ Beginner: The Twelve Tables - -- **Status:** 🚧 Coming Soon -- **Topics:** Kyverno, Falco, Policy Reporter, Argo CD, Kubernetes - -Fix broken Kyverno policies to restore proper admission control. - -[**Start the Beginner Challenge**](./beginner.md) diff --git a/adventures/planned/00-lex-imperfecta/docs/index.yaml b/adventures/planned/00-lex-imperfecta/docs/index.yaml new file mode 100644 index 0000000..23828a0 --- /dev/null +++ b/adventures/planned/00-lex-imperfecta/docs/index.yaml @@ -0,0 +1,21 @@ +slug: lex-imperfecta +name: "Lex Imperfecta" +emoji: "⚖ī¸" + +tags: + - Kyverno + - Kubernetes + +backstory: + - The Roman Republic has built a sophisticated legal system to protect its citizens — but the laws were written in haste, and the exceptions were written too generously. Policies go unenforced, the wrong citizens are exempt, and something has slipped through the gates unnoticed. As a newly appointed Praetor, your mission is to restore order before chaos takes hold. + +overview: + - The Republic's legal system is in disarray — workloads run unchecked, required labels go missing, and privileged containers slip through the gates. As a newly appointed Praetor, your mission is to restore order by fixing broken Kyverno policies and enforcing proper admission control. + +rewards: + deadline: "TODO" + tiers: + - label: "1st place" + description: "50% voucher for a Linux Foundation certification" + - label: "Top 3" + description: "Credly badge to showcase the achievement"