feature-flag experimental module metadata (#85351)

* added ansible-test integration env/set directive for aliases
* applied to module-serialization-profiles test to enable feature flag

Co-authored-by: Matt Clay <matt@mystile.com>

changelogs/fragments/ansible-test-env-set.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - ansible-test - Added support for setting static environment variables in integration tests using ``env/set/``
+    entries in the ``aliases`` file. For example, ``env/set/MY_KEY/MY_VALUE`` or ``env/set/MY_PATH//an/abs/path``.

lib/ansible/config/base.yml

@@ -41,6 +41,15 @@ _CALLBACK_DISPATCH_ERROR_BEHAVIOR:
     ignore: just continue silently
   env: [ { name: _ANSIBLE_CALLBACK_DISPATCH_ERROR_BEHAVIOR } ]
   version_added: '2.19'
+_MODULE_METADATA:
+  name: Enable experimental module metadata
+  description:
+    - Enables experimental module-level metadata controls for serialization profile selection.
+    - This is for internal use only.
+  type: boolean
+  default: false
+  env: [ { name: _ANSIBLE_MODULE_METADATA } ]
+  version_added: '2.19'
 ALLOW_BROKEN_CONDITIONALS:
   # This config option will be deprecated once it no longer has any effect (2.23).
   name: Allow broken conditionals

lib/ansible/executor/module_common.py

@@ -659,9 +659,14 @@ metadata_versions: dict[t.Any, type[ModuleMetadata]] = {
     1: ModuleMetadataV1,
 }
 
+_DEFAULT_LEGACY_METADATA = ModuleMetadataV1(serialization_profile='legacy')
+
 
 def _get_module_metadata(module: ast.Module) -> ModuleMetadata:
-    # DTFIX2: while module metadata works, this feature isn't fully baked and should be turned off before release
+    # experimental module metadata; off by default
+    if not C.config.get_config_value('_MODULE_METADATA'):
+        return _DEFAULT_LEGACY_METADATA
+
     metadata_nodes: list[ast.Assign] = []
 
     for node in module.body:
@@ -674,9 +679,7 @@ def _get_module_metadata(module: ast.Module) -> ModuleMetadata:
                         metadata_nodes.append(node)
 
     if not metadata_nodes:
-        return ModuleMetadataV1(
-            serialization_profile='legacy',
-        )
+        return _DEFAULT_LEGACY_METADATA
 
     if len(metadata_nodes) > 1:
         raise ValueError('Module METADATA must defined only once.')

test/integration/targets/ansible-test-integration/ansible_collections/ns/col/tests/integration/targets/hello/aliases

@@ -1 +1,3 @@
 context/controller
+env/set/A_VAR/something
+env/set/A_PATH//an/absolute/path

test/integration/targets/ansible-test-integration/ansible_collections/ns/col/tests/integration/targets/hello/tasks/main.yml

@@ -5,3 +5,5 @@
 - assert:
     that:
       - hello.message == 'Hello Ansibull'
+      - lookup('env', 'A_VAR') == 'something'
+      - lookup('env', 'A_PATH') == '/an/absolute/path'

test/integration/targets/module-serialization-profiles/aliases

@@ -1,2 +1,3 @@
 context/target
 shippable/posix/group1
+env/set/_ANSIBLE_MODULE_METADATA/1

test/lib/ansible_test/_internal/commands/integration/__init__.py

@@ -825,6 +825,7 @@ def integration_environment(
         env.update(ANSIBLE_TEST_REMOTE_INTERPRETER='')
 
     env.update(integration)
+    env.update(target.env_set)
 
     return env
 

test/lib/ansible_test/_internal/target.py

@@ -582,6 +582,14 @@ class IntegrationTarget(CompletionTarget):
         else:
             static_aliases = tuple()
 
+        # non-group aliases which need to be extracted before group mangling occurs
+
+        self.env_set: dict[str, str] = {
+            match.group('key'): match.group('value') for match in (
+                re.match(r'env/set/(?P<key>[^/]+)/(?P<value>.*)', alias) for alias in static_aliases
+            ) if match
+        }
+
         # modules
 
         if self.name in modules: