TL;DR

Plattform-Dokumentation gehört ins Git-Repository, nicht ins Wiki. Mit MkDocs Material erstellst du eine durchsuchbare Docs-Site, generierst API-Referenzen automatisch aus CRDs und Helm Charts und hältst Architekturentscheidungen als ADRs nach. Dieser Guide zeigt das Setup und die Automatisierung.

Kubernetes-Dokumentation als Code

Confluence-Seiten, die seit 18 Monaten niemand aktualisiert hat. Google Docs mit dem Titel "K8s Setup FINAL v3 (2)". Runbooks, die auf einem Cluster basieren, den es nicht mehr gibt. Klingt bekannt? Documentation as Code löst das Problem, indem Dokumentation denselben Lifecycle wie Code durchläuft: versioniert, reviewt und automatisch deployt.

Tooling: MkDocs Material

MkDocs mit dem Material-Theme ist der De-facto-Standard für technische Dokumentation. Die Konfiguration ist minimal:

# mkdocs.yml
site_name: Platform Docs
site_description: Interne Kubernetes-Plattform-Dokumentation
theme:
  name: material
  language: de
  palette:
    - scheme: default
      primary: indigo
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy

plugins:
  - search:
      lang: de
  - awesome-pages
  - git-revision-date-localized:
      type: date
      fallback_to_build_date: true

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - attr_list
  - pymdownx.emoji

nav:
  - Home: index.md
  - Architektur:
    - Übersicht: architecture/overview.md
    - ADRs: architecture/adrs/
  - Runbooks:
    - Incident Response: runbooks/incident-response.md
    - Scaling: runbooks/scaling.md
  - API-Referenz: api-reference/

Installieren und lokal starten:

pip install mkdocs-material mkdocs-awesome-pages-plugin \
  mkdocs-git-revision-date-localized-plugin

mkdocs serve
# Docs unter http://localhost:8000

Das git-revision-date-Plugin zeigt automatisch an, wann eine Seite zuletzt geändert wurde. Veraltete Docs fallen sofort auf.

Docs-Struktur für Kubernetes-Plattformen

Eine bewährte Verzeichnisstruktur:

docs/
├── index.md                    # Landing Page
├── architecture/
│   ├── overview.md             # Cluster-Topologie, Netzwerk
│   ├── adrs/
│   │   ├── 001-container-runtime.md
│   │   ├── 002-ingress-controller.md
│   │   └── 003-gitops-tool.md
│   └── diagrams/               # Mermaid oder draw.io
├── runbooks/
│   ├── incident-response.md
│   ├── scaling.md
│   ├── certificate-renewal.md
│   └── _template.md            # Runbook-Vorlage
├── onboarding/
│   ├── developer-guide.md
│   └── namespace-request.md
├── api-reference/              # Auto-generiert
│   ├── crds.md
│   └── helm-values.md
└── decisions/
    └── runbook-template.md

Architecture Decision Records (ADRs)

Warum haben wir Cilium statt Calico gewählt? Warum ArgoCD statt Flux? ADRs dokumentieren diese Entscheidungen mit Kontext:

# ADR-002: Nginx Ingress Controller statt Traefik

## Status
Akzeptiert (2026-01-15)

## Kontext
Die Plattform braucht einen Ingress Controller für HTTP-Routing.
Evaluiert wurden: Nginx Ingress, Traefik, HAProxy, Emissary.

## Entscheidung
Wir verwenden den Nginx Ingress Controller (kubernetes/ingress-nginx).

## Begründung
- Breiteste Community-Unterstützung und Dokumentation
- Team hat Erfahrung mit Nginx-Konfiguration
- Annotations-basierte Konfiguration reicht für unsere Anforderungen
- ModSecurity-WAF-Integration möglich

## Konsequenzen
- Kein nativer TCP/UDP-Support (Workaround: ConfigMap)
- Kein Dashboard wie bei Traefik
- Upgrade-Prozess muss dokumentiert werden (Breaking Changes zwischen Majors)

ADRs werden nummeriert und nie gelöscht — nur der Status ändert sich (Vorgeschlagen, Akzeptiert, Abgelöst durch ADR-XXX).

Automatische Docs aus CRDs und Helm Charts

Manuell gepflegte API-Referenzen sind immer veraltet. Besser: Docs direkt aus dem Code generieren.

CRD-Dokumentation generieren

Das Tool crd-ref-docs erstellt Markdown aus CustomResourceDefinitions:

# crd-ref-docs installieren
go install github.com/elastic/crd-ref-docs@latest

# Docs aus CRDs generieren
crd-ref-docs \
  --source-path=./api/v1 \
  --config=docs/crd-ref-docs.yaml \
  --renderer=markdown \
  --output-path=docs/api-reference/crds.md

Helm Values dokumentieren

helm-docs generiert Dokumentation aus values.yaml-Kommentaren:

