ansible-role-act-runner/.kiro/steering/ansible-best-practices.md

inclusion

inclusion
always

Ansible Best Practices für Act Runner Role

Allgemeine Prinzipien

Idempotenz

• Alle Tasks müssen idempotent sein - mehrfache Ausführung führt zum gleichen Ergebnis
• Verwende changed_when und failed_when für präzise Zustandskontrolle
• Nutze creates Parameter bei command/shell Tasks wo möglich

Variablen und Namenskonventionen

• Alle Variablen beginnen mit act_runner_ als Präfix
• Verwende aussagekräftige Namen: act_runner_config_file statt config_file
• Dokumentiere alle Variablen mit ## @param Kommentaren
• Setze sinnvolle Defaults in defaults/main.yaml

Plattform-Unterstützung

• Verwende OS-spezifische Variablen in vars/ Verzeichnis
• Nutze ansible_facts für Plattform-Erkennung
• Teste auf allen unterstützten Distributionen

Task-Organisation

Struktur

- name: Beschreibender Task-Name
  ansible.builtin.module_name:
    parameter: value
  register: variable_name
  when: condition
  notify: handler_name

Fehlerbehandlung

• Verwende failed_when für spezifische Fehlerbedingungen
• Registriere wichtige Outputs mit register
• Nutze assert für Eingabevalidierung

Handler

• Ein Handler pro Service-Aktion
• Verwende systemd Modul für Service-Management
• Handler sollten idempotent sein

Sicherheit

Berechtigungen

• Setze explizite Dateiberechtigungen (mode)
• Verwende dedizierte Benutzer/Gruppen
• Minimiere privilegierte Operationen

Secrets

• Keine Secrets in Defaults oder Variablen
• Verwende Ansible Vault für sensible Daten
• Dokumentiere erforderliche Secrets klar

Testing und Qualität

Lint-Regeln

• Befolge .ansible-lint Konfiguration für Ansible Dateien.
• Verwende FQCN (Fully Qualified Collection Names)
• Keine deprecated Module verwenden
• Befolge .markdownliny.yaml Konfiguration für Markdown Dateien.

Dokumentation

• Jeder Task braucht einen aussagekräftigen Namen
• Dokumentiere komplexe Logik mit Kommentaren
• README automatisch aus Variablen generieren