Voraussetzungen prüfen

Diese Seite beginnt mit einem vorhandenen, passend dimensionierten Kubernetes-Cluster. Bevor das Inventory erstellt wird, müssen dessen technische Eigenschaften sowie alle externen Zugänge und Werkzeuge feststehen.

Anforderungen an Kubernetes

Die folgenden vier Bereiche werden vor der Inventory-Konfiguration gemeinsam mit dem Clusterbetreiber abgenommen.

Basisdienst

Kubernetes

API, Worker-Kapazität und administrativer Zugang bilden die technische Grundlage.

Empfehlung

Für Produktion einen Managed- oder etablierten internen Cluster mit eigenem Deployment-Zugang verwenden.

1. Clusterzugang und Berechtigungen

Die Deployment-Umgebung benötigt eine Kubeconfig, deren Context eindeutig auf den vorgesehenen Zielcluster zeigt. Die Kubernetes-API muss von dieser Umgebung erreichbar sein. Vorhanden sein müssen:

• eine lesbare Kubeconfig unter $HOME/.kube/<kubeconfig_file>
• der später in inv_k8s.config.context eingetragene Context
• ausreichende Rechte für die clusterweiten Ressourcen der Erstinstallation

Eine Kubeconfig, die nur einen einzelnen Namespace verwalten darf, reicht für das Standardprofil nicht aus.

Die vollständige Erstinstallation erzeugt Namespaces, CustomResourceDefinitions, Operatoren, ClusterRoles, StatefulSets, PersistentVolumeClaims, Ingress- und Zertifikatsressourcen. Eingeschränkte Berechtigungen müssen deshalb vorab gemeinsam mit dem Clusterbetreiber bewertet und in Staging getestet werden.

Basisdienst

Ingress Controller

IngressClass und Load Balancer machen die späteren Plattformdienste erreichbar.

Empfehlung

Die native LoadBalancer-Integration und den vom Kubernetes-Anbieter unterstützten Ingress Controller nutzen.

2. Ingress und externe Adresse

Im Cluster muss bereits ein funktionierender Ingress Controller vorhanden sein. Dessen IngressClass wird später über inv_k8s.ingress_class referenziert.

Der zugehörige Load Balancer benötigt eine externe IP-Adresse oder einen erreichbaren Hostnamen für Port 80 und 443. Diese Adresse ist das Ziel der DNS-Einträge für die Plattform- und Mandantendomains.

Basisdienst

Persistenter Storage

Dynamische RWO-Volumes speichern Daten zustandsbehafteter Plattformdienste.

Empfehlung

CSI-basierten, replizierten Block-Storage einsetzen und eine Retain-Strategie festlegen.

3. Persistenter Speicher

Die UDSP verwendet zustandsbehaftete Dienste wie PostgreSQL, Stellio, FROST, MinIO, Prometheus und Loki. Deshalb muss der Cluster dynamisch persistente Volumes bereitstellen können.

Im Inventory werden zwei ReadWriteOnce-Verwendungen unterschieden:

• inv_k8s.storage_class.rwo für reguläre persistente Volumes
• inv_k8s.storage_class.rwo_retain für Daten, die bei Entfernung einer Workload nicht automatisch gelöscht werden sollen

Beide Werte dürfen auf dieselbe StorageClass zeigen, wenn deren Reclaim Policy bewusst geprüft wurde. Das Playbook kontrolliert beide Namen zu Beginn und stoppt, wenn eine konfigurierte StorageClass fehlt.

Basisdienst

Netzwerkzugriff

Cluster und Deployment-Umgebung müssen alle benötigten Artefaktquellen erreichen.

Empfehlung

Freigaben, Proxyregeln und interne Ausnahmen vor dem ersten Rollout praktisch testen.

4. Ausgehende Erreichbarkeit

Cluster und Deployment-Umgebung müssen Helm-Repositories, öffentliche oder private Container-Registries, kundenspezifische Git-Repositories und die eingesetzte Zertifizierungsstelle erreichen.

