OrchidE

OrchidE ist ein Plugin für die JetBrains IntelliJ Plattform um custom language support für Ansible playbooks, roles und variables Dateien zu ermöglichen. Zusätzlich wird die Template-Engine Jinja2 unterstützt.

Diese Anleitung beschreibt die Funktionen die OrchidE für des Editieren von Ansible playbooks, roles und variables mitbringt. Einen allgemeinen Überblick über die IntelliJ Plattform gibt es in der Hilfe zu IntelliJ.

Voraussetzungen

IntelliJ Plattform

OrchidE läuft auf der IntelliJ Plattform und unterstützt

die IntelliJ IDEs:

in der Version 2022.3 oder neuer.

OrchidE wird über den IntelliJ Marketplace zur Verfügung gestellt und kann direkt über die Plugin Konfiguration installiert werden.

Deprecation

Der Support für die IntelliJ Plattform 2022.3 ist deprecated und endet mit dem Start der EAP Version der IntelliJ Plattform 2024.3.

Code Struktur

Zum Parsen von playbooks, roles und variables Dateien von Ansible benötigt OrchidE folgende Voraussetzung damit eine vollständige Unterstützung gegeben ist:

  • Die Datei Erweiterung kann yml oder yaml sein
  • Die Text-Einrückung ist fix auf 2 Leerzeichen eingestellt. Playbooks, roles und variables Dateien müssen damit formatiert sein.
  • Listen müssen eingerückt werden
         
    - hosts: webservers
      tasks:
        - block:
    

Kompatiblität

Der Parser von OrchidE unterstützt nicht die vollständige YAML Spezifikation, sodass nicht alle YAML Formatierungen verwendet werden können. Basis für die unterstützten Formatierungen sind die Best Practices Anmerkungen aus der Ansible Dokumentation. Weitere Details dazu bei den Einschränkungen.

IntelliJ Plattform Konflikte

Das OrchidE Plugin kann Ansible Dateien nicht erkennen, wenn dem Feature ‘Python Template Language’ im gleichen IntelliJ Module ebenfalls die Datei-Erweiterung ‘YAML’ zugewiesen ist. Die Inkompatibilität besteht mit allen Template Sprachen.

Zum Nutzen von OrchidE und der Python Template Language müssen die Dateien in mind. zwei IntelliJ Module aufgeteilt werden.

Konfigurationsdialog Python Template Language

(nur verfügbar in den kommerziellen IntelliJ Editionen mit aktivem Python Plugin)

Installation

Die Installation erfolgt über das IntelliJ Plugin Repository innerhalb IntelliJ. Die Hilfe der IntelliJ Plattform erläutert weitere Details

Eine ältere Version von OrchidE wird folgendermaßen installiert:

  1. Ältere Version manuell aus dem IntelliJ Plugin Repository herunterladen
  2. Über das Menü File | Settings | Plugins den Konfigurationsdialog öffnen
  3. Über das Einstellungssymbol (Icon für Einstellungen) den Befehl “Install Plugin from disk” auswählen und die ältere Version installieren

Information für IntelliJ EAP Nutzer

Bei der Nutzung von OrchidE mit einer EAP Version von IntelliJ kann es nötig sein, die Registrierung der (Trial) Lizenz manuell durchzuführen. Sollte nach der Installation von OrchidE nach dem Neustart kein Dialog zur Aktivierung von OrchidE erscheinen kann das Plugin mit folgenden Schritten aktiviert werden:

  1. Menü → Help → Register aufrufen
  2. OrchidE auswählen und Evaluate for free auswählen.
  3. Evaluate drücken um die Probezeit zu starten. Es erscheint eine Info mit “Free evaluation: 30 days left.
  4. Dialog schließen (es sind keine Lizenzinformationen nötig) und IntelliJ neu starten

Konfiguration

Verzeichnisstruktur

Zum Erkennen von Ansible Dateien benötigt OrchidE zwei grundsätzliche Einstellungen:

  • die Root-Ordner, in denen sich die Playbooks, Roles und Inventories befinden
  • ein Pattern-Set um zu erkennen, ob es sich um eine Playbook-, Task- oder Variablen-Datei handelt

Ab OrchidE 2022.1.5 (Mai 2023) gibt es neue Einstellungen für das Mapping. Die Anleitung für die Konfiguration von Versionen 2022.1.4 und älter ist hier noch verfügbar.

Root-Ordner

Die Root-Ordner und Patterns werden in den Einstellungen unter Datei | Einstellungen | Sprachen & Frameworks | OrchidE | Ansible Folder Mapping konfiguriert.

Damit OrchidE Dateien mit dem richtigen Parser lädt müssen die Root-Ordner zu Playbooks, Roles und Inventories konfiguriert werden. Ohne diese Konfiguration werden Ansible Dateien nicht korrekt dargestellt und übliche IDE Features funktionieren nicht.

Die Konfiguration zum Erkennen von playbooks, tasks und variables ist für die folgende Verzeichnisstruktur voreingestellt:

  project
  |-- inventory
  |   |-- hosts
  |   |-- group_vars
  |   |   |-- webservers
  |   |   |   |-- default.yml
  |-- playbooks
  |   |-- webservers
  |   |   -- main.yml  
  |-- roles
  |   |-- webserver
  |   |   |-- tasks
  |   |   |   |-- main.yml

