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
OrchidE runs on the IntelliJ platform and requires one of these IDEs
IntelliJ IDEs:
in version 2023.1 or later.
OrchidE is distributed via the IntelliJ Marketplace and can be installed directly via the plugin configuration.
Deprecation
Support for IntelliJ Platform 2023.1 is deprecated and will end with the launch of the EAP for IntelliJ version 2025.1.
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.
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.
(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:
- manually download older version from the IntelliJ Plugin Repository
- open the configuration dialog via the menu File | Settings | Plugins.
- select the command “Install Plugin from disk” via the setting symbol () 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:
- Menu → Help → Register
- Select OrchidE and choose Evaluate for free.
- Press Evaluate to start the trial period.
An info appears with “Free evaluation: 30 days left.”
- 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
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 ()
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)
.
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
Obsolete as of OrchidE 2023.1.4.
(File | Settings | Languages & Frameworks | OrchidE)
.
Configuration for Ansible <collections>
(File | Settings | Languages & Frameworks | OrchidE | 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.
.
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)
.
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)
.
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.
.
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)
.
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.
For boolean values the suggestions can be adjusted in the configuration.
(File | Settings | Editor | OrchidE )
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
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.
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.
Additionally, there is folding for the annotation, so whole blocks of variables can be shown and hidden for a role.
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.
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
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.
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
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.
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.
Navigation
Navigation for import and variable references
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
Navigation for dynamic imports
Navigation is also supported for simple dynamic imports (file names with Jinja2 templates)
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)
Note to flow style:
The sequence flow style of YAML is not supported.
- include_tasks: { file: tasks.yml }
Navigation to playbooks and roles
OrchidE supports navigation to playbooks and roles. These functions are linked to the IntelliJ function “Go to class”.
(Shortcuts: Ctrl + N, ⌘ + O)
Navigation to inventory entries
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
Navigation to variables
OrchidE supports direct navigation to variables. These functions are linked to the IntelliJ function “Go to symbols”.
(Shortcuts: Ctrl + Alt + ⇧Shift + N, ⌘ + ⌥Option + O)
Navigation to Ansible tasks
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 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)
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
Navigation from inventory variables files to definition in role` argument specs files.
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).
A role annotation must be set for navigation to work.
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:
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.
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.
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.
Intention for creating missing files
With this intention, missing files can be created directly.
Supported includes are
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.
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.
This behavior can be set in the configuration
(File | Settings | Editor | OrchidE )
Action New File
OrchidE can create Ansible files (and associated folders) context-independently for playbooks, roles, and inventory variable 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).
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.
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.
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.
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.
Other Functions
Additional variables (from the command line)
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 variables “ can also be created with the quick fix “Create extra vars variable “ of the Inspection
“Undefined Variable “ directly from within the editor.
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.
Language Injection for Ansible Shell Module
Script code in the Ansible shell module can be edited with the associated IntelliJ plugin.
OrchidE supports the following languages/plugins:
The integration in OrchidE supports most of the standard functions of IntelliJ.
Some extra functions of the plugins are not supported in some cases.
OrchidE recognizes the language of the code by a language annotation, the keyword executable and a few SheBang lines.
If several entries are available, the following priority list is used for selection (the highest priority first)
- Annotation
- Keyword executable
- Shebang
The correct annotation can be created using the quick fix of the inspection “Shell module language injection” (see settings: File | Settings | Editor | Inspection | Ansible)
Alias annotation for inventory variables
With the alias annotation of OrchidE you get quick documentation, code completion, and navigation for
argument-spec variables that are used indirectly.
This can be used to call a role in a playbook several times with different values, e.g., to install several
instances of a service on one node and still have OrchidE’s editor functions.
Playbook example
- name: Sample Aliases
hosts: alias-sample
roles:
- role: service-instance
vars:
install_folder: "{{
alias_sample_instance_1 }}"
- role: service-instance
vars:
install_folder: "{{ alias_sample_instance_2 }}"
And the corresponding inventory definition:
If the alias annotation is specified, OrchidE uses the argument-spec definition of the role to offer
editor functions such as quick documentation, navigation, and code completion.
To resolve the alias annotation, OrchidE requires an inventory entry corresponding to the hosts keyword in the playbook and associated host/group variable files.
For the above example, an inventory entry (Ini format) with
[alias-sample]
localhost
And inventory files
<Inventory>/group_vars/alias-sample/myvars.yml
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.
If there are YAML files in the OrchidE file structure that are detected as an Ansible file type, the file type can be changed using the context menu.
Use the standard IntelliJ “Override File Type” function to change the file type.
Alternatively, the file can be added to the OrchidE’s global ignore list in the settings.
(File | Settings | Languages & Frameworks | OrchidE | Ansible Folder Mapping | Global Ignores).
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