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/guangzhengli/k8s-tutorials 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 6mo ago
• 17 active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 6mo ago
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits
• ⚠ No test directory 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 guangzhengli/k8s-tutorials repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/guangzhengli/k8s-tutorials.

What it runs against: a local clone of guangzhengli/k8s-tutorials — 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 guangzhengli/k8s-tutorials | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 202 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of guangzhengli/k8s-tutorials. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/guangzhengli/k8s-tutorials.git
#   cd k8s-tutorials
#
# 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 guangzhengli/k8s-tutorials and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 202 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~172d)"
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/guangzhengli/k8s-tutorials"
  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).

A hands-on Kubernetes tutorial repository that progressively teaches k8s concepts through concrete examples—starting from container basics with Dockerfile/Go applications, then advancing through Pod, Deployment, Service, Ingress, ConfigMap, Secret, Job/CronJob, and Helm. It pairs each concept with working Go applications and YAML manifests that learners deploy to an actual k8s cluster. Modular tutorial structure: each k8s concept gets its own directory (configmaps/, deployment/, cronJob/, etc.) containing a Go application (main.go), Dockerfile, and YAML manifests. Documentation lives in docs/ as Markdown files with VitePress configuration, and a GitHub Actions workflow (release.yml) automates publishing. The pattern is: concept folder → runnable code → docs → deployment YAML.

Developers new to Kubernetes who want practical, step-by-step examples rather than theory alone. Ideal for those already comfortable with containers and Linux but learning orchestration for the first time. Works best for Chinese and English speakers, as docs are bilingual.

Actively maintained with strong GitHub engagement (visible stars/forks/issues badges in README). The repository structure is well-organized with separate directories per concept (container/, pod/, deployment/, etc.) and published online at https://guangzhengli.com/courses/kubernetes. CI/CD setup exists (.github/workflows/release.yml), indicating production-grade publishing practices.

Single maintainer (guangzhengli) creates maintenance risk if they step back. VitePress docs dependency is on RC version (1.0.0-rc.4), which could introduce breaking changes. No visible test suite in the file structure (only Go applications and YAML manifests), meaning examples are validated manually. Docker images are auto-published to Docker Hub (guangzhengli/hellok8s), so image availability depends on CI/CD reliability.

The repo is actively maintained with a VitePress-based documentation site. The .github/workflows/release.yml indicates automated Docker image publishing and docs deployment. Recent activity includes supporting multilingual docs (Chinese 教程 / English tutorials) and expanding examples across deployment variants (v1/, v2/, liveness/, readiness/ subdirectories in deployment/).

git clone https://github.com/guangzhengli/k8s-tutorials.git
cd k8s-tutorials
npm install
npm run docs:dev

Then open http://localhost:5173 to browse the tutorial locally. To run examples, ensure you have a k8s cluster running (Docker Desktop, minikube, or cloud k8s) and kubectl configured.

Daily commands: For docs: npm run docs:dev (runs VitePress dev server on port 5173). For individual examples (e.g., container/): build Docker image from Dockerfile, then deploy using kubectl apply -f <yaml-file>. Prerequisites: Docker, kubectl, and an active k8s cluster.

• docs/index.md: Entry point for the tutorial site; lists and links all k8s concept lessons in progression order
• .github/workflows/release.yml: Automates Docker image building/pushing to Docker Hub and docs site deployment on each release
• configmaps/main.go: Canonical example showing how a Go app reads ConfigMap data injected as environment variables, foundational pattern used across lessons
• deployment/v2/main.go: Demonstrates stateless app design with liveness/readiness probes, core pattern for production k8s deployments
• docs/.vitepress/config.mts: VitePress site configuration; defines doc navigation structure and theme customizations

To add a new k8s concept example: (1) create a directory at the repo root (e.g., volumeMounts/), (2) add main.go demonstrating the feature, (3) add Dockerfile for containerization, (4) add YAML manifests (e.g., hellok8s-volume.yaml), (5) add Markdown doc in docs/ explaining the concept. Follow existing patterns in deployment/ or configmaps/ for consistency.

VitePress is at RC stage (1.0.0-rc.4)—expect possible breaking changes in minor releases. Go examples assume a k8s cluster is already running; no local fallback or embedded server for docs-only learners. Dockerfile examples tag images with guangzhengli/hellok8s but registry credentials are not documented, making it unclear how forks can publish images. YAML manifests reference hardcoded namespace defaults; learners may hit unexpected behavior if deploying to non-default namespaces without adjustments.

