docs: add Quick Navigation Map and YouTube Multimedia Series (masterclasses & shorts)

Author: inafev

README.md

@@ -70,8 +70,82 @@ axes:
 > (OpenShift-only). If you deploy on OpenShift *exclusively*, either works; this
 > repo generalises the same design to any distribution.
 
+<a id="quick-navigation-map"></a>
+## 🗺️ Quick Navigation Map
+
+This repository provides an enterprise, production-ready umbrella Helm chart that deploys the official **Traefik Ingress Controller (v3.7+)** with a **Keycloak-protected dashboard (oauth2-proxy + ForwardAuth)**, portable across **Red Hat OpenShift**, **Rancher RKE2**, **k3s**, **kubeadm**, and **VMware Tanzu**. Use this map to navigate the repository layout, architectural documentation, and multimedia series:
+
+### 🧭 Repository Architecture Blueprint
+```text
+traefik-keycloak-portable/                   # 🌐 Multi-Distribution Ingress & Keycloak SSO Platform
+├── 📁 argocd/                               # Declarative GitOps Multi-Source Delivery
+│   ├── 📁 apps/                             # ArgoCD Applications (traefik-keycloak)
+│   ├── 📄 project.yaml                      # AppProject scoping repos, namespaces, and cluster resources
+│   └── 📄 README.md                         # Multi-source $values GitOps pattern & runbooks
+├── 📁 docs/                                 # Architectural Deep Dives & Distribution Guides
+│   ├── 📄 air-gapped.md                     # Disconnected deployment, vendoring & image mirroring
+│   ├── 📄 external-secrets.md               # HashiCorp Vault ESO SecretStore & token sync
+│   ├── 📄 network-policies.md               # Calico & Cilium default-deny NetworkPolicies
+│   └── 📄 tls-secret.md                     # CA trust chains, cert-manager & TLS secret injection
+├── 📁 helm/                                 # Umbrella Helm Chart & Templates
+│   └── 📁 traefik-keycloak/                 # Portable umbrella chart (Chart v41.0.2 / Traefik v3.7.6)
+│       ├── 📁 charts/                       # Vendored official Traefik subchart (offline-ready)
+│       ├── 📁 templates/                    # Core oauth2-proxy, IngressRoute & _validate.tpl
+│       └── 📄 values.yaml                   # Base values & orthogonal feature flag defaults
+├── 📁 keycloak/                             # Identity Provider Configuration & Setup
+│   └── 📄 keycloak-client-setup.md          # OIDC client, mapper & traefik-admin role guide
+├── 📁 metallb/                              # Bare-Metal Layer 2 / BGP Load Balancing
+│   └── 📄 ipaddresspool.example.yaml        # On-prem IPAddressPool & L2Advertisement definition
+├── 📁 secrets/                              # Secret Synchronization Templates
+│   └── 📄 oauth2-proxy-secret.example.yaml  # Sealed/Vault secret reference for cookie & client secrets
+├── 📁 sites/                                # Distribution-Specific Values Overlays
+│   ├── 📄 values-openshift.yaml             # Red Hat OpenShift (restricted-v2 SCC, dynamic UIDs)
+│   ├── 📄 values-rke2.yaml                  # Rancher RKE2 (Cilium LB-IPAM, non-root)
+│   ├── 📄 values-k3s.yaml                   # Lightweight edge k3s (MetalLB, Traefik disabled)
+│   ├── 📄 values-kubeadm.yaml               # Bare-metal kubeadm (MetalLB, local CA ConfigMap)
+│   ├── 📄 values-tanzu-nsx.yaml             # VMware Tanzu / TKG with NSX ALB (Avi Vantage)
+│   └── 📄 values-tanzu-kubevip.yaml         # VMware Tanzu / TKG with kube-vip virtual IP
+├── 📄 CHANGELOG.md                          # Release history & version notes
+├── 📄 install.sh                            # Imperative deployment script with pre-flight linting
+└── 📄 PORTABILITY.md                        # Portability matrix across distros & load balancers
+```
+
+<a id="ai-multimedia-series"></a>
+## 🎬 AI-Generated Multimedia Series (YouTube)
+
+This repository is accompanied by an educational video masterclass series and technical shorts synthesized with **Gemini NotebookLM** based directly on the multi-distribution architecture, ForwardAuth security flows, and air-gapped runbooks from this project. All videos are freely accessible on YouTube on the [**@nubenetes**](https://youtube.com/@nubenetes) channel.
+
+> [!NOTE]
+> **Multilingual Learning Experience**:  
+> Content features sessions with original spoken audio in **English 🇺🇸**, with automated YouTube closed captions (CC) translated into **20+ languages** for global platform engineering and SRE teams.
+
+### 📽️ Full-Length Technical Deep Dives (Architecture Masterclasses)
+
+| # | Video Guide Title | Engineering Domain & Core Architecture | Audio | Duration | Direct Link |
+|:---:|:---|:---|:---:|:---:|:---:|
+| **01** | [Portable Traefik & Keycloak Helm Chart](https://www.youtube.com/watch?v=3OQhS25KbIk) | **Multi-Distro Architecture & Feature Flags**<br/>Orthogonal axes, fail-fast validation in `_validate.tpl`, vendored offline charts | 🇺🇸 EN | `9:26` | [▶️ Watch](https://www.youtube.com/watch?v=3OQhS25KbIk) |
+| **02** | [Multi-Distro Kubernetes Portability](https://www.youtube.com/watch?v=8w0-SJw0jLo) | **Platform Engineering & Distro Quirks**<br/>OpenShift restricted-v2 SCC vs vanilla K8s, dynamic UIDs & CNI NetworkPolicies | 🇺🇸 EN | `9:26` | [▶️ Watch](https://www.youtube.com/watch?v=8w0-SJw0jLo) |
+| **03** | [Traefik & Keycloak OIDC Authentication](https://www.youtube.com/watch?v=X4GdtkJrbZo) | **Zero-Trust Ingress & ForwardAuth**<br/>oauth2-proxy token exchange, statusRewrites 401 to 302, role RBAC (`traefik-admin`) | 🇺🇸 EN | `7:04` | [▶️ Watch](https://www.youtube.com/watch?v=X4GdtkJrbZo) |
+| **04** | [Portable Kubernetes Networking](https://www.youtube.com/watch?v=Hb4K81jiGrA) | **On-Premises LoadBalancer Backends**<br/>MetalLB (L2/BGP), VMware NSX ALB (Avi), kube-vip virtual IP & Cilium LB-IPAM | 🇺🇸 EN | `7:52` | [▶️ Watch](https://www.youtube.com/watch?v=Hb4K81jiGrA) |
+| **05** | [End-to-End Portable Traefik & Keycloak](https://www.youtube.com/watch?v=1AfsoppwT_w) | **Air-Gapped GitOps Masterclass**<br/>Full Day 0 to Day 2 lifecycle, HashiCorp Vault ESO sync, multi-source ArgoCD | 🇺🇸 EN | `9:46` | [▶️ Watch](https://www.youtube.com/watch?v=1AfsoppwT_w) |
+
+### ⚡ Video Shorts Matrix
+
+| # | Short Title | Architectural Domain & Focus | Audio | Duration | Action |
+|:---:|:---|:---|:---:|:---:|:---:|
+| **01** | [The Ultimate Portable Traefik & Keycloak Helm Chart](https://www.youtube.com/shorts/murHHpH8WHE) | **Unified Ingress & OIDC**<br/>Zero forks, ForwardAuth middleware, status 401 to 302 rewrite & role-gating | 🇺🇸 EN | `1:30` | [▶️ Watch](https://www.youtube.com/shorts/murHHpH8WHE) |
+| **02** | [How Air-Gapped Kubernetes Clusters Install Ingress](https://www.youtube.com/shorts/LGdVhOyaVaI) | **Air-Gapped Architecture**<br/>Vendored Helm dependencies & internal OCI mirrors for disconnected datacenters | 🇺🇸 EN | `1:03` | [▶️ Watch](https://www.youtube.com/shorts/LGdVhOyaVaI) |
+| **03** | [How External Secrets Operator Connects Vault](https://www.youtube.com/shorts/BUwUb6vpbqs) | **Zero-Trust Secret Sync**<br/>Bridging HashiCorp Vault into Kubernetes secrets without committing passwords | 🇺🇸 EN | `1:02` | [▶️ Watch](https://www.youtube.com/shorts/BUwUb6vpbqs) |
+| **04** | [Why OpenShift SCC Breaks Standard Pods](https://www.youtube.com/shorts/Cv5jakkIseE) | **OpenShift Hardening**<br/>restricted-v2 dynamic UID ranges vs hardcoded non-root UIDs (65532) | 🇺🇸 EN | `1:20` | [▶️ Watch](https://www.youtube.com/shorts/Cv5jakkIseE) |
+
+*For complete technical summaries, topic breakdowns, and direct studio links, see [Section 18: Video Walkthroughs & Architecture References](#18-video-walkthroughs--architecture-references-youtube).*
+
+---
+
 ## Table of contents
 
+- [Quick Navigation Map](#quick-navigation-map)
+- [AI-Generated Multimedia Series (YouTube)](#ai-multimedia-series)
 1. [Architecture](#1-architecture)
 2. [How portability works (orthogonal axes)](#2-how-portability-works-orthogonal-axes)
 3. [Deployment topology](#3-deployment-topology)
@@ -89,6 +163,7 @@ axes:
 15. [Operations & troubleshooting](#15-operations--troubleshooting)
 16. [GitOps with ArgoCD](#16-gitops-with-argocd)
 17. [Contributing & license](#17-contributing--license)
+18. [Video Walkthroughs & Architecture References (YouTube)](#18-video-walkthroughs--architecture-references-youtube)
 
 ---
 
@@ -661,3 +736,116 @@ Licensed under the [MIT License](LICENSE).
 
 > **Status:** untested on a live cluster — all validation is `helm lint` /
 > `helm template` / kubeconform / mermaid parsing, not runtime.
+
+---
+
+## 18. Video Walkthroughs & Architecture References (YouTube)
+
+Architectural deep dives, video walkthroughs, and technical shorts for `traefik-keycloak-portable`, multi-distribution Kubernetes deployments, Traefik Ingress, and Keycloak SSO are hosted on the **[Nubenetes YouTube Channel (@nubenetes)](https://www.youtube.com/@nubenetes)**.
+
+<details open>
+<summary>📂 <strong>Full-Length Technical Deep Dives (Architecture Masterclasses)</strong></summary>
+
+<br/>
+
+##### 1. Portable Traefik & Keycloak Helm Chart: Multi-Distro Kubernetes Architecture
+- 🔗 **Direct Link**: [https://www.youtube.com/watch?v=3OQhS25KbIk](https://www.youtube.com/watch?v=3OQhS25KbIk)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 9:26
+- 🏷️ **Engineering Domain**: Multi-Distribution Architecture, Orthogonal Feature Flags & Helm Design
+- 📝 **Technical Overview**:
+Detailed exploration of a single, highly portable umbrella Helm chart deploying Traefik v3 and a Keycloak-protected dashboard across OpenShift, RKE2, k3s, kubeadm, and VMware Tanzu. Explains why a single core with orthogonal feature flags outperforms per-distribution forks, how `_validate.tpl` catches invalid configurations during `helm template` rendering, and how vendored subcharts enable true air-gapped deployments.
+- 🛠️ **Direct Links**: [Watch on YouTube](https://www.youtube.com/watch?v=3OQhS25KbIk) | [Edit in YouTube Studio](https://studio.youtube.com/video/3OQhS25KbIk/edit)
+
+##### 2. Multi-Distro Kubernetes Portability: OpenShift, RKE2, K3s, Kubeadm & Tanzu
+- 🔗 **Direct Link**: [https://www.youtube.com/watch?v=8w0-SJw0jLo](https://www.youtube.com/watch?v=8w0-SJw0jLo)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 9:26
+- 🏷️ **Engineering Domain**: Platform Engineering, Distribution Quirks & Security Hardening
+- 📝 **Technical Overview**:
+Architectural analysis of multi-distribution Kubernetes portability. Explores how platform-specific security models—specifically Red Hat OpenShift's `restricted-v2` SecurityContextConstraints rejecting hardcoded UIDs like 65532—differ from standard Kubernetes PodSecurityStandards. Demonstrates how the portable chart adapts UID allocation dynamically, configures CNI NetworkPolicies for Calico and Cilium, and eliminates environment drift.
+- 🛠️ **Direct Links**: [Watch on YouTube](https://www.youtube.com/watch?v=8w0-SJw0jLo) | [Edit in YouTube Studio](https://studio.youtube.com/video/8w0-SJw0jLo/edit)
+
+##### 3. Traefik & Keycloak OIDC Authentication: ForwardAuth & Role RBAC Masterclass
+- 🔗 **Direct Link**: [https://www.youtube.com/watch?v=X4GdtkJrbZo](https://www.youtube.com/watch?v=X4GdtkJrbZo)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 7:04
+- 🏷️ **Engineering Domain**: Zero-Trust Ingress, Keycloak OIDC, oauth2-proxy & ForwardAuth Middleware
+- 📝 **Technical Overview**:
+Comprehensive guide to securing the internal Traefik dashboard with OpenID Connect when Traefik OSS lacks native OIDC. Details the exact mechanics of `oauth2-proxy`, Traefik's `ForwardAuth` middleware (`/oauth2/auth`), the Traefik v3.4+ `errors` middleware status rewrite (`statusRewrites: "401": 302`), and enforcing strict role-based access control with `traefik-dashboard:traefik-admin`.
+- 🛠️ **Direct Links**: [Watch on YouTube](https://www.youtube.com/watch?v=X4GdtkJrbZo) | [Edit in YouTube Studio](https://studio.youtube.com/video/X4GdtkJrbZo/edit)
+
+##### 4. Portable Kubernetes Networking: MetalLB, NSX ALB, Kube-Vip & Cilium LB-IPAM
+- 🔗 **Direct Link**: [https://www.youtube.com/watch?v=Hb4K81jiGrA](https://www.youtube.com/watch?v=Hb4K81jiGrA)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 7:52
+- 🏷️ **Engineering Domain**: On-Premises Load Balancing, Ingress Networking & CNI Isolation
+- 📝 **Technical Overview**:
+Deep dive into decoupling Kubernetes ingress networking from specific cloud providers. Compares on-premises LoadBalancer backends supported by the chart: MetalLB (Layer 2 ARP and BGP pools), VMware NSX Advanced Load Balancer (Avi Vantage with AKO), kube-vip virtual IP failover, and modern eBPF-native Cilium LB-IPAM. Also reviews ingress NetworkPolicy hardening for zero-trust datacenters.
+- 🛠️ **Direct Links**: [Watch on YouTube](https://www.youtube.com/watch?v=Hb4K81jiGrA) | [Edit in YouTube Studio](https://studio.youtube.com/video/Hb4K81jiGrA/edit)
+
+##### 5. End-to-End Portable Traefik & Keycloak: Air-Gapped GitOps Masterclass
+- 🔗 **Direct Link**: [https://www.youtube.com/watch?v=1AfsoppwT_w](https://www.youtube.com/watch?v=1AfsoppwT_w)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 9:46
+- 🏷️ **Engineering Domain**: End-to-End Production Lifecycle, Air-Gapped GitOps & Secrets Management
+- 📝 **Technical Overview**:
+The complete production walkthrough covering Day 0 setup through Day 2 operations. Explains disconnected air-gapped image mirroring and chart vendoring, synchronizing secrets and private CA certificates from HashiCorp Vault via External Secrets Operator, declarative multi-source GitOps delivery with ArgoCD, and zero-downtime Helm upgrades.
+- 🛠️ **Direct Links**: [Watch on YouTube](https://www.youtube.com/watch?v=1AfsoppwT_w) | [Edit in YouTube Studio](https://studio.youtube.com/video/1AfsoppwT_w/edit)
+
+</details>
+
+<details open>
+<summary>📂 <strong>Technical Shorts Matrix & Architecture Breakdowns</strong></summary>
+
+<br/>
+
+### ⚡ Video Shorts Matrix
+
+| # | Short Title | Architectural Domain & Focus | Audio | Duration | Action |
+|:---:|:---|:---|:---:|:---:|:---:|
+| **01** | [The Ultimate Portable Traefik & Keycloak Helm Chart](https://www.youtube.com/shorts/murHHpH8WHE) | **Unified Ingress & OIDC**<br/>Zero forks, ForwardAuth middleware, status 401 to 302 rewrite & role-gating | 🇺🇸 EN | `1:30` | [▶️ Watch](https://www.youtube.com/shorts/murHHpH8WHE) |
+| **02** | [How Air-Gapped Kubernetes Clusters Install Ingress](https://www.youtube.com/shorts/LGdVhOyaVaI) | **Air-Gapped Architecture**<br/>Vendored Helm dependencies & internal OCI mirrors for disconnected datacenters | 🇺🇸 EN | `1:03` | [▶️ Watch](https://www.youtube.com/shorts/LGdVhOyaVaI) |
+| **03** | [How External Secrets Operator Connects Vault](https://www.youtube.com/shorts/BUwUb6vpbqs) | **Zero-Trust Secret Sync**<br/>Bridging HashiCorp Vault into Kubernetes secrets without committing passwords | 🇺🇸 EN | `1:02` | [▶️ Watch](https://www.youtube.com/shorts/BUwUb6vpbqs) |
+| **04** | [Why OpenShift SCC Breaks Standard Pods](https://www.youtube.com/shorts/Cv5jakkIseE) | **OpenShift Hardening**<br/>restricted-v2 dynamic UID ranges vs hardcoded non-root UIDs (65532) | 🇺🇸 EN | `1:20` | [▶️ Watch](https://www.youtube.com/shorts/Cv5jakkIseE) |
+
+<br/>
+
+##### 1. The Ultimate Portable Traefik & Keycloak Helm Chart Explained
+- 🔗 **Direct Link**: [https://www.youtube.com/shorts/murHHpH8WHE](https://www.youtube.com/shorts/murHHpH8WHE)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 1:30
+- 🏷️ **Engineering Domain**: Unified Ingress, OIDC Authentication & Helm Architecture
+- 📝 **Technical Overview**:
+Why managing separate Helm chart forks per distribution is an anti-pattern. Demonstrates how a single portable chart handles Traefik ingress and Keycloak dashboard protection across any Kubernetes cluster, using oauth2-proxy, ForwardAuth, status 401 to 302 redirect rewriting, and role-based gating.
+- 🛠️ **Direct Links**: [Watch Short](https://www.youtube.com/shorts/murHHpH8WHE) | [Edit in YouTube Studio](https://studio.youtube.com/video/murHHpH8WHE/edit)
+
+##### 2. How Air-Gapped Kubernetes Clusters Install Ingress & Helm Charts
+- 🔗 **Direct Link**: [https://www.youtube.com/shorts/LGdVhOyaVaI](https://www.youtube.com/shorts/LGdVhOyaVaI)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 1:03
+- 🏷️ **Engineering Domain**: Air-Gapped Kubernetes, Disconnected Mirroring & Offline Charts
+- 📝 **Technical Overview**:
+How to deploy ingress controllers and complex microservices in strictly isolated datacenters with zero internet egress. Explains storing vendored Helm charts in Git and redirecting image repositories to internal OCI registries.
+- 🛠️ **Direct Links**: [Watch Short](https://www.youtube.com/shorts/LGdVhOyaVaI) | [Edit in YouTube Studio](https://studio.youtube.com/video/LGdVhOyaVaI/edit)
+
+##### 3. How External Secrets Operator Connects HashiCorp Vault to Kubernetes
+- 🔗 **Direct Link**: [https://www.youtube.com/shorts/BUwUb6vpbqs](https://www.youtube.com/shorts/BUwUb6vpbqs)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 1:02
+- 🏷️ **Engineering Domain**: Zero-Trust Secret Management, External Secrets Operator & Vault
+- 📝 **Technical Overview**:
+Eliminating plaintext secrets from Git repositories. Shows how External Secrets Operator continuously polls HashiCorp Vault to synchronize client secrets, cookie encryption keys, and internal TLS certs into standard Kubernetes Secrets.
+- 🛠️ **Direct Links**: [Watch Short](https://www.youtube.com/shorts/BUwUb6vpbqs) | [Edit in YouTube Studio](https://studio.youtube.com/video/BUwUb6vpbqs/edit)
+
+##### 4. Why OpenShift Security Context Constraints Break Standard Kubernetes Pods
+- 🔗 **Direct Link**: [https://www.youtube.com/shorts/Cv5jakkIseE](https://www.youtube.com/shorts/Cv5jakkIseE)
+- 🌐 **Origin Language**: English 🇺🇸 (Subtitles in 20+ languages)
+- ⏱️ **Duration**: 1:20
+- 🏷️ **Engineering Domain**: OpenShift Security, restricted-v2 SCC & Dynamic UID Ranges
+- 📝 **Technical Overview**:
+Why pods that run fine on k3s or kubeadm get blocked on Red Hat OpenShift. Explains how OpenShift's `restricted-v2` SCC allocates dynamic UIDs and why hardcoding `runAsUser: 65532` causes admission failures, plus how the portable chart adapts seamlessly.
+- 🛠️ **Direct Links**: [Watch Short](https://www.youtube.com/shorts/Cv5jakkIseE) | [Edit in YouTube Studio](https://studio.youtube.com/video/Cv5jakkIseE/edit)
+
+</details>
+