From 02ccc48d8c69f6f20a7e42a3b1e64fb49459abbe Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 24 Jul 2025 09:23:53 -0400 Subject: [PATCH] add details on some plugin options - AI-assisted (#2813) * add details on some plugin options * revise based on feedback * Apply suggestions from code review Co-authored-by: Felix Fontein * Update docs/docsite/rst/dev_guide/developing_plugins.rst * Apply suggestions from code review Co-authored-by: Don Naro * add examples * Update docs/docsite/rst/dev_guide/developing_plugins.rst Co-authored-by: Felix Fontein * Apply suggestions from code review Co-authored-by: Andrew Klychkov --------- Co-authored-by: Felix Fontein Co-authored-by: Don Naro Co-authored-by: Andrew Klychkov (cherry picked from commit caa2399fa45dfe3165646d325f3c434962551a50) --- .../rst/dev_guide/developing_plugins.rst | 57 +++++++++++++++++-- 1 file changed, 53 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 9783d6df2ea..3be04aaa615 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -63,18 +63,67 @@ To define configurable options for your plugin, describe them in the ``DOCUMENTA description: describe this config option default: default value for this config option env: - - name: NAME_OF_ENV_VAR + - name: MYCOLLECTION_NAME_ENV_VAR_NAME ini: - - section: section_of_ansible.cfg_where_this_config_option_is_defined + - section: mycollection_section_of_ansible.cfg_where_this_config_option_is_defined key: key_used_in_ansible.cfg vars: - - name: name_of_ansible_var - - name: name_of_second_var + - name: mycollection_name_of_ansible_var + - name: mycollection_name_of_second_var version_added: X.x required: True/False type: boolean/float/integer/list/none/path/pathlist/pathspec/string/tmppath version_added: X.x +The supported configuration fields are: + +**env** + List of environment variables that can be used to set this option. + Each entry includes a ``name`` field specifying the environment variable name. + The name should be in uppercase and should be prefixed with the collection name. + Multiple environment variables can be listed for the same option. + The last set environment variable in the list takes precedence if multiple are set. + This is commonly used for plugins (especially inventory plugins) to allow configuration through environment variables. + Examples: ``VMWARE_PORT``, ``GRAFANA_PASSWORD`` + + +**ini** + List of configuration file settings that can be used to set this option. + Each entry includes a ``section`` field for the configuration file section and a ``key`` field for the configuration key. Both should be in lowercase and should be prefixed with the collection name. + Multiple configuration settings can be listed for the same option. + The last set configuration setting in the list takes precedence if multiple are set. + This allows plugins to be configured with ansible.cfg. + Example: ``grafana_password`` + + +**vars** + List of Ansible variables that can be used to set this option. + Each entry includes a ``name`` field specifying the variable name. + The name should be in lowercase and should be prefixed with the collection name. + Multiple variables can be listed for the same option. + The last set variable in the list takes precedence if multiple are set. + Variables follow Ansible's variable precedence rules. + This allows plugins to be configured with Ansible variables. + Example: ``ansible_vmware_port`` + +.. _general_plugin_precedence_rules: + +General precedence rules +------------------------ + + The precedence rules for configuration sources are listed below, starting with the highest precedence values: + +* Keywords +* CLI settings +* Environment variables (``env``) +* Values defined in ``ansible.cfg`` +* Default value for the option, if present. + +.. _accessing_configuration_settings: + +Accessing configuration settings +-------------------------------- + To access the configuration settings in your plugin, use ``self.get_option()``. Some plugin types handle this differently: