feat: add central config/ folder with sync-to-canonical

Add a single config/ folder at the repository root where users create
their configuration files. Every make-accessible script syncs config/
files to their canonical locations (newer-wins, never deletes) before
doing anything else; the playbooks and roles keep reading from the
canonical locations unchanged.

- Move all templates and example configs into config/ (single source):
  instance.env.template, config_*_example.sh, kcli.yml.template,
  assisted.yml.template, plus a README map and a .gitignore that
  prevents real config files (including the pull secret) from ever
  being committed
- Add sync_config_files() to aws-hypervisor/scripts/common.sh with a
  manifest of src:dest[:dest2] entries; the pull secret fans out to
  both the dev-scripts and kcli role locations
- Restructure common.sh so the sync runs before instance.env is
  sourced, and replace the raw missing-file source error with an
  actionable hint
- Add 'make sync-config' for users who invoke ansible-playbook
  directly, and register init-host.yml.local in the manifest (it is
  consumed by init-host.yml)
- Source common.sh from get-tnf-logs.sh and helpers/keep-instance.sh
  so every make target inherits the sync
- Gitignore vars/assisted.yml (contains credentials, was not ignored)
- Update all docs and the /setup command to point at config/, keeping
  a note that editing canonical locations directly still works

Backwards compatible: config/ ships with templates only, so the sync
is a no-op until the user explicitly creates a file there.

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

Author: fonta-rh

.claude/commands/setup.md

@@ -37,7 +37,7 @@ All deployment methods require an SSH key on the local machine. Check for any of
 
 If no SSH key exists, create one with: `ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519`
 
-**Note for non-default key paths:** Set `SSH_PUBLIC_KEY` in [deploy/aws-hypervisor/instance.env](deploy/aws-hypervisor/instance.env). This is used by both the AWS hypervisor and dev-scripts deployments.
+**Note for non-default key paths:** Set `SSH_PUBLIC_KEY` in [config/instance.env](config/instance.env). This is used by both the AWS hypervisor and dev-scripts deployments.
 
 ### Inventory File
 
@@ -60,22 +60,19 @@ Required for: external, kcli, dev-scripts
 
 Required for: kcli, dev-scripts
 
-The same pull secret is used by both kcli and dev-scripts (stored in different locations).
-
-- kcli location: [deploy/openshift-clusters/roles/kcli/kcli-install/files/pull-secret.json](deploy/openshift-clusters/roles/kcli/kcli-install/files/pull-secret.json)
-- dev-scripts location: [deploy/openshift-clusters/roles/dev-scripts/install-dev/files/pull-secret.json](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/pull-secret.json)
+The same pull secret is used by both kcli and dev-scripts. Create it once in the central config folder: [config/pull-secret.json](config/pull-secret.json). The sync (run by every `make` target, or explicitly via `cd deploy && make sync-config`) distributes it to both role locations automatically.
 
 **Setup logic:**