• Liveness and Readiness Probes — deployment/liveness/ and deployment/readiness/ examples teach how k8s monitors pod health; critical for production reliability and automatic failure recovery
• ConfigMap and environment variable injection — configmaps/ directory demonstrates how to externalize configuration from code—essential for running the same container image across dev/test/prod environments without rebuilding
• Declarative vs. Imperative deployment — The repo teaches YAML-based declarative deployments (deployment/*.yaml); understanding why this is superior to imperative kubectl commands is foundational to k8s philosophy
• Service abstraction and DNS — docs/service.md explains how k8s Services provide stable DNS names for Pods that may be ephemeral; critical for internal service-to-service communication in a cluster
• Ingress routing and TLS termination — docs/ingress.md teaches how external traffic reaches services via URL paths; essential for exposing multiple applications on a single public IP
• Secret management (opaque vs. docker-registry) — docs/secret.md addresses storing sensitive data (credentials, API keys) separately from ConfigMaps; demonstrates k8s security best practices
• Helm templating and package management — docs/helm.md shows how to parameterize and package entire application stacks; moving from raw YAML to Helm charts is the industry-standard deployment workflow

• kubernetes/kubernetes — Official Kubernetes repository; canonical source for understanding k8s internals and API versions used in this tutorial's YAML manifests
• kelseyhightower/kubernetes-the-hard-way — Step-by-step cluster setup tutorial complementing this repo; teaches k8s architecture from the ground up before deploying applications like these examples
• helm/helm — Helm package manager referenced in docs/helm.md; this tutorial uses Helm as the final deployment abstraction, so understanding Helm's templating is essential
• kubernetes/website — Official k8s documentation site; provides the canonical API reference for YAML manifests and concepts explained in this tutorial's markdown docs
• docker/getting-started — Docker fundamentals tutorial; prerequisite knowledge for understanding the Dockerfile pattern used in every example directory

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 GitHub Actions workflow to automatically build and push Docker images for tutorial examples

The repo contains multiple Dockerfiles across deployment/, configmaps/, container/, helm-charts/, and cronJob/ directories, but there's no CI workflow to validate builds. A workflow that builds and pushes images to Docker Hub (referenced in README badges) would prevent broken examples and ensure all Dockerfiles are functional.

• [ ] Create .github/workflows/docker-build.yml that triggers on changes to any Dockerfile
• [ ] Add build steps for each directory: container/, deployment/v2/, deployment/liveness/, deployment/readiness/, configmaps/, helm-charts/hello-helm/, cronJob/
• [ ] Configure Docker Hub credentials and push logic (leverage existing docker/build-push-action)
• [ ] Test by modifying a Dockerfile and verifying the workflow runs successfully

Add integration tests for Helm chart templates against Kubernetes validation

The helm-charts/hello-helm/ directory contains Kubernetes manifests as Helm templates (deployment, service, configmaps, secrets, ingress), but there's no validation that these templates render correctly or pass Kubernetes schema validation. This prevents template syntax errors and invalid configurations from being committed.

• [ ] Create a new test directory tests/helm/ with a script using helm template + kubeval to validate rendered manifests
• [ ] Test all helm chart templates: hellok8s-deployment.yaml, hellok8s-service.yaml, ingress.yaml, nginx-deployment.yaml
• [ ] Add GitHub Actions workflow .github/workflows/helm-lint.yml using helm lint and kubeval on template rendering
• [ ] Include testing against both values.yaml and values-dev.yaml configurations

Create detailed tutorial documentation for the liveness and readiness probe examples

The deployment/liveness/ and deployment/readiness/ directories contain separate Dockerfiles and deployment.yaml files with distinct implementations, but docs/deployment.md doesn't explain the differences, when to use each, or show actual probe configuration examples. This creates confusion for learners.

• [ ] Add new section to docs/deployment.md explaining liveness probes with code snippet from deployment/liveness/deployment.yaml
• [ ] Add new section for readiness probes with code snippet from deployment/readiness/deployment.yaml and explain the behavioral difference
• [ ] Document when to use each probe type with practical examples (crash detection vs. slow startup)
• [ ] Link to the actual source files and test instructions using kubectl commands

• Add Go unit tests for main.go files in container/, configmaps/, and deployment/v2/ to validate business logic (e.g., config parsing, health check logic) without a k8s cluster—improves confidence in examples
• Expand docs/deployment.md with a troubleshooting section explaining common failure modes (ImagePullBackOff, CrashLoopBackOff, pending pods) and how to diagnose them with kubectl commands, since learners often hit these on first deploy
• Create a missing docs/job.md example that walks through cronJob/hello-cronjob.yaml in parallel with docs/job.md—currently cronJob/ directory exists with YAML but no corresponding tutorial explaining CronJob semantics and use cases

This Kubernetes tutorial repository has a moderate security posture. The primary concerns are: (1) use of pre-release dependency version (VitePress RC), (2) potential secret exposure in version control, (3) Docker images lacking security best practices, and (4) missing Kubernetes security configurations (NetworkPolicies, RBAC). The codebase appears to be educational rather than production-ready. For a tutorial repository, security is acceptable, but if these manifests are used as templates for production, significant hardening is needed. Key actions: update VitePress, implement Docker security scanning, add Kubernetes network and access policies, and ensure secrets are

• High · Outdated VitePress Dependency — package.json - vitepress dependency. The project uses VitePress 1.0.0-rc.4, which is a release candidate version. Release candidates are pre-release versions that may contain unpatched vulnerabilities and are not recommended for production use. The latest stable version should be used instead. Fix: Update VitePress to the latest stable release (e.g., 1.0.0 or later). Run 'npm install vitepress@latest' and test thoroughly.
• Medium · Missing Security Headers in Documentation Site — docs/.vitepress/config.mts - VitePress configuration. The documentation site (built with VitePress) does not appear to have explicit security headers configuration visible. This could allow for XSS attacks, clickjacking, and other client-side vulnerabilities depending on deployment configuration. Fix: Add security headers configuration to the VitePress config file, including: Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, and X-XSS-Protection headers.
• Medium · Potential Secret Exposure in Kubernetes Manifests — helm-charts/hello-helm/templates/hellok8s-secret.yaml, secret/ directory. Multiple Kubernetes YAML files exist (hellok8s-secret.yaml in helm-charts and secret directory) that may contain sensitive data. If these contain actual secrets rather than template placeholders, they could be exposed in version control. Fix: Ensure all secrets are template-based with placeholders. Use Kubernetes secret management tools (sealed-secrets, external-secrets) or store sensitive values in .gitignored files. Never commit actual credentials.
• Medium · Insufficient Docker Image Security Practices — configmaps/Dockerfile, container/Dockerfile, deployment/liveness/Dockerfile, deployment/v2/Dockerfile, helm-charts/hello-helm/Dockerfile. Multiple Dockerfiles exist in the codebase without visible security best practices such as explicit base image versions, non-root user execution, or minimal base images. This could lead to supply chain attacks or privilege escalation. Fix: Implement Docker security best practices: (1) Use specific base image versions instead of 'latest' tags, (2) Run containers as non-root users, (3) Use minimal base images (alpine, distroless), (4) Scan images for vulnerabilities with tools like Trivy or Snyk, (5) Include HEALTHCHECK directives.
• Low · Missing HTTPS Enforcement in Ingress Configuration — ingress/ingress.yaml. The ingress configuration files (ingress/ingress.yaml) may not explicitly enforce HTTPS/TLS, which could allow man-in-the-middle attacks. Fix: Add TLS configuration to ingress manifests with proper certificates. Ensure redirect from HTTP to HTTPS and configure tls section with secretName pointing to valid TLS certificate secrets.
• Low · Missing Network Policy Configuration — Repository root - absence of NetworkPolicy files. No visible NetworkPolicy resources in the repository to control traffic between pods and services. This allows unrestricted pod-to-pod communication. Fix: Implement Kubernetes NetworkPolicies to restrict ingress/egress traffic between pods and services. Start with a deny-all default policy and selectively allow required communication.
• Low · Missing RBAC Configuration — Repository root - absence of RBAC manifests. No explicit Role, RoleBinding, or ServiceAccount configurations visible. Default service accounts may have excessive permissions. Fix: Implement proper RBAC with least-privilege access. Create specific ServiceAccounts, Roles, and RoleBindings for each component with minimal required permissions.

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.