# values.yaml
# -- Anzahl der Replicas für das Deployment
# @default -- 3
replicaCount: 3

# -- Container-Image Repository
# @default -- nginx
image:
  # -- Image-Repository
  repository: nginx
  # -- Image-Tag (überschreibt appVersion)
  tag: "1.27"

# -- Resource Requests und Limits
resources:
  requests:
    # -- CPU-Request
    cpu: 100m
    # -- Memory-Request
    memory: 128Mi

# helm-docs installieren
go install github.com/norwoodj/helm-docs/cmd/helm-docs@latest

# Dokumentation generieren
helm-docs --chart-search-root=./charts \
  --output-file=../../docs/api-reference/helm-values.md

Die generierten Docs fließen automatisch in die MkDocs-Site ein.

Runbook-Template

Jedes Runbook folgt derselben Struktur, damit es im Incident schnell nutzbar ist:

# Runbook: [Titel]

## Symptome
- Alert: `KubePodCrashLooping`
- Betroffene Services: [Liste]

## Diagnose
1. Pod-Status prüfen:
   ```bash
   kubectl get pods -n <namespace> | grep -v Running

Events anzeigen:

kubectl describe pod <pod-name> -n <namespace>

Behebung

Option A: Restart

kubectl rollout restart deployment/<name> -n <namespace>

Option B: Rollback

kubectl rollout undo deployment/<name> -n <namespace>

Eskalation

L2: Platform Team (#platform-oncall)
L3: Cloud Provider Support

Nachbereitung

Post-Mortem erstellt
Monitoring angepasst
Runbook aktualisiert


## CI/CD: Docs automatisch bauen

Die Docs-Site wird bei jedem Merge nach `main` gebaut und deployt:

```yaml
# .github/workflows/docs.yml
name: Platform Docs
on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml', 'charts/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Für git-revision-date Plugin
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Generate CRD and Helm docs
        run: |
          go install github.com/norwoodj/helm-docs/cmd/helm-docs@latest
          helm-docs --chart-search-root=./charts \
            --output-file=../../docs/api-reference/helm-values.md

      - name: Build and deploy
        run: |
          pip install mkdocs-material mkdocs-awesome-pages-plugin \
            mkdocs-git-revision-date-localized-plugin
          mkdocs build
          # Deploy zu GitHub Pages, S3 oder internem Hosting

Ansatz	Vorteile	Nachteile
Confluence/Wiki	Bekannte UI, WYSIWYG	Keine Versionierung, veraltet schnell
Git + MkDocs	Versioniert, reviewbar, automatisierbar	Initiales Setup nötig
Notion/Google Docs	Einfach zu starten	Keine Code-Reviews, kein CI/CD

FAQ

Wie überzeuge ich mein Team, von Confluence zu Documentation as Code zu wechseln?

Zeige konkret, wie viele Confluence-Seiten veraltet sind. Der stärkste Argument ist die Integration in den Entwicklungs-Workflow: Docs werden im gleichen PR wie der Code geändert und durchlaufen Reviews.

Welches Tool ist besser — MkDocs oder Docusaurus?

MkDocs Material ist schneller einzurichten und hat ein ausgereiftes Plugin-Ökosystem. Docusaurus eignet sich besser, wenn du React-Komponenten in der Doku brauchst oder bereits ein React-Team hast. Für Plattform-Docs ist MkDocs die pragmatischere Wahl.

Wie halte ich Runbooks aktuell?

Verknüpfe Runbooks mit Alerts. Jeder Alert sollte einen Link zum Runbook enthalten. Nach jedem Incident wird das betroffene Runbook als Teil der Nachbereitung aktualisiert. Zusätzlich: quartalsweise Review aller Runbooks als Team-Aufgabe.

Können nicht-technische Stakeholder Documentation as Code nutzen?

Ja. MkDocs rendert Markdown zu einer normalen Website. Stakeholder lesen die gebaute Site im Browser. Für Änderungen können sie Markdown direkt in der GitHub-Web-UI bearbeiten und einen PR erstellen — ohne Git-Kenntnisse.

Wie gehe ich mit sensiblen Informationen in der Dokumentation um?

Secrets und Credentials gehören nie in die Dokumentation. Verweise stattdessen auf den Secret Manager (z.B. Vault, AWS Secrets Manager). Für interne Docs mit eingeschränktem Zugriff eignet sich ein privates Repository mit GitHub Pages hinter einem VPN oder SSO.

Nächster Schritt: Lege ein docs/-Verzeichnis in deinem Plattform-Repository an und starte mit einer MkDocs-Konfiguration und drei ADRs für eure wichtigsten Architekturentscheidungen.

Kubernetes-Expertise gesucht?

Managed Services, Beratung, Training oder Security – wir unterstützen deutsche Unternehmen bei allen Kubernetes-Themen.

Kontakt aufnehmen Kontakt aufnehmen

Documentation as Code für Kubernetes-Plattformen