Alternativ können playbooks auch im playbooks-Ordner direkt abgelegt werden.

Besteht ein IntelliJ Projekt nur aus einer Ansible Rolle, d.h. die tasks, handlers, defaults, … Ordner sind im IntelliJ Projekt Ordner, muss der Projekt Ordner für die Rollen ausgewählt werden.

Der Konfigurationsdialog enthält vier Kategorien:

  • für Inventories
  • für Playbooks
  • für Roles
  • für globale Ausnahmen

Konfigurationsdialog für das Erkennen von Ansible Dateien

Zu den Root-Ordner Kategorien Playbooks und Roles können/müssen zusätzlich Ausnahmen für Variablen und je nach Kategorie Playbook / Rolle gemacht werden.

Playbooks Ordner können

  • Task Dateien und
  • Variablen Dateien enthalten

Roles Ordner können

  • Playbook Dateien und
  • Variablen Dateien enthalten

Global Ignores können

  • Ausnahmen für beliebige für YAML Dateien enthalten, die keine Ansible Dateien sind - z.B Konfigurationsdateien für CI Systeme.

In den jeweiligen Konfigurations-Tabs werden die Ausnahmen mit einfachen Datei-Patterns definiert.

Ansible Mapping Folder Konfiguration zurücksetzen

Die OrchidE Plugin Default-Einstellungen können über den Toolbar-Button (Reset Button) in den jeweiligen Detaileinstellungen wieder hergestellt werden.

Syntax Highlighting

In den Color-Scheme-Einstellungen von IntelliJ kann das Highlighting für OrchidE geändert werden.

(File | Settings | Editor | Color Scheme | OrchidE)

OrchidE color scheme settings dialog.

Code Completion

OrchidE unterstützt die Code-Completion und das Text-Parsing für verschiedene Ansible Versionen. Die zu nutzende Ansible Version hängt vom installierten OrchidE Builder Package ab.

Innerhalb IntelliJ kann das neueste OrchidE Builder package heruntergeladen werden, mit den zum Zeitpunkt der Erstellung aktuellsten Collections aus Ansible Galaxy.

Pakete für eine bestimmte Ansible Version können von der OrchidE Builder GitHub Seite heruntergeladen werden.

Um die Übersichtlichkeit bei der Code-Completion zu verbessern, können Ansible Modul-Kategorien aktiviert / deaktiviert werden.

Auswahl Ansible Version für Code Completion

Entfällt ab OrchidE 2023.1.4.

(File | Settings | Languages & Frameworks | OrchidE)

OrchidE code completion settings version dialog.

Konfiguration für Ansible <collections>

(File | Settings | Languages & Frameworks | OrchidE | Collections)

OrchidE code completion settings dialog - collections.

Zusätzlich kann für jede Collection festgelegt werden ob der full qualified collection name oder nur der Modulname (ohne Namespace) vorgeschlagen wird.

Verfügbare Optionen sind:

  • FQCN only: immer nur den full qualified collection name anzeigen
  • Name only: immer nur den Modulnamen ohne Namespace anzeigen
  • Show FQCN and name: immer beides anzeigen
  • Based on collection keyword: nur den Modulname anzeigen, wenn die Collection im Suchpfad aufgeführt ist (Keyword: collections:), ansonsten wird beides angezeigt.

OrchidE code completion settings dialog - collections.

Die Default Einstellung ist Based on collection keyword

Konfiguration für Ansible <=2.9 (veraltet)

Nicht mehr verfügbar seit OrchidE 2023.1.4.

(File | Settings | Languages & Frameworks | OrchidE | Modules)

OrchidE code completion settings dialog - classic.

‘Quick Documentation’

OrchidE zeigt im Quick Documentation Popup/Tool Window die Dokumentation zu Ansible Modulen, Modul-Argumenten und Keywords an.

Die Dokumentation ist nicht Teil von OrchidE und muss separat installiert werden. Dazu legt man das Download Verzeichnis in den Extension Einstellungen fest und installiert das aktuelle Definitionspaket.

OrchidE Builder Definition File installieren

(File | Settings | Languages & Frameworks | OrchidE | Extension)

OrchidE extension settings dialog.

Weitere Einstellungen zur Quick Documentation kann in der offiziellen IntelliJ Dokumentation von quick documentation und documentation tool window nachgelesen werden.

Inlay Hints für Jinja Variablen

OrchidE kann im Editor für die meisten Jinja Variablen den oder die Werte der Referenz als inlay hints anzeigen.

OrchidE editor with inlay hints.

In den Einstellungen können die Inlay Hints aus- und eingeschaltet und die Darstellung beeinflusst werden:

(File | Settings | Editor | Inlay hints)

Ansible inlay hints settings.

Code Completion

OrchidE unterstützt die IntelliJ Code-Completion via Tab- und Enter-Taste. Es werden

  • vars (in Jinja2 Templates),
  • group und host Variablen in Inventory-Variablen Dateien
  • roles,
  • modules,
  • module arguments
  • keywords
  • registered vars (innerhalb einer Datei),
  • set_fact vars (innerhalb einer Datei)
  • tags (innerhalb einer Datei)
  • variables aus der argument spec-Definition (innerhalb Playbooks und Jinja2 templates derselben Role)

