Add a command to reset the Ansible fact cache

[berendt]

Category: feature | Scope: Small

Description

Add an osism command that clears the Ansible fact cache so operators can remove stale or incorrect facts. By default the command flushes the entire cache. A parameter restricts the operation to selected hosts or groups when an operator wants to reset only part of it.

The command only clears the cache. It does not start a new fact-gathering run; the cache rebuilds on the next Ansible run that collects facts.

No confirmation prompt is needed. The operation is destructive but low-risk, since the cache is rebuilt automatically.

Motivation

Operators troubleshooting a deployment need a clean way to drop cached facts. Stale or wrong facts can make Ansible act on outdated information about a host, producing confusing results that are hard to diagnose. There is no direct command to clear them today, so an operator has to locate and remove the cache by hand.

A dedicated command turns this into a single, predictable step. Restricting the reset to specific hosts or groups keeps the rest of the cache intact when only one host misbehaves.

---

Drafted by planwerk-review with Claude

[berendt]

Implementation Plan (issue #2388)

Summary

• Add a new cliff command osism reset facts that clears the Ansible fact cache stored in Redis under ansible_facts<host> keys. With no argument it flushes every ansible_facts* key; with -l/--limit <pattern> it resolves the host/group pattern through ansible-inventory --list --limit and deletes only the matching hosts' keys. The command performs direct Redis deletes only — no confirmation prompt and no fact-gathering run — which is the smallest change satisfying every requirement. The implementation reuses two existing in-repo idioms verbatim: Redis key deletion (osism/commands/vault.py:UnsetPassword) and limit→inventory→host expansion (osism/commands/report.py:Memory).

Ground-Truth Notes

• Redis fact cache keys ansible_facts<host> — confirmed as the canonical Ansible fact cache. Read in osism/commands/get.py:194,280 (Facts, States), osism/api.py:935,974, osism/utils/rabbitmq.py:44; scanned with match="ansible_facts*" in osism/utils/__init__.py:584 (check_ansible_facts). Key format matches the community.general.redis cache plugin with fact_caching_prefix=ansible_facts. The plugin itself is configured in the separate osism-ansible container, not in this repo (no ansible.cfg here).
• Redis deletion from a command — confirmed at osism/commands/vault.py:57: utils.redis.delete("ansible_vault_password"). utils.redis is a lazily-initialised module attribute (osism/utils/__init__.py:662 __getattr__ → _init_redis, host/port/db from osism/settings.py:21-23).
• -l/--limit host/group selection — confirmed idiom in osism/commands/report.py:18-60 (Memory): list-form subprocess.run(["ansible-inventory","-i",get_inventory_path("/ansible/inventory/hosts.yml"),"--list","--limit",pattern], capture_output=True, text=True, timeout=30), then get_hosts_from_inventory(json.loads(result.stdout)). get_inventory_path / get_hosts_from_inventory live in osism/utils/inventory.py. Ansible --limit accepts hostnames, group names, and patterns — this is exactly "selected hosts or groups."
• Command registration — confirmed via entry points in setup.cfg:40-175 under osism.commands:, loaded by CommandManager("osism.commands") in osism/main.py:26. osism.egg-info is not git-tracked (regenerated on install), so only setup.cfg changes.
• No reset/facts top-level namespace exists — confirmed; only manage loadbalancer reset (setup.cfg:101) and sonic reset (setup.cfg:143). No collision.
• Cliff command + test conventions — confirmed: class docstring becomes CLI help (osism/commands/lock.py:9); tests construct Cls(MagicMock(), MagicMock()), build args via get_parser("test").parse_args([...]), patch module-level names, assert on return code (tests/unit/commands/test_get.py, test_vault.py). loguru_logs fixture for log assertions at tests/conftest.py:85.
• Documentation — confirmed no in-repo docs/ directory; CLI reference is external (osism.tech, separate repo). CHANGELOG.md is curated in batch by maintainers at release time (git log shows "Add changelog entries for v… through v…"), not edited by feature PRs.

Change Set

• osism/commands/reset.py — create: new module with class Facts(Command). Imports: json, subprocess, from cliff.command import Command, from loguru import logger, from osism import utils, from osism.utils.inventory import get_hosts_from_inventory, get_inventory_path. One-line class docstring (e.g. """Reset (clear) the cached Ansible facts.""") used as CLI help.
  • get_parser: add -l/--limit (type=str, help="Limit the reset to selected hosts or groups (Ansible host pattern)"), copying the wording style of report.py:Memory.
  • take_action:
    • Resolve r = utils.redis. Wrap all Redis access in try/except redis.exceptions.RedisError as exc: → logger.error(f"Failed to reset Ansible fact cache: {exc}") + return 1 (avoids the silent-failure anti-pattern; ConnectionError from _init_redis().ping() is a RedisError subclass). Add from redis.exceptions import RedisError.
    • If parsed_args.limit is falsy → SCAN/flush all (mirror check_ansible_facts loop): iterate r.scan(cursor, match="ansible_facts*", count=100), collect keys, r.delete(*keys) when non-empty, logger.info(f"Removed cached facts for {len(keys)} host(s)"), return 0.
    • If parsed_args.limit is set → run list-form subprocess.run(["ansible-inventory","-i",get_inventory_path("/ansible/inventory/hosts.yml"),"--list","--limit",parsed_args.limit], capture_output=True, text=True, timeout=30). On result.returncode != 0 → logger.error("Error loading inventory.") + return 1 (also catch subprocess.TimeoutExpired like report.py:Memory). Parse get_hosts_from_inventory(json.loads(result.stdout)). If empty → logger.warning("No hosts matched the given limit.") + return 0. Else deleted = sum(r.delete(f"ansible_facts{host}") for host in hosts), logger.info(f"Removed cached facts for {deleted} host(s)"), return 0.
• setup.cfg — modify: add one entry-point line under the osism.commands: block (group it with the reconciler/report entries around setup.cfg:126-131): reset facts = osism.commands.reset:Facts.

Commit Sequence

1. Add 'osism reset facts' command to clear the fact cache — create osism/commands/reset.py and register reset facts in setup.cfg. Body: new cliff command deletes ansible_facts* Redis keys, optionally scoped by -l/--limit; no prompt, no gather run.
2. Add unit tests for 'osism reset facts' — add tests/unit/commands/test_reset.py covering flush-all, empty-cache, limited-delete, and inventory-failure paths.

(Two commits keep code and tests reviewable; they may be squashed into one if the maintainer prefers a single feature commit.)

Test Plan

New file tests/unit/commands/test_reset.py (model on test_get.py/test_vault.py; helper _make(cls) → cls(MagicMock(), MagicMock()); patch osism.commands.reset.utils.redis with a MagicMock, patch osism.commands.reset.subprocess.run and osism.commands.reset.get_hosts_from_inventory as needed; use the loguru_logs fixture for message assertions):

• test_facts_flushes_all_keys_when_no_limit — redis.scan yields (0, [b"ansible_factsnode1", b"ansible_factsnode2"]); assert redis.delete called once with both keys and take_action returns falsy. Locks down: default behavior flushes the whole cache via one batched delete.
• test_facts_succeeds_and_skips_delete_when_cache_empty — redis.scan yields (0, []); assert redis.delete not called, returns falsy, info log reports 0 host(s). Locks down: empty cache is success, not error.
• test_facts_limit_deletes_only_selected_hosts — args ["-l","control"]; subprocess.run returns returncode=0 with inventory JSON; get_hosts_from_inventory → ["node1","node2"]; assert redis.delete called with "ansible_factsnode1" and "ansible_factsnode2", no scan, returns falsy. Locks down: limit path expands group→hosts and deletes per-host keys only.
• test_facts_limit_returns_nonzero_when_inventory_fails — subprocess.run returns returncode=1; assert returns 1, redis.delete not called, error logged. Locks down: inventory failure is a hard error, cache untouched.
• test_facts_limit_warns_and_succeeds_when_no_hosts_match — inventory ok but get_hosts_from_inventory → []; assert returns falsy, warning logged, no delete. Locks down: empty match is a no-op success.

Documentation Plan

• osism/commands/reset.py — class docstring + --limit argument help text are the user-facing documentation (cliff renders them in osism reset facts --help and osism --help). This is the only in-repo doc surface.
• CHANGELOG.md — none in this PR. Changelog entries are added in batch by maintainers at release time (per git history), not in feature PRs.
• External CLI reference (osism.tech references/cli) — out of scope (separate repository); note for maintainers that the new reset facts command should be added there.

Verification Commands

• pipenv install --dev (once, to install the entry point so osism reset facts --help works end-to-end)
• pipenv run pytest tests/unit/commands/test_reset.py
• pipenv run pytest (full unit suite — testpaths = tests/unit, setup.cfg:178)
• flake8 osism/commands/reset.py tests/unit/commands/test_reset.py (config .flake8, max-line-length = 200)

(Per project convention these also run in CI/Zuul; the user prefers to commit and let CI run them.)

Risks & Open Questions

• Command name is a design decision, not specified by the issue. I chose osism reset facts (mirror of the existing sync facts writer, discoverable, no namespace collision). Alternatives a maintainer might prefer: sync facts --clear/--reset (rejected — the issue states it must not start a gather, and overloading the gather command is confusing) or a facts reset group. Renaming is a one-line change to the setup.cfg entry point; flagged so a maintainer can veto before merge.
• A second fact cache exists at /cache/facts/<host> (file/jsonfile), read only by osism/api.py:1026 search_inventory. The plan clears the Redis cache only, because (1) Redis ansible_facts* is the canonical Ansible fact cache and the store every operator-facing CLI command reads, and (2) /cache/facts is an absolute path likely mounted only in specific containers and may not be writable from where the CLI runs. If operators also need the API's file cache cleared, the implementer should additionally remove /cache/facts/<host> files (guarded by os.path.exists) — but that is speculative scope absent confirmation. Open question for the maintainer; does not block the Redis implementation.
• --limit requires the inventory at /ansible/inventory/hosts.yml (same assumption as get.py, report.py, rabbitmq.py). The flush-all path has no such dependency. Acceptable and consistent with existing commands.

Status

STATUS: PLAN_READY

---

Implementation plan generated by planwerk-review implement with Claude

[berendt]

Implementation Report (issue #2388)

Acceptance Criteria

The issue has no explicit "Acceptance Criteria" section; the Description is the contract.

• Add an osism command that clears the Ansible fact cache.
  • Status: satisfied
  • Evidence: osism/commands/reset.py (class Facts), registered as reset facts = osism.commands.reset:Facts in setup.cfg:132.
• By default the command flushes the entire cache.
  • Status: satisfied
  • Evidence: osism/commands/reset.py:39-58 (_reset_all SCANs ansible_facts* and batch-deletes); test test_facts_flushes_all_keys_when_no_limit and edge test test_facts_succeeds_and_skips_delete_when_cache_empty.
• A parameter restricts the operation to selected hosts or groups.
  • Status: satisfied
  • Evidence: -l/--limit at osism/commands/reset.py:24-30, expanded via ansible-inventory --list --limit at :60-95; test test_facts_limit_deletes_only_selected_hosts and edge test test_facts_limit_warns_and_succeeds_when_no_hosts_match.
• It only clears the cache — does not start a fact-gathering run; no confirmation prompt.
  • Status: satisfied
  • Evidence: reset.py performs only Redis deletes (no ansible.run/celery call, no prompt). Inventory-failure edge test test_facts_limit_returns_nonzero_when_inventory_fails confirms the cache is left untouched on error.

Commits

• 4da9b13 Add 'osism reset facts' command to clear the fact cache
• f6c5ace Add unit tests for 'osism reset facts'

Local verification

• flake8 osism/commands/reset.py tests/unit/commands/test_reset.py — pass
• pytest tests/unit — skipped: per project convention and user preference, the suite runs in CI/Zuul (commit and let CI run tests)

Pull Request

• URL: Add 'osism reset facts' command to clear the Ansible fact cache #2389 (draft)
• Branch: implement/issue-2388-reset-facts

Deviations from the issue

• Command name reset facts is a design choice the issue left open (flagged in the PR for maintainer veto; renaming is a one-line setup.cfg change).
• Redis cache only — the file-based /cache/facts/<host> cache (read solely by osism/api.py:search_inventory) is intentionally not cleared, as it is out of scope absent a confirmed need. Noted in the PR.
• Note on the plan: the first commit was authored by a prior run of this session, which followed the plan's RedisError handling verbatim. I kept it rather than revert: it logs with context and returns a non-zero exit (consistent with the Silent-Failures pattern), and added a dedicated test_facts_returns_nonzero_on_redis_error test to lock that branch down. (I also added a timeout test beyond the plan's list to match report.py's contract.)

Status

STATUS: DONE

---

Implementation report generated by planwerk-review implement with Claude