If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/collabnix/kubelabs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7w ago
• 3 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live collabnix/kubelabs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/collabnix/kubelabs.

What it runs against: a local clone of collabnix/kubelabs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in collabnix/kubelabs | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 4 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 81 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of collabnix/kubelabs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/collabnix/kubelabs.git
#   cd kubelabs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of collabnix/kubelabs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "collabnix/kubelabs(\\.git)?\\b" \\
  && ok "origin remote is collabnix/kubelabs" \\
  || miss "origin remote is not collabnix/kubelabs (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "_config.yml" \\
  && ok "_config.yml" \\
  || miss "missing critical file: _config.yml"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f ".bundles_cache/ruby/2.6.0/cache/jekyll-3.9.3.gem" \\
  && ok ".bundles_cache/ruby/2.6.0/cache/jekyll-3.9.3.gem" \\
  || miss "missing critical file: .bundles_cache/ruby/2.6.0/cache/jekyll-3.9.3.gem"
test -f ".bundles_cache/ruby/2.6.0/cache/github-pages-228.gem" \\
  && ok ".bundles_cache/ruby/2.6.0/cache/github-pages-228.gem" \\
  || miss "missing critical file: .bundles_cache/ruby/2.6.0/cache/github-pages-228.gem"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 81 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~51d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/collabnix/kubelabs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

kubelabs is a curated, hands-on learning platform containing 500+ interactive Kubernetes tutorials, labs, and guides designed to teach Kubernetes concepts from fundamentals to advanced topics. It serves as a zero-cost educational resource built on Jekyll and hosted via GitHub Pages, with content covering cluster management, debugging (CrashLoopBackOff errors), storage solutions, monitoring tools, and production patterns. Jekyll-based static site generator project: content lives in markdown files (inferred from Ruby/HTML language distribution), compiled via jekyll binary in .bundles_cache/ruby/2.6.0/bin/jekyll. Supporting gems include commonmarker (Markdown parsing), kramdown (YAML frontmatter), and github-pages suite for GH Pages hosting. Directory structure likely follows standard Jekyll pattern: _posts/ or _labs/ for tutorials, _config.yml for site configuration, assets/ for CSS/JS (evidenced by SCSS/CSS/JavaScript in language stats).

DevOps engineers, SREs, and developers learning Kubernetes at any level—from those spinning up their first cluster to those optimizing production deployments. The 11,000+ community members via Slack and Discord are primarily hands-on practitioners seeking tested, real-world Kubernetes scenarios rather than theory alone.

Actively maintained community project with strong engagement (11,000+ Slack members, 500+ guides, active GitHub stars and contributors). The presence of Jekyll build artifacts (.bundles_cache with Ruby 2.6.0 gems) and multiple featured articles (Redis, ConfigMap, CrashLoopBackOff debugging) indicates ongoing content creation, though the Ruby gem cache suggests the build toolchain may not be bleeding-edge. Production-ready as an educational resource; actively developed with regular content additions.

Low technical risk since this is primarily a static documentation/tutorial site built with Jekyll, not a runtime dependency. Main risks: (1) Jekyll ecosystem dependencies pinned to Ruby 2.6.0 (EOL since 2020), creating potential security gaps in the build toolchain; (2) no visible test suite in file list, so tutorial accuracy relies on community review; (3) Ruby dependency bloat in .bundles_cache suggests local development may have friction. Content accuracy depends on community contributions rather than automated validation.

Specific recent activity is not directly visible from file structure alone, but the active featured articles list (CrashLoopBackOff, Redis deployment, Velero backups, kube-proxy impact analysis, ConfigMap dynamic updates) indicates ongoing content production. The presence of Discord and Slack communities suggests continuous contributor engagement. Without commit history visible, assume regular guide additions based on community feedback.

