OrchidE

OrchidE is a plugin for the JetBrains IntelliJ platform to enable custom language support for Ansible playbooks, roles and variables files.

These instructions describe the features OrchidE provides for editing Ansible playbooks, roles and variables. A general overview of the IntelliJ platform can be found in the IntelliJ Help.

Prerequisites

IntelliJ Platform

OrchidE runs on the IntelliJ platform and requires one of these IDEs

IntelliJ IDEs:

in version 2022.3 or later.

OrchidE is distributed via the IntelliJ Marketplace and can be installed directly via the plugin configuration.

Deprecation

Support for IntelliJ Platform 2022.3 is deprecated and will end with the launch of the EAP for IntelliJ version 2024.3.

Code Structure

To recognize playbooks, roles and variables files of Ansible, OrchidE needs a predefined structure. The following requirements must be given for full support:

  • The file extension can be yml or yaml
  • The text indentation is fixed to 2 spaces. Playbooks, roles and variables files must be formatted with it.
  • Lists must be indented
         
    - hosts: webservers
      tasks:
        - block:
    

Compatibility

The parser of OrchidE does not support the complete YAML specification, so not all YAML formats can be used. Basis for the supported formats are the best practices notes from the Ansible documentation. For more details see limitation.

IntelliJ Platform Conflicts

The OrchidE plugin cannot recognize Ansible files if the ‘Python Template Language’ feature in the same IntelliJ module is also assigned the file extension ‘YAML’. The incompatibility exists with all template languages.

To use OrchidE and the Python Template Language, the files must be split into at least two IntelliJ modules.

Configuration of Python Template Language

(only available in the IntelliJ commercial versions if Python plugin is activated)

Installation

The installation is done via the IntelliJ Plugin Repository within IntelliJ. The Help of the IntelliJ platform explains further details.

To install an older version of OrchidE, please proceed as follows:

  1. manually download older version from the IntelliJ Plugin Repository
  2. open the configuration dialog via the menu File | Settings | Plugins.
  3. select the command “Install Plugin from disk” via the setting symbol (Icon for settings) and install the older version

Information for IntelliJ EAP users

When using OrchidE with an EAP version of IntelliJ, it may be necessary to register the (Trial) license manually. If after installing OrchidE no dialog for activating OrchidE appears after restarting, the plugin can be activated by following these steps:

  1. Menu → Help → Register
  2. Select OrchidE and choose Evaluate for free.
  3. Press Evaluate to start the trial period. An info appears with “Free evaluation: 30 days left.
  4. Close the dialog (no license information is required) and restart IntelliJ

Configuration

Directory Layout

To recognize Ansible files, OrchidE needs two basic settings:

  • the root folders where the playbooks, roles and inventories are located.
  • a pattern set to recognize if it is a playbook, task or variable file

As of OrchidE 2022.1.5 (May 2023) there are new settings for mapping. The instructions for the configuration of versions 2022.1.4 and older is still available here.

Root-Folders

The root folders are configured in the settings under File | Settings | Languages & Frameworks | OrchidE | Ansible Folder Mapping.

In order for OrchidE to load files with the correct parser, the root folders to Playbooks, Roles and Inventories must be configured. Without this configuration Ansible files will not be displayed correctly and common IDE features will not work.

The configuration for recognizing playbooks, tasks and variables is preset for the following directory structure:

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

Alternatively, playbooks can also be stored directly in the playbooks folder.

If an IntelliJ project consists of only one Ansible role, i.e. the tasks, handlers, defaults, … folders are in the IntelliJ project folder, the project folder must be selected for the roles.

The configuration dialog contains four categories:

  • for inventories
  • for playbooks
  • for roles
  • for global exceptions

Configuration dialog for Ansible file detection

To the root folder categories Playbooks and Roles additional exceptions can/must be made for variables and depending on the category Playbook / Role.

Playbooks folder can contain

  • task files and
  • variable files

