anpassen von git ignore

2026-01-29 18:41:59 +01:00
parent 85bcb598df
commit dc06ee04d3
13 changed files with 336 additions and 59 deletions
--- a/README.md
+++ b/README.md
@@ -1,53 +1,118 @@
-# PuppetDB API Abfragen
+# Dockerized Puppet Master (OpenVox)

-Dieses Dokument beschreibt, wie man die PuppetDB-API direkt über `curl` abfragt, um Informationen über den Status der Puppet-Clients zu erhalten.
+Dieses Projekt konfiguriert einen Puppet Master, der in Docker-Containern läuft. Es verwendet Docker Compose für die Orchestrierung der Dienste, einschließlich des Puppet Masters (`openvox`), einer PostgreSQL-Datenbank und anderer notwendiger Komponenten.

-Alle Befehle werden innerhalb des `openvox` (Puppet Master) Containers ausgeführt.
+Die Konfiguration wurde optimiert, um portabel und einfach auf neuen Servern ausrollbar zu sein.

-## Alle aktiven Clients (Nodes) auflisten
+## Inhaltsverzeichnis

-Um eine Liste aller von PuppetDB verwalteten Clients zu erhalten, die aktiv sind, verwenden Sie den folgenden Befehl:
+- [Verzeichnisstruktur](#verzeichnisstruktur)
+- [Lokale Inbetriebnahme](#lokale-inbetriebnahme)
+- [Neuen Puppet-Agenten verbinden](#neuen-puppet-agenten-verbinden)
+- [Deployment mit Ansible](#deployment-mit-ansible)
+- [Backup & Portabilität](#backup--portabilität)

-```bash
-docker compose exec openvox curl -s http://openvoxdb:8080/pdb/query/v4/nodes
-```
+---

-**Beispiel-Ausgabe (gekürzt):**
+## Verzeichnisstruktur

-```json
-[
-  {
-    "certname": "arch-2.lxd",
-    "latest_report_status": "changed",
-    "facts_environment": "production",
-    ...
-  }
-]
-```
-Dies zeigt Ihnen den `certname` jedes Clients, den Sie für weitere Abfragen verwenden können.
+- `docker-compose.yml`: Die zentrale Datei, die alle Docker-Services, Volumes und Netzwerke definiert.
+- `code/`: Enthält den Puppet-Code (Manifeste, Module etc.), der von den Agenten angewendet wird.
+- `config/`: Beinhaltet Konfigurationsdateien für die verschiedenen Dienste.
+- `ca_data/`: **Wichtiges Verzeichnis.** Dies ist ein persistenter Speicher für die Certificate Authority (CA) des Puppet Masters. Es enthält alle signierten Zertifikate und wird per "bind mount" eingebunden.
+- `hiera_config.md`: Erklärt die Konfiguration von Hiera, dem Key-Value-Lookup-System von Puppet, das hier zur Klassenzuweisung verwendet wird.
+- `openvox_bugs.md`: Dokumentiert häufige SSL-Fehler und deren Lösungen.
+- `deploy_openvox.yml`: Ein Ansible-Playbook, um das gesamte Setup automatisiert auf einem neuen Server zu deployen.

-## Reports für einen bestimmten Client abrufen
+---

-Um zu sehen, was auf einem bestimmten Client gelaufen ist, können Sie dessen Reports abfragen. Ersetzen Sie `arch-2.lxd` mit dem `certname` des gewünschten Clients.
+## Lokale Inbetriebnahme

-```bash
-docker compose exec openvox curl -s -G http://openvoxdb:8080/pdb/query/v4/reports --data-urlencode 'query=["=","certname","arch-2.lxd"]'
-```
+Um das Projekt auf einem neuen Rechner (mit installiertem Docker und Docker Compose) zum ersten Mal zu starten:

-### Interpretation der Report-Ausgabe
+1.  **Projektverzeichnis klonen/kopieren:**
+    Stellen Sie sicher, dass Sie das gesamte Projektverzeichnis auf dem neuen Host haben.

-Die Ausgabe ist ein JSON-Array von Reports. Jeder Report enthält wichtige Informationen:
+2.  **CA-Verzeichnis erstellen und Berechtigungen setzen:**
+    Der Puppet-Server im Container läuft nicht als `root`, sondern als Benutzer mit der ID `999`. Wir müssen das `ca_data`-Verzeichnis manuell erstellen und ihm die korrekten Berechtigungen geben. Führen Sie diese Befehle im Hauptverzeichnis des Projekts aus:

-*   `"status"`: Zeigt das Ergebnis des Puppet-Laufs.
-    *   `"changed"`: Der Lauf war erfolgreich und es wurden Änderungen am System vorgenommen.
-    *   `"unchanged"`: Der Lauf war erfolgreich, es waren aber keine Änderungen nötig.
-    *   `"failed"`: Der Lauf ist fehlgeschlagen (z.B. wegen eines Kompilierungsfehlers).
-*   `"logs"`: Enthält die Log-Meldungen des Puppet-Agenten während des Laufs. Hier finden Sie Details zu Fehlern oder erfolgreichen Aktionen.
-*   `"resource_events"`: Zeigt im Detail, welche Ressourcen geändert wurden.
+    ```bash
+    # Verzeichnis für die CA-Daten erstellen
+    sudo mkdir -p ./ca_data

-Anhand dieser Reports können Sie genau nachvollziehen, welche Aktionen auf einem Client erfolgreich waren und welche nicht.
+    # Korrekte Berechtigungen setzen
+    sudo chown -R 999:999 ./ca_data
+    ```

-## Weiterführende Informationen
+3.  **Services starten:**
+    Starten Sie alle Dienste mit Docker Compose.

-Für komplexere Abfragen können Sie die offizielle Dokumentation der PuppetDB API konsultieren:
-[PuppetDB Query API Documentation](https://puppet.com/docs/puppetdb/latest/api/query/v4/overview.html)
+    ```bash
+    docker compose up -d
+    ```
+
+4.  **Status überprüfen:**
+    Nach etwa einer Minute sollte der `openvox`-Container als `healthy` angezeigt werden.
+    ```bash
+    docker compose ps
+    ```
+
+---
+
+## Neuen Puppet-Agenten verbinden
+
+Wenn ein neuer Puppet-Agent mit dem Master verbunden werden soll, muss sein Zertifikat signiert werden:
+
+1.  **Auf dem neuen Agenten:**
+    Führen Sie den Agenten einmal aus. Er wird eine Zertifikatsanfrage (CSR) an den Master senden und mit einem Fehler abbrechen.
+    ```bash
+    sudo puppet agent -t
+    ```
+
+2.  **Auf dem Docker-Host (Master):**
+    Listen Sie die ausstehenden Anfragen auf und signieren Sie die des neuen Agenten.
+    ```bash
+    # Anfragen auflisten
+    docker exec -it openvox puppetserver ca list
+
+    # Anfrage signieren (ersetzen Sie <agent_hostname>)
+    docker exec -it openvox puppetserver ca sign --certname <agent_hostname>
+    ```
+
+3.  **Erneut auf dem Agenten:**
+    Führen Sie den Agenten erneut aus. Er sollte nun das signierte Zertifikat erhalten und seine Konfiguration anwenden.
+    ```bash
+    sudo puppet agent -t
+    ```
+    *Bei SSL-Problemen siehe `openvox_bugs.md`.*
+
+---
+
+## Deployment mit Ansible
+
+Das beiliegende Ansible-Playbook `deploy_openvox.yml` automatisiert die Inbetriebnahme auf einem neuen Server.
+
+**Voraussetzungen:**
+- Auf dem **Steuer-Rechner**: Ansible und die `community.docker`-Collection (`ansible-galaxy collection install community.docker`).
+- Auf dem **Ziel-Server**: Docker und Docker Compose müssen bereits installiert sein. Passwortloser SSH-Zugang vom Steuer-Rechner zum Ziel-Server.
+
+**Ausführung:**
+
+1.  **Playbook verschieben:** Stellen Sie sicher, dass das Playbook `deploy_openvox.yml` eine Ebene *über* dem `openvox`-Projektverzeichnis liegt.
+
+2.  **Inventory erstellen:** Legen Sie eine `inventory.ini`-Datei an, um Ihre Zielserver zu definieren (siehe die Kommentare im Playbook für ein Beispiel).
+
+3.  **Playbook starten:**
+    ```bash
+    # Ersetzen Sie <your_host_group> mit dem Namen aus Ihrer inventory.ini
+    ansible-playbook -i inventory.ini deploy_openvox.yml -e "target_host=<your_host_group>"
+    ```
+
+---
+
+## Backup & Portabilität
+
+Durch die Verwendung eines "bind mounts" für das `ca_data`-Verzeichnis ist das Projekt hochgradig portabel und einfach zu sichern.
+
+- **Backup:** Um ein vollständiges Backup zu erstellen, sichern Sie einfach den gesamten `openvox`-Projektordner. Alle wichtigen Daten (Puppet-Code, CA-Zertifikate) sind darin enthalten.
+- **Wiederherstellung/Umzug:** Kopieren Sie den gesicherten Ordner auf einen neuen Server, führen Sie die Schritte unter [Lokale Inbetriebnahme](#lokale-inbetriebnahme) aus, und Ihr Puppet-Master ist mit allen signierten Zertifikaten wieder online.