Ansible Knowledge Patch

Ansible Core Knowledge Patch

Use this skill when changing Ansible playbooks, inventories, controller plugins, connection settings, test targets, or modules that depend on current ansible-core behavior.

Working Method

1. Determine the installed or pinned ansible-core version from dependency manifests, execution-environment definitions, or lockfiles.
2. Inspect the affected playbooks and plugins for the migration points below.
3. Open the topic reference before changing behavior that depends on exact configuration names, defaults, or plugin APIs.
4. Apply only guidance introduced at or below the project's version. If the project is newer than the frontmatter version, treat this patch as potentially stale.
5. Prefer project tests and observed runtime behavior when a project carries compatibility shims or backports.

Reference Index

Highest-Priority Migration Checks

Treat templating as trusted and single-pass

• Jinja expressions in untrusted strings, including facts and module results, are not evaluated merely because the strings contain delimiters.
• Preserve trust when a plugin transforms a value that is intended to remain a template. Apply trust explicitly when a plugin creates such a value.
• Remove designs that depend on one template producing another template for a later pass.
• Do not wrap ordinary conditionals in {{ ... }}. A whole trusted string expression is the narrow exception.

# Preferred
when: service_enabled | bool

# Avoid
when: "{{ service_enabled | bool }}"

Expect native values and boolean conditionals

• Template results retain native types; do not assume automatic string conversion.
• Do not assume None becomes an empty string.
• set_fact preserves the literal strings yes, no, true, and false when they are supplied as strings.
• A conditional must produce a boolean. Use an explicit comparison or a suitable conversion instead of relying on truthiness.
• Compatibility mode for broken conditionals is temporary and should only support a staged migration.

- name: Use an explicit boolean conversion
  ansible.builtin.debug:
    msg: enabled
  when: feature_flag | bool

Audit lazy values and omit

• Only accessed portions of a structure are templated, so errors may surface later than structure construction.
• omit is removed from its parent container during templating.
• In loops, use default(omit) on the value that should disappear from module arguments.
• Code calling Templar.template() must handle AnsibleValueOmittedError when the complete result is omitted.

- ansible.builtin.user:
    name: "{{ item.name }}"
    shell: "{{ item.shell | default(omit) }}"
  loop: "{{ users }}"

Plugin and Extension Quick Reference

Controller-side code

• Task forks do not provide functional standard input, output, or error streams. Use Display for controller-side messages.
• Convert Ansible-provided subclasses of Python builtins to plain native types before passing them to strict third-party libraries.
• Builtin Jinja filters and tests may be addressed with the ansible.builtin.<name> form.
• Python packages below module_utils may contain __init__.py.

Callback, strategy, and Jinja migration

• Callback plugins must derive from CallbackBase.
• Replace the v1 callback API and v2_on_any with the specific v2_ callbacks.
• Third-party strategy plugins are deprecated without a planned replacement.
• Replace custom Jinja extensions with filter, test, or lookup plugins.
• A Jinja plugin must explicitly opt in before accepting an undefined top-level argument.
• Code using environment.getitem must handle MarkerError and return a marker, or explicitly opt in to marker values.

Connection and Privilege Quick Reference

SSH authentication

• The SSH connection uses SSH_ASKPASS by default for password prompting.
• ansible, ansible-playbook, and ansible-console can create or reuse an SSH agent.
• ansible_ssh_private_key and ansible_ssh_private_key_passphrase can load a key from variables.
• Set SSH_AGENT_EXECUTABLE to choose the agent binary.
• Use ANSIBLE_SSH_VERBOSITY or ansible_ssh_verbosity for SSH-only verbosity.

Removed and deprecated transports

• Do not introduce a Paramiko dependency; migrate inventory and configuration to the SSH connection.
• Remove DEFAULT_TRANSPORT=smart, PARAMIKO_HOST_KEY_AUTO_ADD, and PARAMIKO_LOOK_FOR_KEYS.
• For the local connection, account for become_strip_preamble defaulting to true and become_success_timeout defaulting to 10 seconds.
• sudo_chdir changes directory before invoking sudo.

Playbook, CLI, and Inventory Quick Reference

• Use --flush-cache where cache invalidation is needed with ansible, ansible-console, or ansible-pull.
• Inventory files ending in .ini are parsed by default unless ini is put back into INVENTORY_IGNORE_EXTS.
• Use DISPLAY_TRACEBACK to control tracebacks; -vvv is not the traceback switch.
• Consume task-result warnings and deprecations when building diagnostic tooling.
• Prefer --inventory over the deprecated --inventory-file alias.
• Replace play_hosts with ansible_play_batch.
• Remove empty args, mapping-form action, and combinations of key=value arguments with args.
• Set ansible_managed as a regular variable instead of using DEFAULT_MANAGED_STR.

Validate play arguments

Set validate_argspec: true to select the required play name, or use a string to select another entry from <playbook_name>.meta.yml.

# deploy.yml
- name: deploy
  hosts: all
  validate_argspec: true

# deploy.meta.yml
argument_specs:
  deploy:
    options:
      environment:
        type: str
        required: true

Modules, Facts, and Results Quick Reference

• Migrate injected top-level facts such as ansible_os_distribution to ansible_facts['os_distribution'].
• Prefer the vars and varnames lookups over the internal variable cache.
• Read per-volume-group logical volumes from each ansible_facts['vgs'] entry's lvs subkey when completeness matters.
• async_status.started and async_status.finished are booleans, not integer flags.
• Pass lists to include_vars.extensions and include_vars.ignore_files.
• Use encoding with blockinfile and lineinfile for non-UTF-8 files.
• Expect replace to read, match, and write Unicode text.
• Review automatic dependency installation in apt, dnf5, and deb822_repository before relying on minimal target images.
• Treat non-UTF-8 module response strings as errors; disabling strict checking is a compatibility escape hatch.

Test and Upgrade Checklist

• Exercise templates with facts and module-result strings containing literal Jinja delimiters.
• Test conditionals for genuine boolean results.
• Cover loop arguments that can resolve to omit.
• Run custom plugins without functional standard streams.
• Test SSH agent creation, key loading, and local become timeout behavior.
• Verify inventory discovery for .ini files.
• Assert boolean async-status fields in integrations.
• Run Windows automation under the intended PowerShell host and application control policy.
• Give ansible-test enough deadline headroom to emit pre-timeout thread diagnostics.
• Check the detailed references before removing compatibility workarounds.