config: singular ANSIBLE_COLLECTIONS_PATH (#70007)

* config: singular ANSIBLE_COLLECTIONS_PATH

Every other *_PATH setting in ansible is singular, and the traditional
$PATH variable is also singular despite containing a list of
directories.  Let's be consistent both internally and with POSIX
tradition.

* update all ANSIBLE_COLLECTIONS_PATHS env references to be singular

* deprecate plural ANSIBLE_COLLECTIONS_PATHS setting

changelogs/fragments/singular-collection-path.yml

@@ -0,0 +1,3 @@
+minor_changes:
+- config - accept singular version of ``collections_path`` ini setting and
+  ``ANSIBLE_COLLECTIONS_PATH`` environment variable setting

lib/ansible/config/base.yml

@@ -233,9 +233,23 @@ COLLECTIONS_PATHS:
   default: ~/.ansible/collections:/usr/share/ansible/collections
   type: pathspec
   env:
-  - {name: ANSIBLE_COLLECTIONS_PATHS}
+  - name: ANSIBLE_COLLECTIONS_PATHS
+    deprecated:
+      why: all PATH-type options are singular PATH
+      version: "2.14"
+      alternatives: the "ANSIBLE_COLLECTIONS_PATH" environment variable
+  - name: ANSIBLE_COLLECTIONS_PATH
+    version_added: '2.10'
   ini:
-  - {key: collections_paths, section: defaults}
+  - key: collections_paths
+    section: defaults
+    deprecated:
+      why: all path-type options are singular path
+      version: "2.14"
+      alternatives: the "collections_path" ini setting
+  - key: collections_path
+    section: defaults
+    version_added: '2.10'
 COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH:
   name: Defines behavior when loading a collection that does not support the current Ansible version
   description:

lib/ansible/executor/task_executor.py

@@ -1092,7 +1092,7 @@ def start_connection(play_context, variables, task_uuid):
         # can.
         'ANSIBLE_BECOME_PLUGINS': become_loader.print_paths(),
         'ANSIBLE_CLICONF_PLUGINS': cliconf_loader.print_paths(),
-        'ANSIBLE_COLLECTIONS_PATHS': to_native(os.pathsep.join(AnsibleCollectionConfig.collection_paths)),
+        'ANSIBLE_COLLECTIONS_PATH': to_native(os.pathsep.join(AnsibleCollectionConfig.collection_paths)),
         'ANSIBLE_CONNECTION_PLUGINS': connection_loader.print_paths(),
         'ANSIBLE_HTTPAPI_PLUGINS': httpapi_loader.print_paths(),
         'ANSIBLE_NETCONF_PLUGINS': netconf_loader.print_paths(),

test/integration/targets/ansible-galaxy-collection/tasks/install.yml

@@ -7,7 +7,7 @@
 - name: install simple collection with implicit path - {{ test_name }}
   command: ansible-galaxy collection install namespace1.name1 -s '{{ test_server }}' {{ galaxy_verbosity }}
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
   register: install_normal
 
 - name: get installed files of install simple collection with implicit path - {{ test_name }}
@@ -34,7 +34,7 @@
 - name: install existing without --force - {{ test_name }}
   command: ansible-galaxy collection install namespace1.name1 -s '{{ test_server }}' {{ galaxy_verbosity }}
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
   register: install_existing_no_force
 
 - name: assert install existing without --force - {{ test_name }}
@@ -98,7 +98,7 @@
   args:
     chdir: '{{ galaxy_dir }}/ansible_collections'
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
     ANSIBLE_CONFIG: '{{ galaxy_dir }}/ansible.cfg'
   register: install_multiple_with_dep
 
@@ -140,7 +140,7 @@
   command: ansible-galaxy collection install '{{ galaxy_dir }}/namespace3.tar.gz' {{ galaxy_verbosity }}
   register: install_tarball
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
 
 - name: get result of install collection from a tarball - {{ test_name }}
   slurp:
@@ -161,7 +161,7 @@
   register: fail_bad_tar
   failed_when: fail_bad_tar.rc != 1 and "Cannot extract tar entry '../../outside.sh' as it will be placed outside the collection directory" not in fail_bad_tar.stderr
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
 
 - name: get result of failed collection install - {{ test_name }}
   stat:
@@ -177,7 +177,7 @@
   command: ansible-galaxy collection install '{{ test_server }}custom/collections/namespace4-name-1.0.0.tar.gz' {{ galaxy_verbosity }}
   register: install_uri
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
 
 - name: get result of install collection from a URI - {{ test_name }}
   slurp:
@@ -201,7 +201,7 @@
   command: ansible-galaxy collection install namespace5.name -s '{{ test_server }}' {{ galaxy_verbosity }}
   register: install_empty_server_list
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
     ANSIBLE_GALAXY_SERVER_LIST: ''
 
 - name: get result of a collection with an empty server list - {{ test_name }}
@@ -230,7 +230,7 @@
   command: ansible-galaxy collection install -r '{{ galaxy_dir }}/ansible_collections/requirements-with-role.yml' -s '{{ test_server }}' -vvv
   register: install_req_collection
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
 
 - name: get result of install collections only with requirements-with-roles.yml - {{ test_name }}
   slurp:
@@ -263,7 +263,7 @@
   command: ansible-galaxy install -r '{{ galaxy_dir }}/ansible_collections/requirements.yaml' -s '{{ test_server }}'
   register: install_req
   environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
 
 - name: get result of install collections with ansible-galaxy install - {{ test_name }}
   slurp:

test/integration/targets/ansible-galaxy/runme.sh

@@ -205,7 +205,7 @@ popd # ${galaxy_testdir}
 # https://github.com/ansible/ansible/issues/60167#issuecomment-585460706
 
 f_ansible_galaxy_status \
-    "list specific role not in the first path in ANSIBLE_ROLES_PATHS"
+    "list specific role not in the first path in ANSIBLE_ROLES_PATH"
 
 role_testdir=$(mktemp -d)
 pushd "${role_testdir}"
@@ -352,7 +352,7 @@ ansible-galaxy collection install ansible_test-zoo-2.5.0.tar.gz -p ./local
 ansible-galaxy collection init "ansible_test.development"
 mv ./ansible_test/development "${galaxy_testdir}/local/ansible_collections/ansible_test/"
 
-export ANSIBLE_COLLECTIONS_PATHS=~/.ansible/collections:${galaxy_testdir}/local
+export ANSIBLE_COLLECTIONS_PATH=~/.ansible/collections:${galaxy_testdir}/local
 
 f_ansible_galaxy_status \
     "collection list all collections"
@@ -413,7 +413,7 @@ f_ansible_galaxy_status \
 
     rmdir emptydir
 
-unset ANSIBLE_COLLECTIONS_PATHS
+unset ANSIBLE_COLLECTIONS_PATH
 
 ## end ansible-galaxy collection list
 

test/integration/targets/collections/runme.sh

@@ -2,7 +2,7 @@
 
 set -eux
 
-export ANSIBLE_COLLECTIONS_PATHS=$PWD/collection_root_user:$PWD/collection_root_sys
+export ANSIBLE_COLLECTIONS_PATH=$PWD/collection_root_user:$PWD/collection_root_sys
 export ANSIBLE_GATHERING=explicit
 export ANSIBLE_GATHER_SUBSET=minimal
 export ANSIBLE_HOST_PATTERN_MISMATCH=error
@@ -52,7 +52,7 @@ fi
 ansible-playbook inventory_test.yml -i a.statichost.yml -i redirected.statichost.yml "$@"
 
 # test adjacent with --playbook-dir
-export ANSIBLE_COLLECTIONS_PATHS=''
+export ANSIBLE_COLLECTIONS_PATH=''
 ANSIBLE_INVENTORY_ANY_UNPARSED_IS_FAILED=1 ansible-inventory --list --export --playbook-dir=. -v "$@"
 
 # use an inventory source with caching enabled

test/integration/targets/collections/vars_plugin_tests.sh

@@ -17,7 +17,7 @@ grep '"adj_var": "value"' out.txt
 
 # Test vars plugin in a collection path
 export ANSIBLE_VARS_ENABLED=testns.testcoll.custom_vars
-export ANSIBLE_COLLECTIONS_PATHS=$PWD/collection_root_user:$PWD/collection_root_sys
+export ANSIBLE_COLLECTIONS_PATH=$PWD/collection_root_user:$PWD/collection_root_sys
 
 ansible-inventory -i a.statichost.yml --list --playbook-dir=./ | tee out.txt
 
@@ -46,7 +46,7 @@ grep -v '"whitelisted": true' out.txt
 
 # Test plugins in plugin paths that opt-in to require whitelisting
 unset ANSIBLE_VARS_ENABLED
-unset ANSIBLE_COLLECTIONS_PATHS
+unset ANSIBLE_COLLECTIONS_PATH
 
 ANSIBLE_VARS_ENABLED=vars_req_whitelist ansible-inventory -i a.statichost.yml --list --playbook-dir=./ | tee out.txt
 

test/integration/targets/collections_plugin_namespace/runme.sh

@@ -2,4 +2,4 @@
 
 set -eux
 
-ANSIBLE_COLLECTIONS_PATHS="${PWD}/collection_root" ansible-playbook test.yml -i ../../inventory "$@"
+ANSIBLE_COLLECTIONS_PATH="${PWD}/collection_root" ansible-playbook test.yml -i ../../inventory "$@"

test/integration/targets/collections_relative_imports/runme.sh

@@ -10,4 +10,4 @@ else
 
 fi
 
-ANSIBLE_COLLECTIONS_PATHS="${PWD}/collection_root" ansible-playbook "${TEST_PLAYBOOK}" -i "${INVENTORY_PATH}" "$@"
+ANSIBLE_COLLECTIONS_PATH="${PWD}/collection_root" ansible-playbook "${TEST_PLAYBOOK}" -i "${INVENTORY_PATH}" "$@"

test/integration/targets/collections_runtime_pythonpath/runme.sh

@@ -51,7 +51,7 @@ ansible \
     PYTHONPATH/site-packages ===
 # This is done by injecting a module with the same FQCN
 # into another collection root.
-ANSIBLE_COLLECTIONS_PATHS="${PWD}/ansible-collection-python-dist-foo" \
+ANSIBLE_COLLECTIONS_PATH="${PWD}/ansible-collection-python-dist-foo" \
 PYTHONPATH="${PWD}/ansible-collection-python-dist-boo:$PYTHONPATH" \
 ansible \
     -m python.dist.boo \

test/lib/ansible_test/_data/pytest/plugins/ansible_pytest_collections.py

@@ -6,7 +6,7 @@ import os
 import sys
 
 # set by ansible-test to a single directory, rather than a list of directories as supported by Ansible itself
-ANSIBLE_COLLECTIONS_PATH = os.path.join(os.environ['ANSIBLE_COLLECTIONS_PATHS'], 'ansible_collections')
+ANSIBLE_COLLECTIONS_PATH = os.path.join(os.environ['ANSIBLE_COLLECTIONS_PATH'], 'ansible_collections')
 
 
 def collection_pypkgpath(self):

test/lib/ansible_test/_data/sanity/import/importer.py

@@ -25,7 +25,7 @@ def main():
     temp_path = os.environ['SANITY_TEMP_PATH'] + os.path.sep
     external_python = os.environ.get('SANITY_EXTERNAL_PYTHON') or sys.executable
     collection_full_name = os.environ.get('SANITY_COLLECTION_FULL_NAME')
-    collection_root = os.environ.get('ANSIBLE_COLLECTIONS_PATHS')
+    collection_root = os.environ.get('ANSIBLE_COLLECTIONS_PATH')
 
     try:
         # noinspection PyCompatibility

test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/main.py

@@ -2251,7 +2251,7 @@ class PythonPackageValidator(Validator):
 
 
 def setup_collection_loader():
-    collections_paths = os.environ.get('ANSIBLE_COLLECTIONS_PATHS', '').split(os.pathsep)
+    collections_paths = os.environ.get('ANSIBLE_COLLECTIONS_PATH', '').split(os.pathsep)
     _AnsibleCollectionFinder(collections_paths)
 
 
@@ -2290,7 +2290,7 @@ def run():
     parser.add_argument('--collection',
                         help='Specifies the path to the collection, when '
                              'validating files within a collection. Ensure '
-                             'that ANSIBLE_COLLECTIONS_PATHS is set so the '
+                             'that ANSIBLE_COLLECTIONS_PATH is set so the '
                              'contents of the collection can be located')
     parser.add_argument('--collection-version',
                         help='The collection\'s version number used to check '

test/lib/ansible_test/_internal/ansible_util.py

@@ -107,7 +107,7 @@ def ansible_environment(args, color=True, ansible_config=None):
 
     if data_context().content.collection:
         env.update(dict(
-            ANSIBLE_COLLECTIONS_PATHS=data_context().content.collection.root,
+            ANSIBLE_COLLECTIONS_PATH=data_context().content.collection.root,
         ))
 
     if data_context().content.is_ansible:
@@ -127,7 +127,7 @@ def configure_plugin_paths(args):  # type: (CommonConfig) -> t.Dict[str, str]
     collection_root = os.path.join(support_path, 'collections')
 
     env = dict(
-        ANSIBLE_COLLECTIONS_PATHS=collection_root,
+        ANSIBLE_COLLECTIONS_PATH=collection_root,
     )
 
     # provide private copies of plugins for integration tests

test/units/utils/collection_loader/test_collection_loader.py

@@ -367,7 +367,7 @@ def test_import_from_collection(monkeypatch):
 
     # define the collection root before any ansible code has been loaded
     # otherwise config will have already been loaded and changing the environment will have no effect
-    monkeypatch.setenv('ANSIBLE_COLLECTIONS_PATHS', collection_root)
+    monkeypatch.setenv('ANSIBLE_COLLECTIONS_PATH', collection_root)
 
     finder = _AnsibleCollectionFinder(paths=[collection_root])
     reset_collections_loader_state(finder)