Roles folders can contain

  • playbook files and
  • variables files

Global Ignores can contain

  • exceptions for any YAML files that are not Ansible files - e.g. configuration files for CI systems.

In the respective configuration tabs the exceptions are defined with simple file patterns (* as placeholder for any char).

File Type Pattern Reset Configuration

The OrchidE plugin default settings can be restored via the toolbar button (Reset Button) in the respective detail settings.


Syntax Highlighting

The highlighting for OrchidE can be changed in the Color-Scheme settings of IntelliJ.

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

OrchidE color scheme settings dialog.

Code Completion Settings

OrchidE supports code completion and text parsing for different Ansible versions. The Ansible version to be used depends on the installed OrchidE builder package.

Within IntelliJ, the latest OrchidE Builder package can be downloaded, with the latest collections from Ansible Galaxy at the time of creation.

Packages for a specific Ansible version can be downloaded from the OrchidE Builder GitHub page.

To improve the overview during code completion, individual Ansible Module categories can be hidden. For this purpose, select only the modules to use in the settings.

Select Ansible version for code completion

As of OrchidE 2023.1.4, only the “collections” setting is supported.

(File | Settings | Languages & Frameworks | OrchidE)

OrchidE code completion settings version dialog.

Configuration for Ansible <collections>

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

OrchidE code completion settings dialog - collections.

For each collection you can also specify whether the full qualified collection name or only the module name (without namespace) is suggested.

Available options are:

  • FQCN only: use always only full qualified collection name
  • Name only: use always only the module name without namespace
  • Show FQCN and name: show always both
  • Based on collection keyword: nshow only the module name if the collection is listed in the search path (keyword: collections:), otherwise both will be displayed.

OrchidE code completion settings dialog - collections.

The default configuration uses Based on collection keyword

Configuration for Ansible <=2.9 (obsolete)

No longer available since OrchidE 2023.1.4.

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

OrchidE code completion settings dialog - classic.

Quick Documentation

OrchidE displays the documentation for Ansible modules, module arguments and Ansible keywords in the Quick Documentation Popup/Tool Window.

The documentation is not part of OrchidE and must be installed separately. You have to set the download directory in the extension settings and install the current definition package.

Installation of OrchidE Builder Definition File

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

OrchidE extension settings dialog.

More settings of quick documentation can be found in the IntelliJ documentation of quick documentation and documentation tool window.

Inlay Hints für Jinja Variablen

OrchidE can display the value(s) of the reference as inlay hints in the editor for most Jinja variables.

OrchidE editor with inlay hints.

In the settings the inlay hints can be switched off and on and the presentation of the inlay can be adapted:

(File | Settings | Editor | Inlay hints)

Ansible inlay hints settings.

Code Completion

OrchidE supports IntelliJ code completion via Tab and Enter key. Code completion is supported for

  • vars (in Jinja2 templates),
  • group and host vars in inventory variable files,
  • roles,
  • modules,
  • module arguments
  • keywords
  • registered vars (within same file),
  • set_fact vars (within same file)
  • tags (within same file)
  • variables specified in argument_spec file (within playbook includes and jinja templates in same role)

When completing modules with the Enter key, all mandatory arguments are also inserted.

When completing group/host variables with the Enter key, the description from the argument spec definition will also be inserted. If there is no argument spec available, comments from the role defaults variable definition is used.

Ansible Facts

Additionally, an extract of the typical facts variables is supported. The code completion of facts is a ‘suggestion’ of OrchidE. Whether a facts variable is also available at runtime depends on the concrete configuration at the time of execution.

Code Completion with values

For keywords and module arguments there are additional suggestions with values.

Code completion with values

For boolean values the suggestions can be adjusted in the configuration.

(File | Settings | Editor | OrchidE )

Editor Konfiguration code completion

Inventory group and host variables

For code completion of variables either an annotation is needed, or a playbook with roles and suitable inventory entry.

