From ac570e659a78f14fffb205e29fb0f96be1eef161 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 14 Jul 2025 14:43:16 -0400 Subject: [PATCH 1/8] add details on some plugin options --- .../rst/dev_guide/developing_plugins.rst | 37 ++++++++++++++++--- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index d45ac41a397..ce821ae26b8 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -63,18 +63,45 @@ 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_OF_ENV_VAR ini: - - section: section_of_ansible.cfg_where_this_config_option_is_defined - key: key_used_in_ansible.cfg + - section: mycollection_section_of_ansible.cfg_where_this_config_option_is_defined + key: mycollection_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 first 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. + + +**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. + This allows plugins to be configured via ansible.cfg. + + +**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. + Variables follow Ansible's variable precedence rules. + This allows plugins to be configured via Ansible variables. + + To access the configuration settings in your plugin, use ``self.get_option()``. Some plugin types handle this differently: From e41726b77932884e2cc0512b378e1fd57377ba42 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 15 Jul 2025 16:34:37 -0400 Subject: [PATCH 2/8] revise based on feedback --- .../rst/dev_guide/developing_plugins.rst | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index ce821ae26b8..be96ff36b25 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -82,7 +82,7 @@ The supported configuration fields are: 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 first environment variable in the list takes precedence if multiple are set. + The last 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. @@ -90,6 +90,7 @@ The supported configuration fields are: 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 configuration setting in the list takes precedence if multiple are set. This allows plugins to be configured via ansible.cfg. @@ -98,9 +99,29 @@ The supported configuration fields are: 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 variable in the list takes precedence if multiple are set. Variables follow Ansible's variable precedence rules. This allows plugins to be configured via Ansible variables. - + +.. _general_plugin_precedence_rules: + +General precedence rules +------------------------ + + The precedence rules for configuration sources are listed below,starting with the highest precedence values: + +* Direct specification +* Ansible variables +* Keywords +* CLI settings +* Environment variables +* Values defined in ``ansible.cfg`` +* Option's default value, if present. None if there is no default. + +.. _accessing_configuration_settings: + +Accessing configuration settings +-------------------------------- To access the configuration settings in your plugin, use ``self.get_option()``. Some plugin types handle this differently: From ad0002234178f36fa394df62338977e6e2076c25 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 16 Jul 2025 09:15:15 -0400 Subject: [PATCH 3/8] Apply suggestions from code review Co-authored-by: Felix Fontein --- docs/docsite/rst/dev_guide/developing_plugins.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index be96ff36b25..3e5945739f7 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -82,7 +82,7 @@ The supported configuration fields are: 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 environment variable in the list takes precedence if multiple are set. + 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. @@ -90,7 +90,7 @@ The supported configuration fields are: 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 configuration setting in the list takes precedence if multiple are set. + The last set configuration setting in the list takes precedence if multiple are set. This allows plugins to be configured via ansible.cfg. @@ -99,7 +99,7 @@ The supported configuration fields are: 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 variable in the list takes precedence if multiple are set. + 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 via Ansible variables. @@ -108,15 +108,13 @@ The supported configuration fields are: General precedence rules ------------------------ - The precedence rules for configuration sources are listed below,starting with the highest precedence values: + The precedence rules for configuration sources are listed below, starting with the highest precedence values: -* Direct specification -* Ansible variables * Keywords * CLI settings * Environment variables * Values defined in ``ansible.cfg`` -* Option's default value, if present. None if there is no default. +* Option's default value, if present. ``None`` if there is no default. .. _accessing_configuration_settings: From 07c6fa1b3a039a179d042471590480ab786e5a54 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Wed, 16 Jul 2025 09:16:48 -0400 Subject: [PATCH 4/8] Update docs/docsite/rst/dev_guide/developing_plugins.rst --- docs/docsite/rst/dev_guide/developing_plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 3e5945739f7..ddb875da93c 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -114,7 +114,7 @@ General precedence rules * CLI settings * Environment variables * Values defined in ``ansible.cfg`` -* Option's default value, if present. ``None`` if there is no default. +* Option's default value, if present. .. _accessing_configuration_settings: From 63240cd1b5a936cdd481e21c57e3f7afb01df6fd Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 21 Jul 2025 12:42:27 -0400 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Don Naro --- docs/docsite/rst/dev_guide/developing_plugins.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index ddb875da93c..77892e76bb5 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -91,7 +91,7 @@ The supported configuration fields are: 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 via ansible.cfg. + This allows plugins to be configured with ansible.cfg. **vars** @@ -101,7 +101,7 @@ The supported configuration fields are: 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 via Ansible variables. + This allows plugins to be configured with Ansible variables. .. _general_plugin_precedence_rules: @@ -114,7 +114,7 @@ General precedence rules * CLI settings * Environment variables * Values defined in ``ansible.cfg`` -* Option's default value, if present. +* Default value for the option, if present. .. _accessing_configuration_settings: From 3f635d3a94c03c945cbfacad3f279b2d41e97715 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 21 Jul 2025 13:10:26 -0400 Subject: [PATCH 6/8] add examples --- docs/docsite/rst/dev_guide/developing_plugins.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 77892e76bb5..1f56d5bb559 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -84,6 +84,7 @@ The supported configuration fields are: 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** @@ -92,6 +93,7 @@ The supported configuration fields are: 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** @@ -102,6 +104,7 @@ The supported configuration fields are: 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: From 428e7cd31adab9a9af770d30846d0710e6465e6a Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Tue, 22 Jul 2025 07:47:06 -0400 Subject: [PATCH 7/8] Update docs/docsite/rst/dev_guide/developing_plugins.rst Co-authored-by: Felix Fontein --- docs/docsite/rst/dev_guide/developing_plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 1f56d5bb559..724c19a3a45 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -66,7 +66,7 @@ To define configurable options for your plugin, describe them in the ``DOCUMENTA - name: MYCOLLECTION_NAME_OF_ENV_VAR ini: - section: mycollection_section_of_ansible.cfg_where_this_config_option_is_defined - key: mycollection_key_used_in_ansible.cfg + key: key_used_in_ansible.cfg vars: - name: mycollection_name_of_ansible_var - name: mycollection_name_of_second_var From 1c1fde7217b4610a9287723bc7e6fc91dd29322d Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Thu, 24 Jul 2025 09:19:24 -0400 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Andrew Klychkov --- docs/docsite/rst/dev_guide/developing_plugins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_plugins.rst b/docs/docsite/rst/dev_guide/developing_plugins.rst index 724c19a3a45..8821c8d9948 100644 --- a/docs/docsite/rst/dev_guide/developing_plugins.rst +++ b/docs/docsite/rst/dev_guide/developing_plugins.rst @@ -63,7 +63,7 @@ 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: MYCOLLECTION_NAME_OF_ENV_VAR + - name: MYCOLLECTION_NAME_ENV_VAR_NAME ini: - section: mycollection_section_of_ansible.cfg_where_this_config_option_is_defined key: key_used_in_ansible.cfg @@ -115,7 +115,7 @@ General precedence rules * Keywords * CLI settings -* Environment variables +* Environment variables (``env``) * Values defined in ``ansible.cfg`` * Default value for the option, if present.