feat(preflight): add preflight validation role

[vvaldez]

What

Adds a preflight role and vmf_preflight.yml playbook that validate the migration environment before seeding AAP:

• OpenShift API authentication — SelfSubjectReview probe with the configured credential
• OpenShift Virtualization (CNV) and MTV operator health — CSV phase checks
• AAP access: /api/controller/v2/me/ probe (path configurable for AAP 2.4 and earlier)
• vCenter connectivity and authentication — datacenter listing (vmware sources only)
• VDDK init image configuration — non-empty and scheme-less (vmware sources only)

A single summary report fails the play if any check failed, so one run reports everything that needs attention.

Why

The migration playbooks currently fail late and deep — for example, a scheme'd VDDK image reaches the provider CR and Forklift rejects it with VDDKInitImageUnavailable two stages later. Preflight validates the environment up front with an actionable message per check.

Design notes

• Credentials cascade from the same env-var / host-var chains as the existing roles (K8S_AUTH_API_KEY, VMWARE_HOST, AAP_*), falling back to the temporary API key alternative documented in the sample inventory. Namespace variables resolve through the target cluster host as well as extra vars.
• Credential-bearing endpoints are rejected at pre-validation unless they use https and do not embed user:pass@.
• no_log is controlled by preflight_secure_logging (default true) on all credential-bearing probes; hostnames and usernames appear in success/detail messages, never secrets.
• The summary asserts only over the checks that ran, so isolated --tags debug runs end green when the targeted check passed. A source whose type is not vmware skips the vCenter and VDDK checks.

Testing

• ansible-lint (production profile) passes clean across the role, playbook, and test files.
• New preflight_report integration test (tests/integration/targets/preflight_report/, molecule scenario integration_preflight_report) covers the report summary paths: isolated tagged runs, all-passed full runs with mixed boolean forms, and a failed full run whose summary marks each failed check.
• The integration target includes role tasks via FQCN include_role, which resolves under ansible-test's temp-dir layout. The recap shows ok=18 where include_tasks runs showed 24; coverage is unchanged (eight cases, three rescues, two skips).
• Changelog fragment added.

[sabre1041]

Good start to a preflight check list. A few items:

1. Running to the following issue as it relates to verifying vmware

    "module_stderr": "Traceback (most recent call last):\n  File \"/root/.ansible/tmp/ansible-tmp-1792093923.5295908-74-157229115925727/AnsiballZ_vcenter_datacenter_info.py\", line 107, in <module>\n    _ansiballz_main()\n  File \"/root/.ansible/tmp/ansible-tmp-1792093923.5295908-74-157229115925727/AnsiballZ_vcenter_datacenter_info.py\", line 99, in _ansiballz_main\n    invoke_module(zipped_mod, temp_path, ANSIBALLZ_PARAMS)\n  File \"/root/.ansible/tmp/ansible-tmp-1792093923.5295908-74-157229115925727/AnsiballZ_vcenter_datacenter_info.py\", line 47, in invoke_module\n    runpy.run_module(mod_name='ansible_collections.vmware.vmware_rest.plugins.modules.vcenter_datacenter_info', init_globals=dict(_module_fqn='ansible_collections.vmware.vmware_rest.plugins.modules.vcenter_datacenter_info', _modlib_path=modlib_path),\n  File \"<frozen runpy>\", line 226, in run_module\n  File \"<frozen runpy>\", line 98, in _run_module_code\n  File \"<frozen runpy>\", line 88, in _run_code\n  File \"/tmp/ansible_vmware.vmware_rest.vcenter_datacenter_info_payload_zx9mk_bn/ansible_vmware.vmware_rest.vcenter_datacenter_info_payload.zip/ansible_collections/vmware/vmware_rest/plugins/modules/vcenter_datacenter_info.py\", line302, in <module>\n  File \"/usr/lib64/python3.12/asyncio/base_events.py\", line 691, in run_until_complete\n    return future.result()\n           ^^^^^^^^^^^^^^^\n  File \"/tmp/ansible_vmware.vmware_rest.vcenter_datacenter_info_payload_zx9mk_bn/ansible_vmware.vmware_rest.vcenter_datacenter_info_payload.zip/ansible_collections/vmware/vmware_rest/plugins/modules/vcenter_datacenter_info.py\", line 248, in main\n  File \"/tmp/ansible_vmware.vmware_rest.vcenter_datacenter_info_payload_zx9mk_bn/ansible_vmware.vmware_rest.vcenter_datacenter_info_payload.zip/ansible_collections/vmware/vmware_rest/plugins/modules/vcenter_datacenter_info.py\", line 275, in entry_point\n  File \"/usr/local/lib64/python3.12/site-packages/aiohttp/client_reqrep.py\", line 777, in json\n    raise ContentTypeError(\naiohttp.client_exceptions.ContentTypeError: 404, message='Attempt to decode JSON with unexpected mimetype: text/plain; charset=utf-8', url='https://vcenter.apps.ocpv07.rhdp.net/api/vcenter/datacenter'\nUnclosed client session\nclient_session: <aiohttp.client.ClientSession object at 0xffffa49088f0>\nUnclosed connector\nconnections: ['deque([(<aiohttp.client_proto.ResponseHandler object at 0xffffa3596e40>, 40212.0821937)])']\nconnector: <aiohttp.connector.TCPConnector object at 0xffffa483ce90>\n",

2. Whats the best way to ignore certain types of checks. Skipping tags?
3. As @tech2734 mentioned, should default preflight_aap_api_path=/api/controller/v2/
4. Provides a suggestion to resolve an issue faced when turning off certificate verification to OpenShift

[vvaldez]

Both reviews addressed on 7d2a394 — one line each:

@tech2734

• __preflight_source_vddk moved from defaults to vars/main.yml — fixed in c8ac8f4
• preflight_aap_api_path now defaults to /api/controller/v2/ — fixed in 7d2a394 (AAP 2.4 and earlier set /api/v2/)
• validate_aap results[0] guard — skipped: verified empirically that json.results[0].username | default('unknown', true) handles every response shape without erroring (404 body, non-JSON response, empty results: [], and ok) — chained access propagates undefined, so the suggested guard would be a no-op
• validate_vcenter when converted to list form — fixed in c8ac8f4
• report.yml unran 'False' string defaults are real false booleans — fixed in c8ac8f4

@sabre1041

• vCenter module crash aborting the run — fixed in 7d2a394: the probe now carries ignore_errors so a module exception (e.g. aiohttp ContentTypeError on the non-JSON 404 you hit) flows into the record task's graceful failure detail instead of killing the play
• ignoring certain checks — --tags <check> / --skip-tags <check>; the summary asserts only over checks that ran, so a partial run ends green with the skipped checks reported in the table
• AAP API path default — fixed in 7d2a394 (matches your and tech2734's suggestion)
• verify_ssl suggestion — applied in 7d2a394; the | bool cast was already present, so the delta drops the inner default(true, true) truthy flag (an empty hostvar now resolves false)

CI green on 7d2a394 (pre-commit, ansible-lint, gitleaks, PR validation).

[vvaldez]

@sabre1041 — the traceback is tolerated as of 7d2a394: the probe now carries ignore_errors, so a module exception flows into the record task and the summary reports the vCenter check as failed (with the re-run-alone guidance) instead of killing the play. A preflight run can no longer abort on this.

What the traceback itself means: the endpoint at vcenter.apps.ocpv07.rhdp.net answered HTTP 404 with Content-Type: text/plain, and vmware.vmware_rest feeds the response straight into aiohttp .json() without tolerating a non-JSON body — so the module crashes (the unclosed-session lines are crash debris) rather than failing cleanly. A 404 — rather than 401/403 — means the request reached something that does not serve the API; credentials are not the problem.

On that cluster: vcenter.apps.ocpv07.rhdp.net is an apps. route in front of vCenter, and whatever answers there is not serving /api/vcenter/datacenter. Worth a direct probe:

curl -sk -u '<user>:<pass>' https://vcenter.apps.ocpv07.rhdp.net/api/vcenter/datacenter

A plain-text/HTML 404 page confirms the route (or an intermediate proxy) is not forwarding the path to vCenter — fix the route backend, or point preflight_vcenter_hostname at the vCenter FQDN directly. Once the endpoint serves the REST API, the check goes green.

The crash itself is upstream vmware.vmware_rest behavior (aiohttp ContentTypeError on non-JSON responses) — the preflight tolerates it either way.

[vvaldez]

@sabre1041 — the vCenter check now passes against your environment. Verified with a read-only run of the role against vcenter.apps.ocpv07.rhdp.net:

"detail": " HTTP session established at vcenter.apps.ocpv07.rhdp.net (1 datacenters visible via the SOAP SDK)",
"passed": true

What the probes found on that cluster:

• The route's gateway is a Go-based proxy that maps /sdk and /rest but not /api — an authenticated GET /api/vcenter/datacenter returns Go's default 404 page not found, and its unauthenticated 401 mimics vCenter's error body (which is why the unauth probe looks like REST is served).
• The backend is a 6.5-era vCenter — /sdk/vimServiceVersions.xml advertises urn:vim25 6.5 — so the /api/ REST tree doesn't exist there at all; that's 7.0+ only. The certified vmware.vmware_rest collection cannot reach it on any hostname.
• The provider works because govmomi speaks SOAP via /sdk, which is mapped and supported by 6.x — no exposure change would have fixed the REST path short of an upgrade.

The fix (fa9a1be + 4a36004): the check runs the certified REST probe first, then falls back to community.vmware.vmware_datacenter_info (pyVmomi, vCenter 6.5+, already a collection dependency) whenever REST returns no data or an empty list — the proxied REST path answers with an empty list rather than failing, which the first pass of the fallback missed. The merge prefers a result with datacenters, so the check reports the real count via whichever path found them. No admin changes needed.

Module tier note: community.vmware is Tier-3 content, so the justification is documented in the task header — the certified successor vmware.vmware does not yet ship a datacenter_info module and the certified REST collection cannot reach 6.x, making this the only content covering that path. The SOAP fallback runs only when the REST probe cannot return data.

[sabre1041]

LGTM

[tech2734]

Found a bug during live testing against the homelab environment: the validate_certs cascade silently flips false → true due to the default(true, true) pattern. Two suggestions below.

[vvaldez]

Fixed in 166a5cc.

• validate_certs cascade: the inner default(true, true) treated an explicit false from the inventory as undefined and replaced it with the fallback true, for both the vCenter and AAP checks. The inner default now catches only an undefined key, matching the openshift_verify_ssl pattern: an inventory false survives, the env var wins when set, and a missing key still defaults to true.
• Verified red-green: pre-fix both flags resolved true with an inventory false; post-fix all six cascade cases pass (inventory false survives, env var wins when set, missing key defaults to true).

Thanks John for the find, Andy for the pointer.

[sabre1041]

LGTM