In the variant with annotation there are suggestions from the role of the metadata (argument spec) and the variables in defaults.

In the variant with playbook suggestions are made from all included roles.

The annotation has the following format

#@role::<role name> 

The trigger for code completion is #@ at the beginning of the line.

For all following lines, the code completion (and quick documentation) only uses this role.

Code completion of group and host variables

The use of OrchidE’s role annotation is recommended:

  • so there are no name conflicts when resolving the documentation,
  • the code completion shows only variables for this role,
  • the navigation to the argument spec needs this information - without annotation navigation is not possible

With the Intention and Inspection ‘Role Annotation’ it is easy to add the annotation afterwards.

Role Annotation Inspection & Intention

Additionally, there is folding for the annotation, so whole blocks of variables can be shown and hidden for a role.

Folding role annotation

Depending on which keyboard key (Enter / Tab) is used, different contents are inserted:

When using the argument specs file:

  • Tab-Completion: variable will be inserted
  • Enter-Completion: variable and description will be inserted

When using the defaults file:

  • Tab-Completion: variable will be inserted. For dictionaries, whole structure will be inserted.
  • Enter-Completion: the variable and comments (up to the first empty line) above the variable are inserted. For dictionaries, all substructures are also inserted.

Code Completion for file names

There are suggestions of files for the Ansible modules include_tasks, import_tasks and template.

For the argument src of the template task you can additionally set which files should be displayed:

  • also files relative to the playbook,
  • only files in templates folder,
  • only files with the file extension *.j2 or all files.

Configuration code completion for template -src argument

Project View

The project view for Ansible (Ansible Structure) presents the playbooks, roles and inventory groups and hosts with the associated group vars / host vars in a compact view to facilitate navigation.

Project view selection

Project view selection

To use the project view “Ansible Structure”, root folders for inventory, playbooks and roles must be set in the configuration (File | Settings | Languages & Frameworks | OrchidE | Ansible Folder Mapping).

The view is divided into three parts:

  • Inventories
  • Playbooks
  • Roles

Inventories

The inventory structure is divided into

  • Default groups (all and ungrouped)
  • group of groups
  • groups
  • hosts
  • associated variables files

Project view shows inventory entries of inventory files in INI and YAML format.

Project view inventory

Playbooks

Project view playbooks

Roles

The Roles structure is represented as a virtual structure based on tasks/main.yml:

  • role (tasks/main.yml)
  • associated other tasks files
  • handlers
  • default and group vars
  • further folders and files

Project view roles

Configuration

Project view configuration

For the Project View “Ansible Structure”, the Project View settings

  • Sort by type and
  • Folder Always On Top

should be enabled. This shows the logical structure as intended by OrchidE.

recommended project view configuration


To use the Project View “Ansible Structure” the root folders to Playbooks, Roles and Inventories must be set in the Settings (Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping) must be configured.

OrchidE supports navigation to the declaration of variables and to the implementation of import statements. This function is linked to the IntelliJ function “Go to Declaration (Shortcuts: Ctrl + B, + B).

Supported are

  • Variables in Jinja2 templates
  • Import tasks
    • import_tasks
    • import_playbook
    • import_role -> name
    • include_tasks
    • include_tasks -> file
  • Template task
    • src argument with static file name
  • Keyword vars_files
  • References in playbook roles
  • Keyword hosts in playbooks

Symbols navigation support go to declaration OrchidE Navigation support go to declaration


Navigation is also supported for simple dynamic imports (file names with Jinja2 templates)

OrchidE Navigation support of dynamic includes

Navigation is possible for the following notation:

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

Examples:

  - 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

Note to dynamic includes:

For dynamic includes the OrchidE-Builder Extension is required. The list of supported variables can be found on GitHub.

When using Jinja2 templates, navigation to the destination file only works if the cursor is outside the Jinja2 template and no folder.