bei der Code-Completion unterstützt.

Bei der Code Completion von Modulen mit der Enter-Taste werden auch alle Pflichtargumente eingefügt.

Bei der Code Completion von Group und Host Variablen mit der Enter-Taste wird auch die Beschreibung der Variable aus der argument-spec Definition eingefügt. Gibt es keine argument-spec Definition, werden aus der Role defaults Datei der Kommentar eingefügt.

Ansible Facts

Zusätzlich wird ein Auszug der typischen facts-Variablen unterstützt. Die Code Completion von facts ist ein ‘Vorschlag’ von OrchidE. Ob eine facts-Variable auch zur Laufzeit zur Verfügung steht, ist abhängig von der konkreten Konfiguration zur Ausführungszeit.

Code Completion mit Werten

Bei keywords und module arguments gibt es zusätzliche Vorschläge mit Werten.

Code completion with values

Für Boolean Werte können die Vorschläge in der Konfiguration angepasst werden.

(File | Settings | Editor | OrchidE )

Editor Konfiguration code completion

Inventory group und host Variablen

Für die Code Completion von Variablen wird entweder eine Annotation benötigt, oder ein Playbook mit Rollen und passendem Inventory Eintrag.

Bei der Variante mit Annotation gibt es Vorschläge aus der Rolle von den Meta Daten (argument spec) und den Variablen in defaults.

Bei der Variante mit Playbook werden Vorschläge von allen inkludierten Rollen gemacht.

Die Annotation hat folgendes Format

#@role::<role name> 

Der Trigger für die Code Completion ist #@ am Zeilenanfang.

Für alle folgenden Zeilen wird bei der Code Completion (und Quick Documentation) nur noch diese Rolle genutzt.

Code completion von Group und Host Variablen

Das Nutzen der Role Annotation ist empfehlenswert:

  • damit gibt es keine Namenskonflikte beim Auflösen der Dokumentation,
  • die Code Completion zeigt nur Variablen für diese Rolle an,
  • die Navigation zur Definition in der Argument Spec benötigt diese Angabe - ohne Annotation ist keine Navigation möglich

Mit der Intention und Inspection ‘Role Annotation’ ist es einfach die Annotation nachträgliches hinzu zufügen.

Role Annotation Inspection & Intention

Zusätzlich gibt es Folding für die Annotation, so können ganze Blöcke von Variablen für eine Rolle ein- und ausgeblendet werden.

Folding role annotation

In Abhängigkeit der Code-Completion Taste (Enter / Tab) und der ausgewählten Source (argument_spec/defaults) werden unterschiedliche Inhalte eingefügt:

Bei Nutzung der Argument Specs Datei:

  • Tab-Completion: die Variable wird eingefügt
  • Enter-Completion: die Variable und Description wird eingefügt

Bei Nutzung der Defaults Datei:

  • Tab-Completion: die Variable wird eingefügt und bei Dictionaries alle Unterstrukturen
  • Enter-Completion: die Variable und Kommentare (bis zur ersten Leerzeile) oberhalb der Variable werden eingefügt. Bei Dictionaries werden auch alle Unterstrukturen eingefügt

Code Completion für Dateinamen

Für die Ansible Module include_tasks, import_tasks und template gibt es Vorschläge von Dateien.

Für das Argument src des Template Tasks kann zusätzlich eingestellt werden welche Dateien angezeigt werden sollen:

  • auch Dateien relativ zum Playbook,
  • nur Dateien in einem templates Ordner,
  • nur Dateien mit der Dateierweiterung *.j2 oder alle Dateien.

Konfiguration Code completion für das template - src Argument

Project View

Der Project View für Ansible (Ansible Structure) stellt die Playbooks, Roles und Inventory Groups und Hosts mit den zugehörigen Group Vars / Host Vars in einer kompakten Ansicht dar um die Navigation zu erleichtern.

Project View Auswahl

Project view choice

Um den Project View Ansible Structure zu nutzen, müssen in den Einstellungen die Pfade zum Inventory, den Playbooks und Roles gesetzt sein (File | Settings | Languages & Frameworks | OrchidE | Ansible Folder Mapping)

Der View ist in drei Teile untergliedert:

  • Inventories
  • Playbooks
  • Roles

Inventories

Die Inventory Struktur ist aufgeteilt in

  • Default groups (all und ungrouped),
  • Gruppen von groups,
  • Groups,
  • Hosts und
  • zugehörige Variablen(-dateien)

Der Project View zeigt Inventory Einträge von Inventory-Dateien im INI- und YAML-Format.

Project view inventory

Playbooks

Project view playbooks

Roles

Die Roles Struktur wird als virtuelle Struktur auf Basis von tasks/main.yml dargestellt:

  • Role (tasks/main.yml)
  • zugehörige weitere Tasks-Dateien
  • Handlers
  • Default und Group vars
  • weitere Ordner und Dateien

Project view roles

Konfiguration

Project View Konfiguration

Für den Project View “Ansible Structure” sollten die Project View Einstellungen

  • Sort by type und
  • Folder Always On Top