-- Check if file exists in either location
-- If it exists in one location, offer to copy it to the other
+- Check if [config/pull-secret.json](config/pull-secret.json) exists
+- If not, check the canonical locations (`deploy/openshift-clusters/roles/dev-scripts/install-dev/files/pull-secret.json` and `deploy/openshift-clusters/roles/kcli/kcli-install/files/pull-secret.json`) - a file there means the user configured it the direct-edit way, which is still valid
 - If it doesn't exist anywhere:
   - User gets pull secret from: https://cloud.redhat.com/openshift/install/pull-secret
   - **For CI builds**: Must include `registry.ci.openshift.org` access (see [CI Token](#ci-token) below)
-  - Suggest creating file and pasting content
+  - Suggest creating [config/pull-secret.json](config/pull-secret.json) and pasting content
 
 **Validation:**
-- Validate pull secret is valid JSON: `jq . < <path-to-pull-secret>`
-- Check for CI registry access (if needed): `jq '.auths | has("registry.ci.openshift.org")' < <path-to-pull-secret>`
+- Validate pull secret is valid JSON: `jq . < config/pull-secret.json`
+- Check for CI registry access (if needed): `jq '.auths | has("registry.ci.openshift.org")' < config/pull-secret.json`
 
 ### CI Token
 
@@ -107,10 +104,11 @@ Required for: dev-scripts (when using CI builds)
      - `export RHSM_ORG="your-org-id"`
      - Guide: https://access.redhat.com/solutions/3341191
 
-   - **Option B**: Local config file [vars/init-host.yml.local](vars/init-host.yml.local)
-     - Template: [vars/init-host.yml.sample](vars/init-host.yml.sample)
-     - Check if exists
-     - Suggest copying: `cp vars/init-host.yml.sample vars/init-host.yml.local`
+   - **Option B**: Local config file [config/init-host.yml.local](config/init-host.yml.local)
+     - Base file: [deploy/openshift-clusters/vars/init-host.yml](deploy/openshift-clusters/vars/init-host.yml)
+     - Check if exists (also accept the direct-edit location `deploy/openshift-clusters/vars/init-host.yml.local`)
+     - Suggest copying: `cp deploy/openshift-clusters/vars/init-host.yml config/init-host.yml.local`
+     - The sync distributes it to `deploy/openshift-clusters/vars/init-host.yml.local`; suggest `cd deploy && make sync-config` before running the playbook directly
 
    - **Option C**: Command line (they'll add when running playbook)
 
@@ -135,17 +133,18 @@ Required for: dev-scripts (when using CI builds)
 
 **Files to configure:**
 
-1. **Instance environment**: [deploy/aws-hypervisor/instance.env](deploy/aws-hypervisor/instance.env)
-   - Template: [deploy/aws-hypervisor/instance.env.template](deploy/aws-hypervisor/instance.env.template)
-   - Check if it exists
+1. **Instance environment**: [config/instance.env](config/instance.env)
+   - Template: [config/instance.env.template](config/instance.env.template)
+   - Check if it exists (also accept the direct-edit location [deploy/aws-hypervisor/instance.env](deploy/aws-hypervisor/instance.env))
    - User must edit ALL variables with their specific values
    - Optional: Set `RHSM_ACTIVATION_KEY` and `RHSM_ORG` for hands-off deployment
      - Guide: https://access.redhat.com/solutions/3341191
-   - Suggest copying: `cp deploy/aws-hypervisor/instance.env.template deploy/aws-hypervisor/instance.env`
+   - Suggest copying: `cp config/instance.env.template config/instance.env`
+   - Every `make` target syncs it to `deploy/aws-hypervisor/instance.env` where the scripts read it
 
 **Validation:**
-- Verify [deploy/aws-hypervisor/instance.env](deploy/aws-hypervisor/instance.env) exists
-- Test by sourcing: `source deploy/aws-hypervisor/instance.env` (should not error)
+- Verify [config/instance.env](config/instance.env) (or `deploy/aws-hypervisor/instance.env`) exists
+- Test by sourcing: `source config/instance.env` (should not error)
 
 **Next steps:**
 - Quick deploy: `cd deploy && make deploy arbiter-ipi`
@@ -165,11 +164,12 @@ Required for: dev-scripts (when using CI builds)
 
 **Files to configure:**
 
-1. **Optional persistent config**: [deploy/openshift-clusters/vars/kcli.yml](deploy/openshift-clusters/vars/kcli.yml)
-   - Template: [deploy/openshift-clusters/vars/kcli.yml.template](deploy/openshift-clusters/vars/kcli.yml.template)
-   - Check if exists
+1. **Optional persistent config**: [config/kcli.yml](config/kcli.yml)
+   - Template: [config/kcli.yml.template](config/kcli.yml.template)
+   - Check if exists (also accept the direct-edit location [deploy/openshift-clusters/vars/kcli.yml](deploy/openshift-clusters/vars/kcli.yml))
    - For setting preferred defaults (cluster name, resources, etc.)
-   - Suggest copying: `cp deploy/openshift-clusters/vars/kcli.yml.template deploy/openshift-clusters/vars/kcli.yml`
+   - Suggest copying: `cp config/kcli.yml.template config/kcli.yml`
+   - The sync distributes it to `deploy/openshift-clusters/vars/kcli.yml`; suggest `cd deploy && make sync-config` before running the playbook directly
 
 **Validation:**
 - Verify inventory file exists
@@ -192,28 +192,29 @@ Required for: dev-scripts (when using CI builds)
 
 **Files to configure:**
 
-1. **Topology config files** in [deploy/openshift-clusters/roles/dev-scripts/install-dev/files/](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/):
+1. **Topology config files** in [config/](config/):
 
-   a. **Arbiter config**: [config_arbiter.sh](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter.sh)
-      - Template: [config_arbiter_example.sh](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter_example.sh)
-      - Check if exists
+   a. **Arbiter config**: [config/config_arbiter.sh](config/config_arbiter.sh)
+      - Template: [config/config_arbiter_example.sh](config/config_arbiter_example.sh)
+      - Check if exists (also accept the direct-edit location `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter.sh`)
       - User must set:
         - `OPENSHIFT_RELEASE_IMAGE` (e.g., `quay.io/openshift-release-dev/ocp-release:4.19.0-rc.5-multi-x86_64`)
         - `CI_TOKEN` (see [CI Token](#ci-token)) unless using `OPENSHIFT_CI="True"`
-      - Suggest copying: `cp deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter_example.sh deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter.sh`
+      - Suggest copying: `cp config/config_arbiter_example.sh config/config_arbiter.sh`
 
-   b. **Fencing config**: [config_fencing.sh](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing.sh)
-      - Template: [config_fencing_example.sh](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing_example.sh)
-      - Check if exists
+   b. **Fencing config**: [config/config_fencing.sh](config/config_fencing.sh)
+      - Template: [config/config_fencing_example.sh](config/config_fencing_example.sh)
+      - Check if exists (also accept the direct-edit location `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing.sh`)
       - Same requirements as arbiter config
-      - Suggest copying: `cp deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing_example.sh deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing.sh`
+      - Suggest copying: `cp config/config_fencing_example.sh config/config_fencing.sh`
 
+   - The sync distributes these to `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/`; suggest `cd deploy && make sync-config` before running the playbook directly
    - **Config reference**: https://github.com/openshift-metal3/dev-scripts/blob/master/config_example.sh
 
 **Validation:**
 - Verify inventory file exists
-- For arbiter: Check [config_arbiter.sh](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter.sh) exists
-- For fencing: Check [config_fencing.sh](deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing.sh) exists
+- For arbiter: Check [config/config_arbiter.sh](config/config_arbiter.sh) (or the direct-edit location) exists
+- For fencing: Check [config/config_fencing.sh](config/config_fencing.sh) (or the direct-edit location) exists
 - Verify pull secret exists and is valid JSON
 
 **Next steps:**

.claude/commands/setup/README.md

@@ -40,7 +40,7 @@ Configures deployment to your own RHEL 9 server (non-AWS).
 Configures automated RHEL hypervisor deployment in AWS EC2.
 
 **Files configured:**
-- `deploy/aws-hypervisor/instance.env` - AWS instance configuration
+- `config/instance.env` - AWS instance configuration (synced to `deploy/aws-hypervisor/instance.env`)
 
 **Use when:** You want to deploy a hypervisor in AWS
 
@@ -49,8 +49,8 @@ Configures kcli-based OpenShift deployment (fencing topology).
 
 **Files configured:**
 - `deploy/openshift-clusters/inventory.ini` - Target host details
-- `deploy/openshift-clusters/roles/kcli/kcli-install/files/pull-secret.json` - OpenShift pull secret
-- `deploy/openshift-clusters/vars/kcli.yml` (optional) - Persistent kcli preferences
+- `config/pull-secret.json` - OpenShift pull secret (synced to the kcli role files directory)
+- `config/kcli.yml` (optional) - Persistent kcli preferences (synced to `deploy/openshift-clusters/vars/kcli.yml`)
 - SSH key validation
 
 **Use when:** You want to deploy using the modern kcli method
@@ -60,9 +60,9 @@ Configures traditional dev-scripts deployment (arbiter or fencing topology).
 
 **Files configured:**
 - `deploy/openshift-clusters/inventory.ini` - Target host details
-- `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter.sh` - Arbiter config
-- `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing.sh` - Fencing config
-- `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/pull-secret.json` - OpenShift pull secret
+- `config/config_arbiter.sh` - Arbiter config (synced to the dev-scripts role files directory)
+- `config/config_fencing.sh` - Fencing config (synced to the dev-scripts role files directory)
+- `config/pull-secret.json` - OpenShift pull secret (synced to both the dev-scripts and kcli role files directories)
 - Ansible collections installation
 - SSH key validation
 

CLAUDE.md

@@ -72,8 +72,8 @@ ansible-playbook kcli-install.yml -i inventory.ini -e "force_cleanup=true"
 
 #### Assisted Installer Method (Spoke TNF via ACM)
 ```bash
-# Copy and customize the configuration template
-cp vars/assisted.yml.template vars/assisted.yml
+# Copy and customize the configuration template (from the repository root)
+cp config/assisted.yml.template config/assisted.yml
 
 # Deploy hub + spoke TNF cluster via assisted installer
 make deploy fencing-assisted
@@ -130,20 +130,30 @@ make ansible-lint
 
 ### Key Configuration Files
 
-#### Dev-scripts Method
-- `inventory.ini`: Ansible inventory (copy from `inventory.ini.sample`)
+#### Central config/ Folder
+User configuration files are created in `config/` at the repository root (templates and examples live there; see `config/README.md`). Every make-accessible script syncs `config/` files to the canonical locations below before doing anything else (newer-wins, never deletes); `make sync-config` runs the sync explicitly. Editing the canonical locations directly still works: a `config/` file only becomes authoritative once the user creates it.
+
+- `config/instance.env`: AWS hypervisor settings (copy from `config/instance.env.template`)
+- `config/pull-secret.json`: OpenShift pull secret, fanned out to both dev-scripts and kcli role locations
+- `config/config_arbiter.sh`, `config/config_fencing.sh`, `config/config_sno.sh`: dev-scripts topology configs (copy from the `config/config_*_example.sh` files)
+- `config/kcli.yml`: kcli variable overrides (copy from `config/kcli.yml.template`)
+- `config/assisted.yml`: assisted installer variables (copy from `config/assisted.yml.template`)
+- `config/init-host.yml.local`: external-host RHSM overrides (copy from `deploy/openshift-clusters/vars/init-host.yml`)
+
+#### Dev-scripts Method (canonical locations)
+- `inventory.ini`: Ansible inventory (copy from `inventory.ini.sample`; generated by `make inventory` on AWS)
 - `roles/dev-scripts/install-dev/files/config_arbiter.sh`: Arbiter topology config
 - `roles/dev-scripts/install-dev/files/config_fencing.sh`: Fencing topology config
 - `roles/dev-scripts/install-dev/files/config_sno.sh`: Single Node OpenShift config
 - `roles/dev-scripts/install-dev/files/pull-secret.json`: OpenShift pull secret
 
-#### Kcli Method
+#### Kcli Method (canonical locations)
 - `vars/kcli.yml`: Variable override file for persistent configuration
 - `roles/kcli/kcli-install/files/pull-secret.json`: OpenShift pull secret
 - SSH key automatically read from `~/.ssh/id_ed25519.pub` on ansible controller
 
-#### Assisted Installer Method
-- `vars/assisted.yml`: Variable override file (copy from `vars/assisted.yml.template`)
+#### Assisted Installer Method (canonical locations)
+- `vars/assisted.yml`: Variable override file (create as `config/assisted.yml`)
 - Hub cluster must be deployed first via dev-scripts (`make deploy fencing-ipi`)
 - Spoke credentials output to `~/<spoke_cluster_name>/auth/` on hypervisor
 - Hub proxy preserved as `hub-proxy.env`

README.md

@@ -6,6 +6,8 @@ This repository provides automation for deploying and managing two-node OpenShif
 
 ## Quick Start
 
+Configuration files (instance settings, pull secret, topology configs) are created in the central [config/](config/) folder; see [config/README.md](config/README.md) for the full list. Every `make` command syncs them to the locations where the automation reads them. Editing the canonical locations directly still works as before.
+
 ### Option 1: AWS Hypervisor (Automated)
 
 If you have AWS access, use the automated workflow. Most lifecycle operations can be performed from the [deploy](deploy/) folder using `make`:
@@ -48,6 +50,8 @@ ansible-playbook setup.yml -i inventory.ini        # dev-scripts (arbiter or fen
 ansible-playbook kcli-install.yml -i inventory.ini # kcli (fencing only)
 ```
 
+If you created your configuration files in [config/](config/), run `make sync-config` from the [deploy/](deploy/) folder first to distribute them, since the playbooks are invoked directly here.
+
 See [deploy/openshift-clusters/README-external-host.md](deploy/openshift-clusters/README-external-host.md) for detailed instructions.
 
 ## Deployment Methods

config/.gitignore

@@ -0,0 +1,7 @@
+# Real config files (created by the user, may contain credentials) must never
+# be committed. Only templates, examples, the README, and this file are tracked.
+*
+!.gitignore
+!README.md
+!*.template
+!config_*_example.sh

config/README.md

@@ -0,0 +1,34 @@
+# Central configuration folder
+
+This folder is the single place to create your configuration files for the toolbox.
+Every `make` target (and `make sync-config` explicitly) syncs files from here to the
+locations where the scripts and playbooks actually read them. A file is only copied
+when it is missing at the destination or the `config/` copy is newer, so editing the
+canonical locations directly still works as before.
+
+Only templates and examples are tracked in git; the `.gitignore` in this folder
+prevents your real config files (including the pull secret) from ever being committed.
+
+## Files
+
+| Create this file | Used by | Synced to | How to create |
+|---|---|---|---|
+| `instance.env` | AWS hypervisor (all `make` instance targets) | `deploy/aws-hypervisor/instance.env` | `cp config/instance.env.template config/instance.env` |
+| `pull-secret.json` | dev-scripts and kcli deployments | `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/pull-secret.json` and `deploy/openshift-clusters/roles/kcli/kcli-install/files/pull-secret.json` | Paste your pull secret from <https://cloud.redhat.com/openshift/install/pull-secret> |
+| `config_arbiter.sh` | dev-scripts arbiter topology | `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_arbiter.sh` | `cp config/config_arbiter_example.sh config/config_arbiter.sh` |
+| `config_fencing.sh` | dev-scripts fencing topology | `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_fencing.sh` | `cp config/config_fencing_example.sh config/config_fencing.sh` |
+| `config_sno.sh` | dev-scripts SNO topology | `deploy/openshift-clusters/roles/dev-scripts/install-dev/files/config_sno.sh` | `cp config/config_sno_example.sh config/config_sno.sh` |
+| `kcli.yml` | kcli deployment (optional overrides) | `deploy/openshift-clusters/vars/kcli.yml` | `cp config/kcli.yml.template config/kcli.yml` |
+| `assisted.yml` | assisted installer spoke deployment | `deploy/openshift-clusters/vars/assisted.yml` | `cp config/assisted.yml.template config/assisted.yml` |
+| `init-host.yml.local` | external host initialization (optional RHSM overrides) | `deploy/openshift-clusters/vars/init-host.yml.local` | `cp deploy/openshift-clusters/vars/init-host.yml config/init-host.yml.local` |
+
+## Syncing
+
+The sync runs automatically at the start of every script invoked through the
+`deploy/` Makefile. To run it on its own (for example before invoking
+`ansible-playbook` directly):
+
+```bash
+cd deploy/
+make sync-config
+```