RHELS LAB
Contents · the agent book

Start here

  1. RHELS Lab — Agent Docs
  2. Service Directory
  3. Lab Overview

Planes

  1. Tooling Plane — the Mac mini cluster
  2. Workload Cluster — CRC / OpenShift
  3. Networking

Tool pages

  1. OpenLDAP — Identity & Access
  2. Vault & Secrets Delivery
  3. Certificates — cert-manager & Let's Encrypt
  4. Tailscale & Cloudflare — the name layer
  5. Agent onboarding — how an agent joins the team
  6. Argo CD — GitOps on both planes
  7. Harbor — container registry
  8. Grafana — dashboards & Explore
  9. Logging pipeline — Vector, Loki, Logstash
  10. Prometheus & Alertmanager — metrics and alerts
  11. GitHub Actions — self-hosted runners
  12. ServiceNow PDI & the MCP servers
  13. StackRox — security platform on pro
  14. This documentation system
  15. Namespace as a Service — the MCP front door
  16. Vault PKI

Operations

  1. CI/CD
  2. Observability — deep dive
  3. Disaster Recovery & Rebuild
  4. SRE: IaC, DR, Upgrades, SLO/SLA
  5. Runbooks
  6. The Agent-Run Lab — A Working Showcase

QA Use Cases

  1. QA Use Cases — how this section works
  2. QA — Vault
  3. QA — Argo CD
  4. QA — Identity (OpenLDAP + Dex)
  5. QA — Grafana, Prometheus, Alertmanager
  6. QA — Logging (Loki, Tempo, Logstash)
  7. QA — ACS (StackRox)
  8. QA — Kyverno
  9. QA — MCP server (Namespace as a Service)
  10. QA — CI runners (ARC)
  11. QA — Front door (ingress, cert-manager, Tailscale operator)
  12. QA — Alert bridge
  13. QA — ServiceNow PDI, sims, group-sync
  14. QA — Lab docs
  15. QA — CRC / OpenShift

Reference

  1. Glossary
  2. Agent Protocol

Agent book · Tool pages

This documentation system

You are reading the output of this system. Since 2026-10-24 it is one site with one theme: the Astro showcase and this agent book are built together from rhels/lab-docs-source and served by one image at the docs front door — the showcase at /, this book at /agent-docs/. Before that date the book was a separate MkDocs build with a mismatched theme; MkDocs is retired (see “History” below) and there is exactly one source of truth for book content: the markdown in the Astro content collection.

Part A — How it is set up

  • Source layout (rhels/lab-docs-source):
    • site/ — the Astro site. Showcase pages are hand-written .astro pages; the book is a content collection: site/src/content/docs/**/*.md, one file per page, with frontmatter (title, section, order, summary).
    • A dynamic route renders every collection entry at /agent-docs/<path>/ inside the site’s own Layout — same header, sidebar, and stylesheet as the cover. The collection’s index.md renders at /agent-docs/ itself.
    • llms.txt and inventory.json under /agent-docs/ are generated at build time from the same collection and the inventory snapshot — they are endpoints, not files, so they can never drift from the pages.
    • Inter-page links in the markdown are written as content-root-relative .md paths (e.g. [vault.md](vault.md), [tools/harbor.md](tools/harbor.md)); a remark step in the Astro config rewrites them to site URLs at build time.
    • inventory/ — the inventory generator + the sanitization audit (audit-bundle.py).
  • The gates (CI, build-deploy.yml, on the mini-k8s runners): gitleaks on source → regenerate inventory → Astro build → gitleaks on the bundle → audit-bundle.py on the bundle. The audit forbids IPs, tailnet/hostname-like suffixes, emails, key material, and token-shaped strings in anything served — including these pages.
  • The publish loop (2026-11-01): automated pipeline via workflow_dispatch with DOCS_PUBLISH_ENABLED → build/audit → push harbor.rhels.com/library/lab-docs:<tag> → workflow pins the full Harbor reference in GitOps → Argo CD rolls tooling-lab-docs. Verify the published publish-marker.txt records the intended source_sha. The mini-host lab-docs-image-sync ferry cron is retired; scripts/build-image.sh is a manual fallback only. Sources: lab-monorepo#99, docs PR #31, GitOps PR #126.
  • Not published: the public GitHub Pages path stays gated off (private repo, Free-plan org, Pages disabled — the would-be URL returns 404). The deploy job exists but runs only on manual dispatch with a repo variable set, which nobody has set. See cicd.md.

History

  • Until 2026-10-24: the book was MkDocs Material (agent-docs/), copied into the image as a second bundle. It rendered in a different theme from the showcase, which is why the owner ordered the migration. The MkDocs tree, its config, and its CI steps were removed in the same change that introduced the content collection; the markdown moved with git mv, so page history is preserved. Nothing consumes MkDocs output anymore.

Part B — How to use it

  • Edit a page: edit the .md file in site/src/content/docs/ (tool pages live in tools/). Keep the frontmatter intact. Follow the sanitization boundary as you write — names of the lab’s own services and rhels.com front doors are fine; IPs, tailnet names, emails, credential values, and real password hashes are forbidden and the audit will fail the build on them.
  • Add a page: create the .md with frontmatter (title, section, order, summary). It joins the book’s table of contents and the generated llms.txt automatically — there is no nav file to edit. Link to it from the book index’s tool matrix if it is a tool page.
  • Structure rule for tool pages: Part A how it is set up (deployment, GitOps source, the mechanics that surprise people), then Part B how to use it (the handful of tasks a reader actually performs). Facts are dated when they are observations rather than design.
  • Preview: from site/, npm run dev for the dev server, or npm run build and inspect dist/ — the build the CI runs is the same one. (The lab image build uses ASTRO_BASE=/; a bare local build defaults to the Pages base path, which only changes link prefixes.)
  • Publish (2026-11-01, lab-monorepo#99): commit + push → dispatch the workflow with DOCS_PUBLISH_ENABLED enabled → confirm build/audit and Harbor push succeed → confirm the workflow pins the full harbor.rhels.com/library/lab-docs:<tag> reference in GitOps → confirm tooling-lab-docs is Synced/Healthy → fetch publish-marker.txt and compare source_sha with the intended source revision → fetch each changed page and verify its content. Use scripts/build-image.sh only as a manual fallback.