(The include reference is overwritten by the embedded Jinja2 reference and therefore cannot be used for navigation when using Jinja2 templates)

OrchidE supports navigation to playbooks and roles. These functions are linked to the IntelliJ function “Go to class”. (Shortcuts: Ctrl + N, + O)

OrchidE Navigation support go to playbook and roles


OrchidE supports navigation to inventory group and host entries and their associated files with group/host variables. (Shortcuts: Ctrl + ⇧Shift + O, then I, + ⇧Shift + O, then I or via Menü | Navigate | Inventory).

Search for and navigation to host and group names is currently available for inventory files in INI format. Also, the INI plugin (ini4idea) from JetBrains must be installed. (YAML for inventory files is not supported).

For this feature, the root folders for playbooks, roles and inventories must be set in the Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping.

Search dialog for inventory entries

OrchidE search for inventory entries


OrchidE supports direct navigation to variables. These functions are linked to the IntelliJ function “Go to symbols”. (Shortcuts: Ctrl + Alt + ⇧Shift + N, + ⌥Option + O)

OrchidE Navigation support go to variable


OrchidE supports navigation to next/previous Ansible tasks in playbooks and tasks files. This function is available by the IntelliJ action “Next/Previous Method” (Shortcuts: Alt + Up/Down, Control + Up/Down).

OrchidE Navigation support go to task

OrchidE supports navigation to related items for

  • host and group entries in inventory files in INI and YAML format,
  • playbooks,
  • roles,
  • and group/host variables.

The navigation takes place via Navigate ➞ Related Symbol (Ctrl + Alt + Home, Ctrl + + Up)

OrchidE Navigation support for related symbols

Navigation is supported:

from playbooks

  • to vars files
  • to roles (-> tasks/main.yml)
  • to group/host variables
  • to inventory entries

from roles (tasks, vars, defaults)

  • to all files of the role
  • to playbooks, including this role
  • to group/host variables (via included role in playbook)
  • to inventory entries (via included role in playbook)

from inventory entries (cursor must be on entry)

  • to playbooks
  • to group/host variables

from group/host variables

  • to playbooks
  • to roles (via playbook)
  • to inventory entries

OrchidE supports navigation to variable declaration in roles argument specs and defaults variables from variables in inventory files.

Navigation is done via the IntelliJ function “Go to Declaration”. (Shortcuts: Ctrl + B, + B).

OrchidE navigation support for group and host variables

A role annotation must be set for navigation to work.
OrchidE role annotation

Inspections

All OrchidE Inspections can be configured or disabled via the settings (Settings | Editor | Inspections | Ansible)

Deprecation

OrchidE can check if a module is deprecated and marks it in the editor and code completion popup. The check for deprecated is performed against the highest version of Ansible supported by OrchidE. Even if the version compatibility is set to an older version of Ansible, the check will be done against the highest supported version of Ansible and all deprecated modules will be displayed.

Check for undefined variables

OrchidE checks if the resolution of a variable in a Jinja2 string is possible (for Playbooks, Roles and Variables). The check considers all variables with the current IntelliJ project - i.e. whether the variable is available at runtime depends on the hosts’ definition. The check in OrchidE is a generic check whether a variable is defined (in the role and in the complete inventory) and may differ from the runtime.

This Inspection checks if a variable in defined at any location of

  • facts (inside roles set with set_facts)
  • role variables (vars)
  • role default variables (defaults)
  • host and group vars
  • variables set by the keyword register

OrchidE can resolve variables set with set_fact and register within a role using the include-/import_tasks modules. (supported are include/import paths as described in dynamic imports)

The QuickFix “Suppress for this variable” can be used to suppress the check for individual occurrence.

This Inspection can be adjusted or turned off via the configuration.

Check for unknown Ansible keywords

This check consists of two variants: one for role calls and one for all other keywords.