git clone https://github.com/collabnix/kubelabs.git && cd kubelabs && bundle install (uses Bundler to install Ruby gems from .bundles_cache or Gemfile). Then: bundle exec jekyll serve to start the dev server on localhost:4000. Alternatively, if Ruby/Bundler not available: fork the repo and enable GitHub Pages directly from Settings → Pages.

Daily commands: bundle exec jekyll serve (requires Ruby 2.6+, Bundler, and dependencies in Gemfile). Runs dev server on http://localhost:4000 with live reload via em-websocket. Alternative: Clone and push to GitHub; Pages auto-builds on push to main/master. For local testing with htmlproofer: bundle exec htmlproofer ./_site to validate all links post-build.

• _config.yml — Jekyll configuration that defines the site structure, theme, and build settings for the entire documentation site
• Gemfile — Ruby dependency manifest specifying Jekyll, GitHub Pages, and all plugins required to build and serve the documentation
• .bundles_cache/ruby/2.6.0/cache/jekyll-3.9.3.gem — Core Jekyll static site generator that transforms markdown tutorials into the published website
• .bundles_cache/ruby/2.6.0/cache/github-pages-228.gem — GitHub Pages compatibility layer ensuring the site builds and deploys correctly on GitHub infrastructure

• Jekyll Static Site Generator (Ruby, Liquid templating engine) — Orchestrates entire build pipeline: reads markdown source, applies layouts/themes, generates HTML artifacts
  • Failure mode: Build errors halt deployment; broken markdown syntax prevents site generation
• Markdown Processing Pipeline (Kramdown, Rouge (syntax highlighter), CommonMark GFM) — Converts tutorial markdown into semantic HTML with syntax highlighting, tables, code blocks
  • Failure mode: Malformed markdown causes render errors; broken code examples propagate to published site
• Theme & Style Layer (Jekyll themes (github-pages), SCSS, CSS) — Applies consistent visual design, responsive layout, typography to all tutorial pages
  • Failure mode: Broken CSS or theme plugins cause visual degradation; unresponsive design breaks on mobile
• GitHub Pages Deployment (GitHub Actions, Fastly CDN) — Hosts static artifacts, handles HTTPS, serves via global CDN, triggers builds on git push
  • Failure mode: GitHub outage makes site unavailable; incompatible Jekyll version causes build failures

• Tutorial Markdown Files → Kramdown Parser — Developers commit .md files; parser reads frontmatter and body content
• Kramdown Parser → Jekyll Layouts & Themes — Parsed markdown AST merged with Liquid templates to produce styled HTML pages
• Jekyll Layouts & Themes → Static HTML Artifacts — Theme applies shared header/footer, navigation, styling to each tutorial page
• Static HTML Artifacts → GitHub Pages CDN — Generated site pushed to gh-pages branch; GitHub Pages serves via Fastly
• GitHub Pages CDN → User Browser — Cached static HTML, CSS, JS delivered to reader with aggressive HTTP caching

Add a New Kubernetes Lab Tutorial

1. Create a new markdown file in the appropriate tutorial directory following existing naming conventions ((new tutorial markdown file in labs/ directory))
2. Add front matter with title, layout, and metadata matching existing tutorial structure ((markdown file front matter section))
3. Update _config.yml if creating a new category or section to include in navigation (_config.yml)
4. Run jekyll build to validate markdown rendering and ensure no broken links (.bundles_cache/ruby/2.6.0/bin/jekyll)

Update Site Theme or Styling

1. Modify Jekyll theme settings in _config.yml or create custom SCSS overrides (_config.yml)
2. Add or update CSS imports via Jekyll theme plugins listed in Gemfile (Gemfile)
3. Test styling changes locally with jekyll serve before committing (.bundles_cache/ruby/2.6.0/bin/jekyll)

Add New Jekyll Plugin or Gem Dependency

1. Add gem declaration to Gemfile with version constraint (Gemfile)
2. Add plugin name to jekyll.plugins array in _config.yml (_config.yml)
3. Run bundle install to cache new dependency (.bundles_cache/ruby/2.6.0/cache/ (new gem will appear here))