aktiviert werden, um den logischen Aufbau für die Anzeige so darzustellen wie von OrchidE vorgesehen.

recommended project view configuration


Für die Nutzung des Project View “Ansible Structure” müssen die Root-Ordner zu Playbooks, Roles und Inventories in den Einstellungen (Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping) konfiguriert sein.

OrchidE unterstützt die Navigation zur Definition von Variablen und zu Implementierung von Imports. Diese Funktion ist auf die IntelliJ Funktion “Go to Declaration” gebunden (Shortcuts: Ctrl + B, + B).

Unterstützt werden

  • Variablen in Jinja2 Templates
  • Import Tasks
    • import_tasks
    • import_playbook
    • import_role -> name
    • include_tasks
    • include_tasks -> file
  • Template Task
    • src Argument mit statischem Datei-Namen
  • Keyword vars_files
  • Roles Rollen Verweise
  • Keyword hosts in Playbooks

Symbole mit Navigationssupport go to declaration OrchidE Navigation support go to declaration


Die Navigation wird auch für einfache dynamische Imports unterstützt (Dateinamen mit Jinja2 Templates)

OrchidE Navigation support of dynamic includes

Für folgende Notation ist eine Navigation möglich:

  • include_tasks: “{{ variable }}<postfix string, no path>”
  • include_tasks: <prefix path>/{{ variable }}
  • include_tasks: <prefix path>/<prefix name>{{ variable }}<postfix string, no path>

Beispiele:

  - include_tasks: "{{ ansible_os_family }}.yml"
  - include_tasks: "{{ a_variable_file_name }}"
  - include_tasks: my_path/{{ ansible_os_family }}.yml
  - include_tasks: my_path/custom-{{ ansible_os_family }}.yml

Anmerkung dynamic includes:

Für dynamic includes wird die OrchidE-Builder Extension benötigt. Die Liste der unterstützten Variablen steht in GitHub.

Die Navigation zur Ziel-Datei funktioniert bei der Verwendung von Jinja2 Templates nur, wenn der Cursor ausserhalb dem Jinja2 Template ist und kein Ordner ist.

(Die Include Referenz ist durch die eingebettete Jinja2 Referenz überschrieben und ist deswegen bei Verwendung von Jinja2 Templates nicht zur Navigation nutzbar)

OrchidE unterstützt die Navigation zu Playbooks und Rollen. Diese Funktion ist auf die IntelliJ Funktion “Go to class” gebunden (Shortcuts: Ctrl + N, + O)

OrchidE Navigation support go to playbook and roles


OrchidE unterstützt die Navigation (Shortcuts: Ctrl + Shift + O, danach I, + Shift + O, danach I oder Menü | Navigate | Inventory) zu Inventory Group und Host Einträgen und den zugehörigen Dateien mit group/host-Variablen.

Die Suche/Navigation zu Host und Group-Namen ist aktuell für Inventory-Dateien im INI-Format verfügbar. Für die Nutzung muss zusätzlich das INI Plugin (ini4idea) von JetBrains installiert sein. (YAML für Inventory-Dateien wird nicht unterstützt.)

Für diese Funktion müssen die Root-Ordner zu Playbooks, Roles und Inventories in den Einstellungen (Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping) konfiguriert sein.

SearchEverywhere Dialog für Inventory Einträge

OrchidE search for inventory entries


OrchidE unterstützt die direkte Navigation zu Variablen. Diese Funktion ist auf die IntelliJ Funktion “Go to symbols” gebunden (Shortcuts: Ctrl + Alt + Shift + N, + Option + O)

OrchidE Navigation support go to variable


OrchidE unterstützt die Navigation zwischen Ansible Tasks in Playbooks und Tasks-Dateien. Die Navigation ist auf die IntelliJ Funktionen “Next/Previous Method” gebunden (Shortcuts: Alt + Up/Down, Control + Up/Down).

OrchidE Navigation support go to task

OrchidE unterstützt die Navigation zu related symbols für

  • Host und Gruppen-Einträge in Inventory-Dateien im INI- und YAML-Format
  • Playbooks,
  • Roles,
  • Group/Host Variablen

Die Navigation erfolgt über Navigate ➞ Related Symbol (Ctrl + Alt + Home, Ctrl + + Up)

OrchidE Navigation support for related symbols

Unterstützt wird die Navigation:

aus Playbooks

  • zu inkludierten Variablen-Dateien
  • zu Roles (-> tasks/main.yml)
  • zu Group/Host Variablen
  • zu Inventory Einträgen

aus Roles (tasks, vars, defaults)

  • zu allen Dateien in der Rolle
  • zu Playbooks, welche die Rolle einbinden
  • zu Group/Host Variablen (via Rolle in Playbook)
  • zu Inventory Einträgen (via Rolle in Playbook)

von Inventory Einträgen (exakte Cursor-Position)

  • zu Playbooks
  • zu Group/Host Variablen

aus Group/Host Variablen

  • zu Playbooks
  • zu Rollen (via Playbooks)
  • zu Inventory Einträgen

OrchidE unterstützt die Navigation von group / host Variablen im Inventory zur Definition der Variablen in Rollen argument specs und defaults Variablen.