In abgeschotteten Umgebungen müssen Registry-Mirrors, HTTP-/HTTPS-Proxys und no_proxy-Ausnahmen vorab festgelegt werden. Die Clusterknoten benötigen außerdem eine zuverlässige Zeitsynchronisation, damit Zertifikate, Tokens und verteilte Datenbanken korrekt funktionieren.

DNS und TLS

Vor der Installation muss feststehen, unter welchen Domains die Plattform und ihre Mandanten erreichbar sein sollen. Für die Infrastrukturplanung sind zwei Fälle relevant. Die konkrete Zertifikats- und Issuer-Konfiguration erfolgt später im Inventory.

1. Standardfall: gemeinsame Plattformdomain

Für eine Installation unter platform.example.org ist ein Wildcard-DNS-Eintrag der einfachste Weg:

*.platform.example.org  →  <IP oder Hostname des Ingress-Controllers>

Dieser Eintrag deckt die Subdomains der aktivierten Plattformdienste ab. Dazu gehören beispielsweise:

• idm.<domain> und api.<domain>
• grafana.<domain> und monitoring.<domain>
• minio.<domain> und s3-minio.<domain>
• frost.<domain>, pgadmin.<domain>, superset.<domain> oder ckan.<domain>

Nur die Hostnamen aktivierter Komponenten müssen erreichbar sein. Der Ingress-Endpunkt muss über Port 80 und 443 aus dem vorgesehenen Zugriffsnetz erreichbar sein.

2. Separate Mandantendomain

Verwendet ein Mandant eine abweichende tenant_domain, muss auch diese Domain auf den vorgesehenen Ingress-Endpunkt zeigen.

*.daten.stadt-a.example  →  <Ingress-Endpunkt>
*.daten.stadt-b.example  →  <Ingress-Endpunkt>

Die Plattformdomain und jede separate Mandantendomain müssen vor dem jeweiligen Rollout eingerichtet sein. Prüfen Sie die Auflösung sowohl aus der Deployment-Umgebung als auch aus dem später vorgesehenen Zugriffsnetz.

Externe Dienste und Zugänge

Prüfen Sie anhand der aktivierten Komponenten, welche der folgenden Zugänge Ihre Installation tatsächlich benötigt. Lassen Sie die betreffenden Endpunkte und Netzwerkfreigaben einrichten, beschaffen Sie die notwendigen technischen Zugangsdaten und testen Sie die Erreichbarkeit aus der Deployment-Umgebung beziehungsweise aus dem Cluster.

Abhängig vom Zielbild

Nicht jeder externe Dienst ist für jede Installation erforderlich

Entscheidend sind die aktivierten Funktionen und die Netzwerkumgebung. Die Karten zeigen, wann ein Zugang benötigt wird und was dann vor dem Rollout vorliegen muss.

Kommunikation

SMTP-Zugang

Ermöglicht Einladungen, Passwort-Reset und Systemmails aus Keycloak und aktivierten Anwendungen.

• Realer Dienst nur bei E-Mail-Funktionen

Dann vorbereiten

• Server und Port
• Absenderadresse
• Benutzer und Passwort

Artefakte & Quellcode

Registry- und Git-Zugriff

Ansible und Kubernetes laden darüber Charts, Container-Images und gegebenenfalls kundenspezifische Ressourcen.

• Für jedes Deployment

Dann vorbereiten

• Netzzugriff auf benötigte Registries
• Deploy Token nur für private Images
• Git-Zugang nur für kundenspezifische Repositories

Externe Persistenz

S3-Backend

Lagert Kubernetes-Backups, Datenbank-Backups oder langfristige Monitoring-Daten außerhalb des Plattformclusters ab.

• Mit Velero, Thanos oder logischen PostgreSQL-Backups

Dann vorbereiten

• S3-Endpunkt und Bucket
• Access Key und Secret
• Erreichbarkeit aus dem Cluster

Netzwerk & Vertrauen

Proxy und PKI

Ermöglicht ausgehende Zugriffe über einen Proxy und schafft Vertrauen zu Zertifikaten einer internen PKI.

• Nur in eingeschränkten Netzen

Dann vorbereiten

• HTTP-/HTTPS-Proxy
• Vollständige no_proxy-Ausnahmen
• Root-CA nur bei Unternehmens-PKI