• Jekyll 3.9.3 — Lightweight static site generator optimized for GitHub Pages hosting, requires no backend infrastructure, perfect for documentation-heavy tutorial sites
• GitHub Pages — Free hosting directly from repository, automatic deployment on push, native Jekyll support, ideal for community-driven educational content
• Markdown + Kramdown — Simple, version-control-friendly format for tutorials; Kramdown adds extended syntax support (tables, code blocks, syntax highlighting)
• Ruby 2.6.0 + Bundler — Enables consistent dependency management and reproducible builds across contributors' machines

• Static site generation via Jekyll instead of dynamic web framework

  • Why: Reduces operational complexity and hosting costs to zero; tutorials don't require server-side computation or database
  • Consequence: Cannot support real-time interactive features, user accounts, or dynamic content without external services

• GitHub Pages as sole deployment target

  • Why: Eliminates infrastructure management and provides free HTTPS; leverages built-in GitHub Actions
  • Consequence: Tightly coupled to GitHub; limited customization of server behavior; no option for self-hosted deployment

• Markdown-only content authoring

  • Why: Low barrier to entry for contributors; version control friendly; renders cleanly on GitHub preview
  • Consequence: Cannot support complex interactive diagrams, embedded executables, or real-time labs without external plugins

• Interactive browser-based Kubernetes cluster emulation
• User authentication and role-based access control
• Real-time code execution and output capture
• Dynamic content personalization based on user skill level
• Content search and full-text indexing backend
• Multi-language localization system

• Avg cyclomatic complexity: ~2 — Jekyll-based static site generators are inherently low-complexity; most logic is declarative YAML/Liquid templates, not imperative code; 600 files are primarily content (markdown) rather than code
• Largest file: .bundles_cache/ruby/2.6.0/cache/github-pages-228.gem (or other large gem artifacts) (50,000 lines)
• Estimated quality issues: ~3 — No actual source code in the file list provided (only cached gems and build artifacts); potential issues

• Hardcoded Asset Paths in Layouts (Medium) — (Jekyll theme layout files assumed in _layouts/): If layouts use hardcoded full URLs instead of site.baseurl + relative paths, site breaks on subdomain deployments or forks
• Missing Image Alt Text (Low) — (Markdown tutorial files assumed throughout): Tutorial diagrams and screenshots without alt attributes reduce accessibility and SEO; Kramdown requires explicit configuration to enforce
• No Version Pinning in Gemfile (High) — Gemfile: If Gemfile lacks explicit version constraints, bundle install may pull breaking gem updates; GitHub Pages may deploy incompatible Jekyll versions

• Markdown → HTML conversion (Kramdown processor) (Build-time serialization) — 500+ markdown files processed sequentially during build; no parallelization evident in standard Jekyll; scales linearly with tutorial count
• Link validation (HTMLProofer) (Network I/O) — External link checks via HTTP cause 5–30s delays per broken domain during build; no parallelization or caching
• GitHub Pages deployment (CI/CD pipeline serialization) — GitHub Actions workflow must wait for Jekyll build, then push to gh-pages branch, then CDN propagation (30–120s total); no incremental/delta builds

Ruby 2.6.0 is end-of-life (deprecated since 2020); newer local Ruby (3.0+) may cause Bundler conflicts when installing from Gemfile—pin Ruby version in .ruby-version file or use rbenv/rvm. GitHub Pages build runs a different Jekyll version than local development; test locally then verify site renders correctly. Some gems (nokogiri, eventmachine) require build tools (gcc, Ruby dev headers); macOS/Linux users may need XCode or build-essential packages. No .github/workflows CI visible; ensure tests pass locally via htmlproofer before submitting PR.