Die Navigation erfolgt über die IntelliJ Funktion “Go to Declaration” (Shortcuts: Ctrl + B, + B).

OrchidE Navigation support for group and host variables

Für diese Funktion muss eine Role Annotation gesetzt sein.
OrchidE role annotation

Inspections

OrchidE Inspections können über die Einstellungen (Settings | Editor | Inspections | Ansible) konfiguriert oder deaktiviert werden.

Deprecation

OrchidE prüft bei der Verwendung von Modulen, ob das jeweilige Modul deprecated ist und markiert entsprechende Module. Die Prüfung auf deprecated erfolgt gegen die höchste Version von Ansible die von OrchidE unterstützt wird. Auch wenn die Versions-Kompatibilität auf eine ältere Ansible Version eingestellt ist, werden alle Module mit dem Sprachumfang der neuesten unterstützten Version von Ansible auf deprecated geprüft und angezeigt.

Prüfung auf unbekannte Vars

OrchidE prüft, ob die Auflösung einer Variable in einem Jinja2 string möglich ist (bei Playbooks, Roles und Variables). Die Prüfung erfolgt innerhalb des IntelliJ Projekts - d.h. ob zur Laufzeit des Playbooks die Variable verfügbar ist, hängt von der Hosts Definition ab. Die Prüfung in OrchidE ist eine generische Prüfung, ob eine Variable definiert ist (in der Rolle und im kompletten Inventory) und kann von der Runtime abweichen.

Die Inspection prüft ob Variablen in einer der folgenden Stellen definiert wurde

  • facts (innerhalb roles, die mit set_facts gesetzt wurden)
  • Rollen Variablen
  • Rollen defaults
  • Host- und Group-Variablen
  • Variablen die mit dem register Keyword gesetzt wurden

OrchidE kann Variablen, die mit set_fact und register gesetzt wurden, innerhalb einer Rolle anhand include-/import_tasks Modulen auflösen. (unterstützt werden include/import Pfade wie in dynamische Imports beschrieben)

Mit dem QuickFix “Suppress for this variable” kann die Prüfung für einzelne Stellen unterdrückt werden.

Diese Inspection verfügt über zusätzliche Konfiguration.

Prüfung auf unbekannte Ansible Keywords

Diese Prüfung besteht aus zwei Varianten: Eine für Rollenaufrufe und eine für alle anderen Keywords.

OrchidE prüft, ob in Playbooks, Tasks und Blocks ob die Keywords korrekt sind und markiert unbekannte (falsche) Keywords.

Für Role Keywords wird in der Default-Einstellung eine geringe Warnung angezeigt, da Rollenaufrufe auch Variablen enthalten dürfen. Best Practice ist es Variablen mit dem Keyword vars anzugeben. Dann kann die Prüfung umgestellt werden, um einen Fehler bei unbekannten Keywords anzuzeigen.

- roles:
    - role: testrole
      vars:
        customvar: for this call only

Prüfung auf unbekannte Ansible Modul-Argumente

OrchidE prüft in Tasks, ob alle Modul-Argumente korrekt sind und markiert unbekannte / falsche Argumente

Diese Prüfung wird ab Ansible 2.8 vollständig unterstützt. Für ältere Ansible Versionen werden Aliase von Argumenten nicht unterstützt und als Fehler angezeigt.

Manche Module, wie z. B. set_fact erlauben durch Ihre Art beliebige Argumente. Solche Module werden von der Prüfung ausgeschlossen.

Die Liste der ausgeschlossenen Module umfasst:

  • set_fact
  • local_action

Weitere Module können über eigene definition files hinzugefügt werden. Details dazu in Erweitern von OrchidE

Falscher Werte-Typ bei keywords und module arguments

OrchidE prüft die Werte von keywords und module arguments für die Typen

  • Boolean,
  • Integer,
  • String und
  • Werte-Listen.

Unterstützt wird auch die Verwendung von Jinja Variablen mit einfachen Referenzen, z. B.

- name: Sample
  become: "{{ use_become }}"

Die Definitionen werden von der collection und keyword Dokumentation genutzt. Eigene Definition aus argument_specs werden zurzeit nicht unterstützt.

Prüfung auf doppelte Keys

OrchidE prüft ob YAML Keys unterhalb eines Keys doppelt vorkommen.

Prüfung auf fehlende Include-Dateien

OrchidE prüft für diverse Ansible Module ob referenzierte Dateien verfügbar sind.

Unterstützt werden

  • alle import/include_* Module
  • das Src-Argument des template Moduls
  • das vars_file Keyword in Playbooks

Um alle Suchpfade von Ansible zu durchsuchen, ist es nötig, dass die Root-Ordner zu Playbooks in den Einstellungen (Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping) konfiguriert sind.

Werte von Variablen in group / host vars-Dateien auf korrekten Typ prüfen

OrchidE prüft die Werte von Variablen für die Typen

  • Boolean,
  • Integer,
  • String und
  • Dictionaries.

Unterstützt wird auch die Verwendung von Jinja Variablen mit einfachen Referenzen.

Prüfung auf Eindeutigkeit von Task-Namen

OrchidE prüft nicht voll qualifizierte Task-Namen (ohne Namespace) auf Mehrdeutigkeit, und zeigt eine Warnung wenn der Task in mehreren Namespaces verfügbar ist.

Wenn das Playbook (collections Keyword) oder die Rolle (collections Keyword in der meta-Datei) über eine Liste von Namespaces verfügt, wird die Prüfung auf Mehrdeutigkeit auf Basis dieser Liste unterstützt.

Inspection Unique Tasks

Intentions

Intentions zum Erstellen von Ansible Variablen

OrchidE bietet beim Benutzen von Ansible Variablen in Jinja2 Templates die Möglichkeit diese Variablen direkt zu erstellen.

Erzeugen von Variablen via Intention

Innerhalb einer role kann eine Ansible defaults oder vars Variable erzeugt werden. Sollte noch keine Variablen Datei existieren, wird eine neue Datei angelegt.

Allgemein kann die Variable immer in group vars oder host vars hinzugefügt werden. Bei der Erstellung von neuen Variablen in host/group vars-Dateien, muss die Datei bereits existieren.

Intention Dialog group vars Datei wählen

Intentions zum Erstellen von fehlenden Dateien

Mit dieser Intention können fehlende Dateien direkt erstellt werden.

Unterstützt werden

  • alle import/include_* Module
  • das Src-Argument des template Moduls
  • das vars_file Keyword in Playbooks

Intention Dialog neue Datei erstellen

Refactoring

Refactoring von Values und Strings

In Rollen können Values und Strings in Variablen umgewandelt werden - in Rollen default Variablen (defaults-Ordner -> main.yml) oder statische Variablen (vars-Ordner -> main.yml).

Über das Kontext Menü | Refactor | Extract | Variable (zu defaults) bzw. Refactor | Extract | Constant (zu vars) wird die aktuelle Stelle extrahiert. Ist kein Text selektiert, wird der komplette String bzw. das komplette Value in eine Variable umgewandelt.

Ist der Text mehrmals in der Datei vorhanden, werden alle Stellen ersetzt.

Das Refactoring wird immer nur im aktuellen Editor/der aktuellen Datei durchgeführt, ein Refactoring für das ganze Projekt wird nicht unterstützt.

Verschieben von Tasks

Ansible Tasks können mit der IntelliJ Funktion Move Statement Up/Down einfach in Playbooks und Tasks-Dateien verschoben werden.

Movement of Ansible Task

Editor

Klammern und Jinja Variablen

OrchidE unterstützt das automatische Einfügen von schließenden Klammern.