OrchidE checks if keywords in playbooks, tasks and blocks are correct and marks unknown (wrong) keywords.

For role keywords a warning is displayed with the default setting, because role calls could also contain variables. Best practice is to use variables with the keyword vars. Then the check can be switched to show an error for unknown keywords.

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

Check for unknown Ansible module arguments

OrchidE checks if all module arguments in tasks are correct and marks unknown / wrong arguments.

This check is fully supported starting with Ansible 2.8. For older Ansible versions aliases of arguments are not supported and are displayed as errors.

Some modules, like set_fact, allow arbitrary arguments by design. Such modules are excluded from the check.

The list of excluded modules:

  • set_fact
  • local_action

Further modules can be added via own definition files. For details see Extending OrchidE

Check for type for keywords und module arguments

OrchidE checks the values of keywords and module arguments for these types

  • boolean,
  • integer,
  • string,
  • selection lists.

Also supported is the use of Jinja variables with simple references, e.g.

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

The definitions are used from the collection and keyword documentation. Own definition from argument_specs are currently not supported.

Duplicate keys check

OrchidE checks if YAML keys are duplicated below a key.

Check for missing include files

OrchidE checks if referenced files are available for various Ansible modules.

Following modules are supported

  • all import/include_* modules
  • the src-argument of the template module
  • the keyword vars_file in playbooks

In order to search all Ansible search paths, it is necessary that the root folders to playbooks are set in the Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping*.

Check that values of group/host variables have the correct type

OrchidE checks the values of variables for these types

  • boolean
  • integer
  • strings
  • dictionaries.

The use of Jinja variables with simple references is also supported.

Check for uniqueness of task names.

OrchidE checks not fully qualified task names (without namespace) for ambiguity, and shows a warning if the task is available in multiple namespaces.

If the playbook (collections keyword) or role (collections keyword in the meta file) has a list of namespaces, ambiguity checking is supported based on that list.

Inspection Unique Tasks

Intentions

Intention to create Ansible variables

OrchidE offers the possibility to create Ansible variables directly from the editor when using ansible variables in Jinja2 templates.

Creating variables via intention

Within a role an Ansible defaults or vars variable can be created. If no variable file exist, a new file is created.

Generally, the variable can always be added to group vars or host vars. When creating a new variable in host/group vars files, the file must already exist.

File chooser dialog for intention

Intention for creating missing files

With this intention, missing files can be created directly.

Supported includes are

  • all import/include_* modules
  • the src-argument of the template module
  • the keyword vars_file in playbooks

  • Intention dialog create new file

Refactoring

Refactoring of values and strings

In roles values and strings can be converted into variables - either in roles default variables (to defaults folder -> main.yml) or static variables (to vars-folder -> main.yml).

The Context menu | Refactor | Extract | Variable (to defaults) or Refactor | Extract | Constant (to vars) extracts the current position. If no text is selected, the complete string or value is converted into a variable.

If the text exists several times in the file, all places are replaced.

The refactoring is only done in the current opened file, a refactoring for the whole project is not supported.

Moving tasks

Ansible tasks can be easily moved up/down in playbooks and tasks files using IntelliJ’s Move Statement Up/Down function.

Movement of Ansible Task

Editor

Braces and Jinja variables

OrchidE supports the automatic insertion of closing braces.