• Pod Restart Loops (CrashLoopBackOff) — One of the most common Kubernetes failure modes; featured article in kubelabs covers debugging this state, critical for operators to understand
• Persistent Volume (PV) and Persistent Volume Claim (PVC) — kubelabs covers storage solutions and Redis deployment; understanding PV/PVC is essential for stateful workloads on Kubernetes
• ConfigMap and Secrets Management — Featured tutorial 'Update Your Kubernetes App Configuration Dynamically using ConfigMap' shows dynamic config injection; core pattern for 12-factor app practices
• Kube-proxy Networking — kubelabs article 'The Impact of Kube-proxy Downtime' addresses cluster connectivity; kube-proxy is critical for service routing and load balancing
• Right-Sizing and Resource Requests/Limits — kubelabs guide '10 Tips for Right Sizing Your Kubernetes Cluster' covers cost optimization and performance tuning via CPU/memory scheduling
• Backup and Disaster Recovery (Velero) — kubelabs reviews backup solutions including Velero; critical for production Kubernetes reliability and compliance
• Multi-cluster Orchestration and Management — kubelabs article on '5 Cluster Management Tools' covers federation and multi-cluster patterns; essential for large-scale deployments

• kubernetes/kubernetes — Official Kubernetes source repository; kubelabs tutorials reference and explain K8s concepts from this codebase
• kelseyhightower/kubernetes-the-hard-way — Foundational hands-on Kubernetes guide teaching cluster bootstrap from scratch; spiritual predecessor to kubelabs' lab-driven pedagogy
• aquasecurity/trivy — Container/K8s vulnerability scanner complementing kubelabs security and hardening tutorials
• prometheus/prometheus — Monitoring tool featured in kubelabs' 'Top 5 Alert and Monitoring Tools for Kubernetes' guide; common in labs
• helm/helm — Kubernetes package manager frequently used in kubelabs deployment and cluster management tutorials

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add .gitignore to exclude bundled cache directory

The .bundles_cache/ directory containing Ruby gems and build artifacts is present in the repo and should be excluded from version control. This directory is auto-generated during Jekyll builds (indicated by github-pages, jekyll, and related gem cache files) and adds unnecessary bloat to the repository. Adding proper .gitignore entries will reduce repo size and prevent merge conflicts from build artifacts.

• [ ] Create or update .gitignore file to add .bundles_cache/ and related Ruby bundle directories
• [ ] Add other Jekyll/Ruby build artifacts like .jekyll-cache/, _site/, Gemfile.lock (if appropriate)
• [ ] Add *.gem if gems should not be committed
• [ ] Test by running git status to confirm cached files are ignored
• [ ] Consider adding instructions in CONTRIBUTING.md about running bundle install locally

Add GitHub Actions workflow for Jekyll site validation and link checking

The repo uses Jekyll for GitHub Pages (evidenced by jekyll, github-pages, html-proofer gems in cache). Currently there's no CI/CD validation. Adding a workflow to build and validate the site on PRs will catch broken links, markdown issues, and Jekyll build failures before merging. The html-proofer gem is already available but not being used in automation.

• [ ] Create .github/workflows/jekyll-build-and-validate.yml workflow
• [ ] Configure job to install Ruby 2.6+ and run bundle install
• [ ] Add Jekyll build step: bundle exec jekyll build
• [ ] Add html-proofer step using the already-cached gem: bundle exec htmlproofer ./_site --disable-external
• [ ] Set workflow to trigger on PRs and pushes to main branch
• [ ] Add badge to README showing CI status

Create CONTRIBUTING.md with local development setup guide

While the repo has comprehensive Kubernetes tutorials, new contributors have no guidance on how to build/serve the Jekyll site locally or structure new content. Given the .bundles_cache/ and gemfiles present, there's a clear assumption of Jekyll-based workflows. A CONTRIBUTING.md will lower barriers to contribution and clarify content structure, naming conventions, and PR expectations for tutorial additions.