Zusätzlich wird die Jinja Klammer ({{) unterstützt. Eventuell nötige “ werden ergänzt.

Einrückung nach ‘Enter’

Nach “Enter” fügt OrchidE sinnvolle Einrückung und/oder den Bindestrich für Listen automatisch ein.

Mit der Backspace wird die Einrückung wieder rückgängig gemacht. Dazu muss die Smart Key Einstellung Unindent on Backspace aktiviert sein. (File | Settings | Editor | General | Smart Keys - Sektion Enter)

Anmerkung: Es gibt in OrchidE keinen Unterschied zwischen den zwei Einrückungseinstellungen.

Als Option kann bei Leerzeilen auch die Enter-Taste genutzt werden. Anstatt einer neuen Zeile wird dann die Einrückung rückgängig gemacht. Per Default ist diese Verhalten deaktiviert und kann über (File | Settings | Editor | OrchidE ) aktiviert werden.

Editor-Tab Namen

Tasks einer Rolle werden typischerweise immer in einer Datei main.yml abgelegt. Zur besseren Übersichtlichkeit ersetzt OrchidE die Namen im Tab der Editoren durch den Namen der Rolle bzw. des Playbooks.

Titel für IntelliJ-Editor-Tabs anpassen

Diese Verhalten kann in der Konfiguration geändert werden.

(File | Settings | Editor | OrchidE )

Editor Konfiguration

New file Aktion

OrchidE kann Ansible-Dateien (und zugehörige Ordner) kontext-unabhängig für Playbooks, Rollen und Inventory-Variablen-Dateien erzeugen

New file dialog for Ansible files

Die New file-Aktion basiert auf den Root-Ordner für Playbooks, Roles und Inventories aus den Einstellungen (Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping).

Folgende Typen können angelegt werden:

  • Rollen: erzeugt einen Ordner für die Rolle und je nach Auswahl noch ein tasks/main.<ext> oder meta/main.<ext> Datei.
  • Playbooks: erzeugt eine Playbook-Datei oder ein Ordner mit main.<ext>.
  • Group var: erzeugt eine Inventory group var-Datei im <inventory>/group_vars Ordner. Optional als Ordner mit voreingestellten Dateiname.
  • Host var: erzeugt eine Inventory host var-Datei im <inventory>/host_vars Ordner.

Es wird nur eine Auswahl angeboten, wenn auch die dazugehörigen Root-Ordner konfiguriert sind.

Den Default Dateinamen für Ordner-basierte Group Var-Dateien und die bevorzugte YAML Dateierweiterung kann in den Einstellungen konfiguriert werden.

(File | Settings | Editor | OrchidE)

New file dialog for Ansible files


Copy & Paste Support

Beim Kopieren und Einfügen von Ansible Code wird der eingefügte Code entsprechend eingerückt.

Die automatische Einrückung von eingefügtem Code wird unterstützt für

  • Tasks,
  • Module,
  • Modul-Argumente,
  • und Variablen.

Wenn der kopierte Text unverändert eingefügt werden soll, kann Paste as Plain Text verwendet werden.

Andere Codeteile werden mit der ursprünglichen Einrückung eingefügt.

Wenn Text im Spaltenmodus markiert und kopiert wird, wird die Einrückung nicht angepasst. Der kopierte Text wird unverändert eingefügt.

Jinja2 Template Unterstützung

Unterstützte Features

OrchidE hat generische Unterstützung für Jinja2 Templates. Bei der generischen Unterstützung wird der Inhalt plain text interpretiert und Jinja2 Expressions und Statements können genutzt werden.

  • Für Jinja2 Expressions und Statements
    • wird Syntax Highlighting wie in playbooks und roles unterstützt.
    • wird Jinja2 Whitespace Control (‘{{-’, ‘-}}’) unterstützt
  • Bei Ansible Variablen wird zusätzlich
    • Code Completion,
    • die Goto Declaration Funktion und
    • Inspections unterstützt, wenn die Variable als einfaches Template Pattern verwendet wird (z.B. “{{ akey }}”).

Weitere Jinja2 Syntax Features werden nicht unterstützt, wie zum Beispiel Formatierung, Variablenerkennung von set-Methoden, Variablen in Schleifen, …)

Wie bei playbooks und roles prüft OrchidE ob die genutzten Variablen innerhalb des IntelliJ Projektes in einer hosts/group Variablen deklariert wurde und markiert ansonsten die Variable mit einer Warnung.

Für die Dateitypen XML, JSON und Properties werden die Sprachfeatures der jeweiligen Plugins unterstützt (Syntax Highlighting, Parsing, Inspections, Kommentare, Formatierung (nicht für Properties)).

OrchidE nutzt die Dateinamenerweiterung *.j2 zur Erkennung von Jinja2 Templates:

  • *.xml.j2 für XML Dateien
  • *.json.j2 für JSON Dateien
  • *.yaml/yml.j2 für YAML Dateien
  • *.properties.j2 für Properties Dateien
  • *.j2 für alle anderen Dateitypen - interpretiert als plain text Dateien.

Einschränkungen für die Basis-Sprache in Jinja2 Templates

Properties und YAML-Dateien

Die Inspections

  • Unused property (Properties)
  • Duplicate key (Properties, YAML)

der Plugins können bei der Nutzung von Jinja2 template expressions/statements zu falschen Resultaten führen.

Unterstützung für Ansible Vault

OrchidE kann Ansible Vault-Dateien entschlüsseln und neue Vault Dateien verschlüsseln. Außerdem können einzelne Werte von Variable verschlüsselt und entschlüsselt werden. Vault IDs werden ebenfalls unterstützt.

Decrypt Ansible Vault file


Konfiguration (optional)

Unter Settings ➞ Languages & Frameworks ➞ OrchidE kann eine Ansible Konfigurationsdatei (ansible.cfg) angegeben werden.

OrchidE nutzt die Angabe vault_password_file, um Ansible Vaults zu entschlüsseln.

OrchidE unterstützt dabei das Lesen von Plain-Text Passwort-Dateien. Ausführbare Dateien werden nicht unterstützt.

Wenn Umgebungsvariablen in der ‘ansible.cfg’ verwendet werden, wird eine einfache variable substitution durchgeführt, erweiterte Shell-Variablenverarbeitung wird nicht unterstützt. Um Umgebungsvariablen verwenden zu können, müssen diese dem IntelliJ Plattform Prozess bekannt sein.

Wird ein Eintrag für eine Ansible Vault-ID im IntelliJ Passwort Manager gefunden, wird immer diese verwendet und die Ansible Konfiguration nicht genutzt.

Ansible Vaults werden automatisch beim Öffnen im Editor entschlüsselt, wenn ein passendes Passwort vorhanden ist.

Öffnen eines Vaults

Wird im Editor eine Vault-Datei geöffnet, kann über das Editor - Kontext - Menü ➞ OrchidE ➞ Decrypt Vault der Inhalt entschlüsselt werden. Danach verhält sich der Editor wie jede andere geöffnete Datei mit Variablen:

  • Es steht Code Completion für Jinja2 Variablen zur Verfügung
  • Die Inspection Undefined Variables erkennt die Variablen
  • Die Navigation zu deklarierten Variablen aus anderen Dateien ist möglich

Beim Speichern der Datei, wird der Inhalt im Hintergrund verschlüsselt. Dabei/danach steht der Editor-Inhalt weiterhin lesbar zur Verfügung.

Zur Verwaltung der Passwörter benutzt OrchidE die integrierte Passwort-Verwaltung von IntelliJ. Im Passwort-Dialog kann dazu angegeben werden, ob Passwörter persistent oder nur für die IDE Session gespeichert werden sollen.

Erzeugen eines neuen Vaults

Eine neue Vault Datei kann für jede Datei mit Variablen über das Editor - Kontext - Menü ➞ OrchidE ➞ Encrypt Vault erstellt werden. Es können nur Dateien verschlüsselt werden die von OrchidE als Variablen Dateien erkannt werden (FileType Einstellungen und Pattern Matching müssen stimmen)

Im Password Dialog kann man eine Vault ID und das Passwort eingeben. Danach wird die Datei verschlüsselt und so auch im Editor angezeigt. Um mit der Datei weiter zu arbeiten, ist ein Decrypt nötig.

Dateien, die bereits ein Vault sind, können nicht verschlüsselt werden, sondern werden automatisch bei jedem Speichern verschlüsselt.

Setzen einer Vault Id

Für existierende Vault Dateien kann die Vault Id neu gesetzt werden.

Der entsprechende Befehl ist im Editor-Kontext-Menü erreichbar: Menü ➞ OrchidE ➞ Set Vault Id.

Setzen einer neuen Vault ID für eine Ansible Vault Datei

Ändern des Passwortes für ein Vault

Für existierende Vault Dateien kann ein neues Passwort gesetzt werden. Dabei spielt es keine Rolle, ob die Vault-Datei im Editor verschlüsselt oder unverschlüsselt angezeigt wird.

Der entsprechende Befehl ist im Editor-Kontext-Menü erreichbar: Menü ➞ OrchidE ➞ Change Password.

Password ändern Menu für Ansible Vault Dateien

Ver- und Entschlüsseln von Ansible Variablen

Werte von Ansible Variablen können einzeln im Editor verschlüsselt werden.

Wenn der Cursor auf einem Variablewert steht, kann über das Editor - Kontext - Menü ➞ OrchidE ➞ Encrypt Value der Wert verschlüsselt werden, bzw. ein Vault entschlüsselt werden.

Verschlüsseln von Variablenwerten

Weitere Funktionen

Werden in playbooks und roles Ansible Variablen aus dynamischen inventories oder der Kommandozeile genutzt, können diese Variablen in OrchidE erstellt werden. Diese Variablen werden dann bei der Code Completion und der Inspection “Undefined Variables” berücksichtigt.

Extra Vars Konfigurationsdialog

“Extra Variablen” können auch mit dem Quick Fix “Create extra vars variable” der Inspection “Undefined Variable” direkt aus dem Editor hinzugefügt werden.

Quick Fix create extra vars variable

Die zusätzlich erstellten Variablen werden im IntelliJ .idea Projekt-Ordner in der Datei orchide-extravars.xml gespeichert und können in die Versionsverwaltung eingecheckt werden.

Erweitern von OrchidE

OrchidE definition file builder

Der OrchidE definition file builder ist ein Command-line Tool um Definition für OrchidE zu erzeugen. Diese Definition umfassen Meta-Daten für den Parser, die Code Completion und Inspections in OrchidE um Ansible Elemente zu erkennen.

Damit kann OrchidE um Support für weitere Module aus Ansible Galaxy Collections und eignen Collections erweitert werden.

Der Builder erzeugt aus Ansible Galaxy Collections JSON Dateien die Definitionen zu Modulen mit allen Attributen enthalten. OrchidE verwendet diese JSON Dateien um Ansible Playbooks und Rollen zu parsen, Vorschläge für die Code Completion darzustellen und zur Prüfung auf gültigen Code.

OrchidE kommt mit einer großen Anzahl an Definitionen für die bekanntesten Ansible Collections. Sollten Collections oder allgemeine Definition fehlen oder out-of-date sein können mit dem Builder eigene Paket gebaut werden und in OrchidE eingebunden werden.

Den Builder, aktualisierte Definitions-Pakete und weitere Details dazu gibt es auf GitHub

Einschränkungen

Der Language Parser von OrchidE wurde von Grund auf für playbooks und roles geschrieben. Eine vollständige Unterstützung für YAML ist nicht vorhanden.

Es ist empfehlenswert YAML Dateien mit dem integrierten YAML Editor zu bearbeiten. Gibt es YAML Dateien innerhalb der von OrchidE unterstützten Dateistruktur für playbooks kann der file type im Kontext-Menü zwischen YAML und Ansible Support umgestellt werden.

Programmier-Sprache einer YAML-Datei ändern

Außerhalb der unterstützten Dateistruktur wird für YAML Dateien immer auf den voreingestellten Editor der IDE gewechselt. (Sofern keine manuellen Änderungen an den File Associations für die yml-Dateinamenerweiterung vorgenommen wurde.)

Eingeschränkte und nicht unterstützte YAML Funktionen

  • Es werden nur die Ansible Tags !unsafe und !vault unterstützt.
  • Flow styles/flow collections werden nur eingeschränkt unterstützt (1. Ebene)
  • Complex mapping key (?_) wird nicht unterstützt
  • YAML Directive werden nicht unterstützt

Einschränkungen für IntelliJ Plattform 2019.1 und 2019.2 (ältere, nicht mehr unterstützte Versionen)

Bei mehr als einem geöffneten Projekt mit den IntelliJ Plattform Versionen 2019.1 und 2019.2, muß der “Projekt schließen”-Button zweimal betätigt werden, sofern noch nicht gespeicherte Vault-Dateien vorhanden sind.