feat: add 'make doctor' configuration preflight

Read-only preflight that validates the full deployment configuration
and prints a concrete fix command for every failure: required tools,
SSH key, Ansible collections, inventory.ini, instance.env plus live AWS
credentials, dev-scripts topology configs and pull secret, CI registry
auth cross-check with live CI token check, and the kcli pull secret.
Exits non-zero if and only if a check failed.

- 'make doctor' runs common checks plus every auto-detected section
- 'make doctor <cluster-type>' validates strictly for that deployment:
  the method's section becomes mandatory and its method-specific
  warnings are promoted to failures; cluster-type goals following
  'doctor' are neutralized so they never trigger a deployment
- inventory.ini stays informational when absent (the AWS flow generates
  it via 'make inventory'), but a present-but-unedited copy of the
  sample fails, since that breaks deployment in confusing ways
- deploy-cluster.sh preflight error paths now point at 'make doctor'

Checks are ported from the validation steps in
.claude/commands/setup.md and the in-playbook preflight in
roles/dev-scripts/install-dev/tasks/config.yml.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSBffYjh3rtLToAMR1pjQT

Author: 2 people

CLAUDE.md

@@ -38,6 +38,8 @@ make patch-nodes        # Build resource-agents RPM and patch cluster nodes
 make ssh               # SSH into EC2 instance
 make info              # Display instance information
 make inventory         # Update inventory.ini with current instance IP
+make doctor            # Validate configuration and prerequisites (read-only)
+make doctor <type>     # Validate strictly for a specific cluster type (e.g. fencing-kcli)
 ```
 
 ### Ansible Deployment Methods

README.md

@@ -79,6 +79,8 @@ If you're using [Claude Code](https://claude.ai/code), use the `/setup` command
 - Validating your setup
 
 Run `/setup` to begin, or `/setup <method>` to configure a specific deployment method (aws, external, kcli, dev-scripts).
+
+If you are not using Claude Code, or want a quick non-interactive check, run `make doctor` from the `deploy/` directory. It validates required tools, SSH keys, Ansible collections, and configuration files, printing a fix command for every problem found. `make doctor <cluster-type>` (for example `make doctor arbiter-ipi`) validates strictly for one deployment type.
 ## Helpers
 
 The [helpers/](helpers/) directory contains utilities for cluster operations including resource-agents patching, fencing validation, and containerized build validation. To quickly verify a resource-agents branch compiles on CentOS Stream 9 and 10:

deploy/Makefile

@@ -13,6 +13,20 @@ ifeq (deploy,$(firstword $(MAKECMDGOALS)))
   endif
 endif
 
+# Handle 'make doctor <cluster-type>' pattern
+# When 'doctor' is first, following cluster types select strict validation for
+# that deployment; the cluster-type goals themselves are neutralized below so
+# they don't trigger an actual deployment.
+ifeq (doctor,$(firstword $(MAKECMDGOALS)))
+  DOCTOR_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
+  ifneq ($(DOCTOR_ARGS),)
+    DOCTOR_INVALID_ARGS := $(filter-out $(VALID_CLUSTER_TYPES),$(DOCTOR_ARGS))
+    ifneq ($(DOCTOR_INVALID_ARGS),)
+      $(error Unknown cluster type: '$(DOCTOR_INVALID_ARGS)'. Run 'make help' for more information.)
+    endif
+  endif
+endif
+
 create:
 	@./aws-hypervisor/scripts/create.sh
 
@@ -64,6 +78,14 @@ inventory:
 sync-config:
 	@bash -c 'set -e; source ./common.sh; if [ "$${CONFIG_SYNCED_COUNT:-0}" -eq 0 ]; then echo "Config files: everything up to date."; fi'
 
+doctor:
+	@./openshift-clusters/scripts/doctor.sh $(DOCTOR_ARGS)
+
+ifeq (doctor,$(firstword $(MAKECMDGOALS)))
+# Cluster types after 'doctor' are arguments to doctor.sh, not deployments
+$(VALID_CLUSTER_TYPES):
+	@:
+else
 fencing-ipi:
 	@./openshift-clusters/scripts/deploy-cluster.sh --topology fencing --method ipi
 
@@ -91,6 +113,7 @@ fencing-kcli:
 fencing-assisted:
 	@$(MAKE) fencing-ipi
 	@./openshift-clusters/scripts/deploy-fencing-assisted.sh
+endif
 
 keep-instance:
 	@../helpers/keep-instance.sh '$(DAYS)'
@@ -130,6 +153,8 @@ help:
 	@echo "  ssh                  - SSH into the EC2 instance"
 	@echo "  info                 - Display instance information"
 	@echo "  inventory            - Update inventory.ini with current instance IP"
+	@echo "  doctor               - Validate configuration and prerequisites (read-only)"
+	@echo "  doctor <cluster-type>- Validate strictly for a specific cluster type"
 	@echo "  keep-instance        - Tag instance with keep-N retention (default: 2, max: 5)"
 	@echo "                         Usage: make keep-instance or make keep-instance DAYS=5"
 	@echo "  sync-config          - Sync files from config/ to their canonical locations"

deploy/README.md

@@ -40,6 +40,8 @@ Additionally, if you're using Mac OS, you might not have `timeout`, so you might
 
 ## Configuration
 
+Run `make doctor` at any time to validate your setup before deploying. It is a read-only preflight that checks required tools, SSH keys, Ansible collections, and every configuration file, and prints a concrete fix command for each problem it finds. Use `make doctor <cluster-type>` (for example `make doctor fencing-kcli`) to validate strictly for a specific deployment type: the checks specific to that deployment method become mandatory.
+
 Before deployment, configure your environment by creating an `instance.env` file in the central [config/](../config/) folder. Copy `config/instance.env.template` to `config/instance.env` and set all variables to valid values for your user. Every `make` target syncs `config/` files to the locations the scripts read them from (`aws-hypervisor/instance.env` in this case); run `make sync-config` to sync explicitly. Editing `aws-hypervisor/instance.env` directly still works as before. See [config/README.md](../config/README.md) for all available configuration files.
 
 ## Available Commands

deploy/openshift-clusters/scripts/deploy-cluster.sh

@@ -73,6 +73,7 @@ fi
 # Check if instance data exists
 if [[ ! -f "$(get_node_dir)/aws-instance-id" ]]; then
     echo "Error: No instance found. Please run 'make deploy' first."
+    echo "Run 'make doctor' to check your setup."
     exit 1
 fi
 
@@ -81,6 +82,7 @@ if [[ ! -f "${DEPLOY_DIR}/openshift-clusters/inventory.ini" ]]; then
     echo "Error: inventory.ini not found in ${DEPLOY_DIR}/openshift-clusters/"
     echo "Please ensure the inventory file is properly configured."
     echo "You can run 'make inventory' to update it with current instance information."
+    echo "Run 'make doctor' to check your setup."
     exit 1
 fi