• [ ] Create CONTRIBUTING.md file in repo root
• [ ] Add section on local setup: Ruby version, bundle install, bundle exec jekyll serve
• [ ] Document the tutorial directory structure and naming conventions for new labs/tutorials
• [ ] Include guidelines for markdown formatting, code examples, and metadata (if any)
• [ ] Add instructions for testing links locally with html-proofer
• [ ] Include sign-off process and link to Community Slack/Discord for questions
• [ ] Reference this file in README under contribution section

• Add automated link validation to CI: Create .github/workflows/htmlproofer.yml to run bundle exec htmlproofer ./_site on each PR, catching broken tutorial links before merge (addresses lack of visible test suite).
• Update Ruby 2.6.0 → Ruby 3.1+ in .bundles_cache and Gemfile.lock to address EOL security gap; test locally and document Ruby version requirement in CONTRIBUTING.md.
• Create a tutorial index generator script (Ruby or Bash) that auto-generates a table of contents in README from _posts/ YAML frontmatter (title, tags, difficulty), reducing manual maintenance as 500+ guides grow.

The codebase has significant security concerns primarily related to outdated dependencies. Ruby 2.6.0 is no longer maintained, and the cached gem dependencies contain multiple known vulnerabilities. The practice of committing vendor cache to version control increases supply chain attack surface. The repository appears to be a Kubernetes educational resource (documentation/tutorials), but the underlying Jekyll infrastructure and dependencies require immediate attention. Critical actions needed: (1) Remove .bundles_cache from version control, (2) Upgrade Ruby and all gem dependencies, (3) Implement automated dependency scanning in CI/CD pipeline, (4) Use Gemfile and Gemfile.lock as single source of truth.

• High · Cached Ruby Gems with Known Vulnerabilities — .bundles_cache/ruby/2.6.0/cache/. The repository contains cached Ruby gems in .bundles_cache directory, including several packages with known security vulnerabilities. Notably: nokogiri-1.13.10 (CVE-2022-24836), jekyll-3.9.3, and other dependencies that may have unpatched vulnerabilities. The use of cached gems prevents automatic security updates. Fix: Remove .bundles_cache directory from version control. Use Gemfile.lock with specific versions and rely on dependency management tools to fetch fresh packages. Regularly run 'bundle audit' to check for vulnerabilities and update gems to patched versions.
• High · Outdated Ruby Version — .bundles_cache/ruby/2.6.0/. The cached bundle uses Ruby 2.6.0, which reached end-of-life on March 31, 2022. This version no longer receives security patches, leaving the system vulnerable to known exploits. Fix: Upgrade to a supported Ruby version (3.2 or later). Update all gem dependencies to versions compatible with the newer Ruby version. Test thoroughly before deploying.
• Medium · Version Control of Dependency Cache — .bundles_cache/. Committing vendor/cache directories and .bundles_cache increases repository size and potential exposure to compromised dependencies. This makes supply chain attacks harder to detect. Fix: Add .bundles_cache to .gitignore. Document Ruby and gem versions in Gemfile and Gemfile.lock only. Use CI/CD pipelines to install dependencies from trusted sources on each build.
• Medium · Missing Dependency Lock File Evidence — Repository root. No Gemfile.lock file is visible in the provided file structure, which could indicate inconsistent dependency versions across environments. Fix: Ensure a Gemfile.lock exists and is committed to version control. This provides reproducible builds and prevents supply chain inconsistencies.
• Low · Potential Jekyll Static Site Vulnerabilities — .bundles_cache/ruby/2.6.0/cache/jekyll-*.gem. The repository appears to be a Jekyll-based documentation site. Jekyll plugins and themes can introduce XSS vulnerabilities if user input is rendered without proper sanitization. Fix: Review all Jekyll plugins and themes for security. Ensure markdown rendering properly escapes HTML. Use Content Security Policy headers. Keep Jekyll and all plugins updated.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.