Ein S3-Backend wird in drei voneinander unabhängigen Fällen benötigt: für Velero, für eine aktivierte Thanos-Langzeitablage oder für logische Backups der durch den PostgreSQL-Operator verwalteten Datenbanken. Planen Sie dafür getrennte Buckets und technische Konten, wenn Sicherungs- und Aufbewahrungsgrenzen voneinander unabhängig bleiben sollen.

Der reale SMTP-Dienst ist dagegen nur erforderlich, wenn E-Mail-Funktionen verwendet werden. Der Block inv_email bleibt im aktuellen Inventory trotzdem strukturell erforderlich, weil das Playbook seine Felder zu Beginn einliest. Die konkrete Entscheidung zwischen neutralen Platzhaltern und produktiven SMTP-Zugangsdaten wird unter Plattformbasis konfigurieren umgesetzt.

Ergebnis für das Plattformteam

Für jeden benötigten Dienst liegen ein erreichbarer Endpunkt, die zuständige Kontaktperson und sicher übergebene Zugangsdaten vor. Diese Werte werden anschließend unter inv_email, inv_registry, den Backup-Einstellungen oder den Proxyvariablen in das Inventory übernommen.

Deployment-Umgebung

Einmal je Deployment-Umgebung einrichten

Von Linux zur einsatzbereiten Deployment-Umgebung

Sie ist kein Kubernetes-Knoten. In ihr liegen Release, Inventory und Kubeconfig; von hier wird das Ansible-Playbook gegen den Zielcluster ausgeführt.

01

Linux vorbereiten

Systempakete und einen dedizierten Deployment-Benutzer einrichten.

Arbeitsfähige Umgebung

→

02

Code beziehen

Das Repository vom offiziellen Standardbranch klonen.

Plattformcode liegt lokal vor

→

03

Python isolieren

Virtuelle Umgebung für Ansible und Python-Module erstellen.

Isolierte Werkzeugkette

→

04

Clients installieren

kubectl, Helm und die benötigten Ansible Collections bereitstellen.

Vollständige CLI-Umgebung

→

05

Zugang prüfen

Kubeconfig ablegen und Context sowie Clusterzugriff testen.

Bereit für das Inventory

Die folgenden Befehle zeigen die Einrichtung auf einem aktuellen Debian- oder Ubuntu-System. Verwenden Sie einen dedizierten Benutzer und führen Sie die späteren Ansible-Aufrufe nicht als root aus. Alle weiteren Befehle werden aus dem Wurzelverzeichnis des core-platform-Repository ausgeführt.

1. Systempakete installieren

sudo apt-get update
sudo apt-get install -y \
  git curl openssl openssh-client sshpass pwgen \
  python3 python3-venv python3-pip python3-dev \
  gcc libpq-dev

Der Rechner benötigt ausgehenden HTTPS-Zugriff auf das GitLab-Repository, die konfigurierten Helm-Repositories und die benötigten Container-Registries. Außerdem muss die Kubernetes-API des Zielclusters erreichbar sein.

2. Offiziellen Plattformstand beziehen

git clone https://gitlab.com/urban-dataspace-platform/core-platform.git
cd core-platform

Damit liegt der offizielle Plattformcode lokal vor. Weitere Git-Befehle sind für die Einrichtung der Deployment-Umgebung nicht erforderlich.

Für einen produktiven Rollout sollte der tatsächlich geprüfte Stand zusätzlich dokumentiert werden. Der folgende Befehl gibt dessen eindeutige Commit-ID aus:

git rev-parse HEAD

Die Commit-ID ist kein Installationsschritt. Sie dient ausschließlich dazu, später nachvollziehen zu können, welcher Quellstand in Staging geprüft und in Produktion verwendet wurde.

3. Python-Umgebung erstellen

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip setuptools wheel
python -m pip install \
  "ansible-core>=2.13,<2.14" \
  "openshift==0.12.1" \
  "kubernetes==12.0.1" \
  "docker>=5.0" \
  "pymongo==3.12.1" \
  jmespath \
  psycopg2-binary

Die virtuelle Umgebung muss in jedem neuen Terminal aktiviert werden:

cd <pfad-zum-core-platform-repository>
source .venv/bin/activate

Python-Interpreter im Inventory

Die Release-Vorlage verwendet für localhost noch /usr/bin/python3. Bei einer virtuellen Umgebung muss der Controller stattdessen denselben Interpreter wie das Playbook verwenden:

controller:
  hosts:
    localhost:
      ansible_host: 127.0.0.1
      ansible_connection: local
      ansible_python_interpreter: "{{ ansible_playbook_python }}"

Andernfalls findet ein Ansible-Modul möglicherweise die in .venv installierten Python-Pakete nicht.

4. Ansible Collections installieren

ansible-galaxy collection install -r requirements.yml

Damit werden die vom Plattformstand genannten Collections installiert, darunter kubernetes.core, community.general, community.grafana, community.postgresql und community.mongodb.

5. kubectl und Helm bereitstellen

Installieren Sie kubectl in einer Version, die höchstens eine Minor-Version vom Kubernetes-Control-Plane abweicht. Die gewünschte Version muss deshalb mit dem Clusterbetreiber festgelegt werden.

Beispiel für Linux amd64:

KUBECTL_VERSION="vX.Y.Z"

curl -LO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
curl -LO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check

sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
rm kubectl kubectl.sha256

Helm 3 kann mit dem offiziellen Installationsskript eingerichtet werden. Prüfen Sie das heruntergeladene Skript vor der Ausführung und fixieren Sie für reproduzierbare Umgebungen eine freigegebene Version:

HELM_VERSION="v3.x.y"

curl -fsSL -o get_helm.sh \
  https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh --version "$HELM_VERSION"
rm get_helm.sh

Weiterführend: kubectl unter Linux installieren und Helm installieren.

6. Kubeconfig ablegen

Der Dateiname muss dem Wert kubeconfig_file im Inventory entsprechen:

install -d -m 700 "$HOME/.kube"
install -m 600 \
  /sicherer/quellpfad/customer-prod.conf \
  "$HOME/.kube/customer-prod.conf"

Beispiel im Inventory:

all:
  vars:
    kubeconfig_file: customer-prod.conf

  children:
    controller:
      vars:
        inv_k8s:
          config:
            context: customer-prod

Die Quelldatei darf anschließend nicht ungeschützt im Arbeitsverzeichnis verbleiben.

7. Deployment-Umgebung abnehmen

source .venv/bin/activate

python --version
ansible --version
ansible-galaxy collection list
kubectl version --client
helm version --short

Prüfen Sie anschließend den tatsächlichen Clusterzugriff:

KUBECONFIG_FILE="$HOME/.kube/customer-prod.conf"
CONTEXT="customer-prod"

kubectl \
  --kubeconfig "$KUBECONFIG_FILE" \
  --context "$CONTEXT" \
  cluster-info

Die Deployment-Umgebung ist vorbereitet, wenn alle Versionsbefehle funktionieren und der konfigurierte Context den richtigen Cluster erreicht. Inventory-Auflösung und Syntaxcheck folgen nach der Konfiguration des Inventory.

Zielcluster vor der Konfiguration prüfen

Verwenden Sie dieselbe Kubeconfig und denselben Context, die später im Inventory eingetragen werden:

KUBECONFIG_FILE="$HOME/.kube/customer-prod.conf"
CONTEXT="customer-prod"

kubectl --kubeconfig "$KUBECONFIG_FILE" \
  --context "$CONTEXT" get nodes

kubectl --kubeconfig "$KUBECONFIG_FILE" \
  --context "$CONTEXT" get storageclass

kubectl --kubeconfig "$KUBECONFIG_FILE" \
  --context "$CONTEXT" get ingressclass

Beginnen Sie erst mit dem Inventory, wenn Clusterzugriff und Ressourcenprüfungen erfolgreich sind und die vorgesehenen StorageClasses eindeutig feststehen.

Nächster Schritt

Damit sind Zielcluster, externe Abhängigkeiten und Deployment-Umgebung vorbereitet. Legen Sie nun unter Konfiguration erstellen zuerst die gemeinsame Plattformbasis und anschließend die Mandanten mit ihren Komponenten fest.