Additionally the Jinja bracket ({{) is supported. Possibly needed “ will be added.

Indentation after ‘Enter’

After “Enter”, OrchidE will automatically insert indentation and/or the hyphen for lists.

The backspace key will undo the indentation. To do this, the Smart Key setting Unindent on Backspace must be activated. (File | Settings | Editor | General | Smart Keys - Section Enter)

Note: there is no difference between the two indentation options in OrchidE.

The enter key can also be used as an option for unindent on blank lines. Instead of a new line, the indentation is then reset. By default this behaviour is deactivated and must be activated via (File | Settings | Editor | OrchidE ).

Editor tab names

Tasks of a role are typically always stored in a main.yml file. For better clarity, OrchidE replaces the names in the editors tab with the name of the role or playbook.

Customize title for IntelliJ editor tabs

This behavior can be set in the configuration

(File | Settings | Editor | OrchidE )

Editor Configuration

Action New File

OrchidE can create Ansible files (and associated folders) context-independently for playbooks, roles, and inventory variable files.

New file dialog for Ansible files

The New file action is based on the root folder for playbooks, roles and inventories from the settings (Settings ➞ Languages & Frameworks ➞ OrchidE ➞ Ansible Folder Mapping).

The following types can be created:

  • Roles: creates a folder for the role and depending on the selection an initial file tasks/main.<ext> or meta/main.<ext>.
  • Playbooks: creates a playbook file or folder with a file main.<ext>.
  • Group var: creates an inventory group var file in <inventory>/group_vars folder. Optionally as a folder with default filename.
  • Host var: creates an inventory host var file in <inventory>/host_vars folder.

A selection is only offered if the associated root folders are configured.

The default file name for folder-based group var files and the preferred YAML file extension can be configured in the settings.

(File | Settings | Editor | OrchidE).

New file dialog for Ansible files


Copy & Paste Support

When copying and pasting Ansible code, the pasted code is indented accordingly.

Automatic indentation of pasted code is supported for

  • Tasks,
  • modules,
  • module arguments,
  • and variables.

If the copied text is to be pasted unchanged, Paste as Plain Text can be used.

Other code parts are pasted with the original indentation.

When text is selected and copied in column mode, the indentation is not adjusted. The copied text is pasted unchanged.

Jinja2 template support

Supported Features

OrchidE has generic support for Jinja2 templates. With generic support the content is plain text. and Jinja2 expressions and statements can be used.

  • For Jinja2 expressions and statements
  • For Ansible variables, the following is also supported if the variable is used as a simple template pattern (e.g. “{{ akey }}”).
    • code completion,
    • the goto declaration function and
    • inspections

Other Jinja2 syntax features are not supported, such as formatting, variable recognition by set methods, variables in loops, …)

As with playbooks and roles OrchidE checks if the used variables were declared in a hosts/group variable within the IntelliJ project and otherwise marks the variable with a warning.

For the file types XML, JSON and properties the language features of the respective plugins are supported (syntax highlighting, parsing, inspections, comments, formatting (not for properties)).

OrchidE uses the file extension *.j2 to recognize Jinja2 templates:

  • *.xml.j2 for XML files
  • *.json.j2 for JSON files
  • *.yaml/yml.j2 for YAML files
  • *.properties.j2 for properties files
  • *.j2 for all other file types - interpreted as plain text files.

Limitations in base languages of Jinja2 templates

Property and YAML files

The inspections

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

of the plugins can lead to wrong results when using Jinja2 template expressions/statements.

Support for Ansible Vault

OrchidE can decrypt Ansible Vault files and encrypt new Vault files. It can also encrypt and decrypt individual values of variables. Vault IDs are also supported.

Decrypt Ansible Vault file


Configuration (optional)

Under Settings Languages & Frameworks OrchidE, an Ansible configuration file (ansible.cfg) can be specified.

OrchidE uses the setting vault_password_file to decrypt Ansible vaults.

OrchidE supports the reading of plain text password files. Executable files are not supported.

When environment variables are used in the ‘ansible.cfg’, a simple variable substitution is performed, advanced shell variable processing is not supported. To be able to use environment variables, they must be known to the IntelliJ platform process.

When an entry for an Ansible vault id is found in the IntelliJ password manager, this is always used and the Ansible configuration is not used.

Ansible vaults are automatically decrypted when opened in the editor if an appropriate password is available.

Opening a vault

If a Vault file is opened in the editor, the content can be decrypted via the Editor - Context - Menu ➞ OrchidE ➞ Decrypt Vault. After that, the editor behaves like any other opened file with variables:

  • Code completion for Jinja2 variables is available
  • The inspection undefined variables detects the variables
  • Navigation to declared variables from other files is possible

When saving the file, the content is encrypted in the background. During/after this, the editor content is still available in a readable form.

To manage the passwords OrchidE uses the integrated password management of IntelliJ. In the password dialog you can specify whether passwords should be stored persistently or only for the IDE session.

Creating a new vault

A new Vault file can be created for each file with variables via the Editor - Context - Menu ➞ OrchidE ➞ Encrypt Vault. Only files that are recognized by OrchidE as variable files can be encrypted (file type settings and pattern matching must be correct).

In the password dialog you can enter a Vault id and the password. After that the file is encrypted and shown in the editor (encrypted). To continue editing the file, a decrypt is necessary.

Files that are already a Vault cannot be encrypted, but are automatically encrypted each time they are saved.

Set Vault Id

For existing Vault files the Vault Id can be reset.

The corresponding command is available in the editor context menu: Menu ➞ OrchidE ➞ Set Vault Id.

Set vault id

Change the password for a Vault.

A new password can be set for existing Vault files. It does not matter whether the Vault file is displayed encrypted or unencrypted in the editor.

The corresponding command can be reached in the editor context menu: Menu ➞ OrchidE ➞ Change Password.

Change password menu for Ansible Vault files

Encrypting and decrypting Ansible variables

Values of Ansible variables can be encrypted individually in the editor.

If the cursor is on a variable value, the value can be encrypted via the Editor - Context - Menu ➞ OrchidE ➞ Encrypt Value. From the same menu, encrypted values can be decrypted.

Encrypt variable value

Other Functions

If Ansible variables from dynamic inventories or the command line are used in playbooks and roles, these variables can be created in OrchidE. These variables are then used during code completion and the inspection “Undefined Variables”.

Extra Vars settings dialog

“Extra variables “ can also be created with the quick fix “Create extra vars variable “ of the Inspection “Undefined Variable “ directly from within the editor.

Quick Fix create extra vars variable

The additionally created variables are stored in the IntelliJ .idea project folder in the file orchide-extravars.xml and can be checked in to version control system.

Extending OrchidE

OrchidE definition file builder

The OrchidE definition file builder is a command-line tool to create definitions for OrchidE. This definition includes meta data for the parser, code completion and inspections in OrchidE to detect Ansible terms.

This can be used to extended OrchidE with support for further modules from Ansible Galaxy collections or any custom collections.

The builder creates JSON files from Ansible Galaxy collections which contain definitions of modules with all attributes. OrchidE uses these JSON files to parse Ansible playbooks and roles, present suggestions for code completion and check for valid code.

OrchidE comes with a large number of definitions for the most popular Ansible collections. If collections or general definitions are missing or out-of-date, you can build your own package with the builder and integrate it into OrchidE.

The Builder, updated definition packages and more details are available on GitHub

Limitations

OrchidE’s Language Parser was written from scratch for playbooks and roles. Full support for YAML is not available.

It is recommended to edit YAML files with the integrated YAML editor. Are there YAML files within the file structure supported by OrchidE, the language support can be switched via context menu between YAML and Ansible support.

Mark file as language type

Outside the supported file structure, YAML files are always opened with the default editor of the IDE. (If no changes are made in the File Associations for the yml file extension.)

Limited and unsupported YAML functions

  • Only the Ansible tags !unsafe and !vault are supported.
  • Flow styles/flow collections are only supported to a limited extent (1st level)
  • Complex mapping key (?_) is not supported
  • YAML Directives are not supported

Restrictions for IntelliJ platform 2019.1 and 2019.2 (sundowned versions without support)

If there is more than one open project with IntelliJ Platform versions 2019.1 and 2019.2, the “Close Project” button must be pressed twice, if there are unsaved vault files.