`netops.playbooks` — Ansible Playbook Generation¶

Composable Ansible remediation playbook generation from health-check reports.

`netops.playbooks.generator`¶

Generate Ansible remediation playbooks from structured health-check failure data.

CLI usage:

python -m netops.playbooks.generator --report health-report.json --output remediation.yml
python -m netops.playbooks.generator --report health-report.json --vendor cisco_ios

generator ¶

Playbook generator — auto-generate Ansible remediation playbooks from health check failures.

Reads a health check report (produced by :func:netops.check.health.run_health_check or :func:netops.check.health.build_health_report) and generates valid Ansible YAML playbooks for each device with active alerts.

Generated playbooks:

Use vendor-specific Ansible collection modules (e.g. cisco.ios.ios_command)
Include pre/post validation tasks that capture device state before and after remediation for comparison
Wrap each remediation in a block/rescue structure so that the rescue section runs the rollback tasks on failure
Default to dry-run mode (dry_run: "true" variable) — remediation tasks are guarded by when: not dry_run | bool so the playbook is safe to inspect in CI before live execution
Prompt for human review before executing remediation (unless --no-pause is passed to the CLI)

Usage::

# Generate playbooks from a saved health report (dry-run, print to stdout)
python -m netops.playbooks.generator generate \\
    --from-health-report health_report.json

# Write playbooks to a directory (one file per device with failures)
python -m netops.playbooks.generator generate \\
    --from-health-report health_report.json \\
    --output-dir ./remediation-playbooks/

# Override vendor when the report does not carry device_type
python -m netops.playbooks.generator generate \\
    --from-health-report health_report.json \\
    --vendor cisco_ios_xr

# Mark playbook ready for live execution (dry_run=false in the vars block):
python -m netops.playbooks.generator generate \\
    --from-health-report health_report.json \\
    --live

Public API::

from netops.playbooks.generator import (
    FailureType,
    GeneratedPlaybook,
    extract_failures,
    generate_playbook,
    generate_playbooks_from_report,
)

Classes¶

FailureType ¶

Bases: str, Enum

Health-check failure categories that can be remediated.

GeneratedPlaybook `dataclass` ¶

GeneratedPlaybook(playbook_id: str, host: str, vendor: str, failure_types: list[FailureType], description: str, plays: list[dict], dry_run: bool = True, created_at: str = '', source_report_timestamp: str = '')

A complete Ansible playbook generated from health-check failures.

Attributes:

Name	Type	Description
`playbook_id`	`str`	UUID string for correlation with health report entries.
`host`	`str`	Ansible inventory hostname / IP targeted by the playbook.
`vendor`	`str`	Device type string (e.g. `cisco_ios`) used to select the correct Ansible collection modules.
`failure_types`	`list[FailureType]`	List of :class:`FailureType` values that were detected and addressed.
`description`	`str`	Human-readable summary used in the top-level play name.
`plays`	`list[dict]`	List of Ansible play dicts ready for serialisation to YAML.
`dry_run`	`bool`	When `True` the generated vars block sets `dry_run: "true"` so remediation tasks are skipped unless the operator overrides the var.
`created_at`	`str`	ISO-8601 UTC timestamp of generation.
`source_report_timestamp`	`str`	Timestamp from the originating health check result.

Methods:¶

to_yaml ¶

to_yaml() -> str

Serialise the playbook plays to Ansible-compatible YAML.

to_dict ¶

to_dict() -> dict

Return a JSON-serialisable dict representation of this playbook.

Functions:¶

extract_failures ¶

extract_failures(health_result: dict) -> list[tuple[FailureType, dict]]

Extract alerting checks from a single device health-check result.

Parameters:

Name	Type	Description	Default
`health_result`	`dict`	A result dict as returned by :func:`netops.check.health.run_health_check` or a vendor-specific equivalent. Must contain a `"checks"` key mapping check names to check result dicts with an `"alert"` boolean.	required

Returns:

Type	Description
`list[tuple[FailureType, dict]]`	Ordered list of `(failure_type, check_detail)` pairs for every check where `alert` is `True`.

generate_playbook ¶

generate_playbook(health_result: dict, vendor: str | None = None, dry_run: bool = True, include_pause: bool = True) -> GeneratedPlaybook | None

Generate a remediation playbook from a single device health-check result.

Parameters:

Name	Type	Description	Default
`health_result`	`dict`	A result dict as returned by :func:`netops.check.health.run_health_check`.	required
`vendor`	`str \| None`	Override the device vendor string. When `None`, the value is taken from `health_result["device_type"]` if present; otherwise the generic `_default` module mapping is used.	`None`
`dry_run`	`bool`	When `True` (the default), remediation tasks are gated behind `when: not dry_run \| bool` so the playbook can be safely reviewed before live execution.	`True`
`include_pause`	`bool`	When `True`, inserts a `ansible.builtin.pause` task that requires operator acknowledgement before executing remediation tasks. The pause is itself gated by `when: not dry_run \| bool` so it never blocks dry-run or CI runs.	`True`

Returns:

Type	Description
`GeneratedPlaybook \| None`	A :class:`GeneratedPlaybook` when at least one alerting check is found. Returns `None` when the device has no active alerts or the result is not successful.

generate_playbooks_from_report ¶

generate_playbooks_from_report(health_report: dict, vendor: str | None = None, dry_run: bool = True, include_pause: bool = True, host_filter: str | None = None) -> list[GeneratedPlaybook]

Generate remediation playbooks from an aggregated health report.

Accepts the dict returned by :func:netops.check.health.build_health_report (which contains a "results" list) or a bare list of per-device health results.

Parameters:

Name	Type	Description	Default
`health_report`	`dict`	Dict with a `"results"` key (from :func:`build_health_report`) or a bare list of per-device health result dicts.	required
`vendor`	`str \| None`	Global vendor override applied to all devices. Per-device `device_type` fields take precedence when vendor is `None`.	`None`
`dry_run`	`bool`	Passed to :func:`generate_playbook` for every device.	`True`
`include_pause`	`bool`	Passed to :func:`generate_playbook` for every device.	`True`
`host_filter`	`str \| None`	When given, only generate a playbook for the device whose `host` field matches this value (case-insensitive substring match).	`None`

Returns:

Type	Description
`list[GeneratedPlaybook]`	One playbook per device that has at least one active alert.

main ¶

main() -> None

CLI entry point for the remediation playbook generator.

`netops.playbooks.templates.remediation`¶

Built-in remediation templates for common network failure types.

Provides REMEDIATION_TEMPLATES — a dict mapping FailureType to RemediationTemplate — and helper functions for looking up and rendering templates.

remediation ¶

Vendor-specific remediation templates for playbook generation.

Each :class:RemediationTemplate encapsulates the commands needed to:

Pre-validate the device state before remediation
Remediate the failure condition
Post-validate that the remediation succeeded
Rollback (undo) the remediation when possible

Vendor command modules are mapped by the VENDOR_COMMAND_MODULE and VENDOR_CONFIG_MODULE dicts so that the generator can pick the correct Ansible collection for each platform.

Public API::

from netops.playbooks.templates.remediation import (
    RemediationTemplate,
    REMEDIATION_TEMPLATES,
    VENDOR_COMMAND_MODULE,
    VENDOR_CONFIG_MODULE,
    get_template,
)

Classes¶

RemediationTemplate `dataclass` ¶

RemediationTemplate(failure_type: str, description: str, pre_commands: dict[str, list[str]] = dict(), remediation_commands: dict[str, list[str]] = dict(), post_commands: dict[str, list[str]] = dict(), rollback_commands: dict[str, list[str]] = dict(), rollback_note: str = '')

Vendor-specific command sets for a single remediation action.

Attributes:

Name	Type	Description
`failure_type`	`str`	The :class:`~netops.playbooks.generator.FailureType` string value this template targets.
`description`	`str`	Human-readable description shown in generated playbook task names.
`pre_commands`	`dict[str, list[str]]`	Dict mapping vendor `device_type` strings (plus `_default`) to a list of CLI commands to run before remediation for state capture.
`remediation_commands`	`dict[str, list[str]]`	Dict mapping vendor to remediation commands. `None` or an empty dict means "no automated remediation available — human review only".
`post_commands`	`dict[str, list[str]]`	Dict mapping vendor to post-validation commands (same shape as pre).
`rollback_commands`	`dict[str, list[str]]`	Dict mapping vendor to rollback/undo commands. Empty when the action cannot be rolled back (e.g. counter clearing).
`rollback_note`	`str`	Human-readable note explaining rollback behaviour or limitations.

Methods:¶

commands_for ¶

commands_for(vendor: str, kind: str) -> list[str]

Return the command list for vendor in kind (pre/remediation/post/rollback).

Falls back to _default when the specific vendor is not listed. Returns an empty list when neither vendor nor default exists.

Functions:¶

get_template ¶

get_template(failure_type: str) -> RemediationTemplate | None

Return the :class:RemediationTemplate for failure_type, or None.

netops.playbooks — Ansible Playbook Generation¶

netops.playbooks.generator¶

generator ¶

Classes¶

FailureType ¶

GeneratedPlaybook dataclass ¶

Functions:¶

extract_failures ¶

generate_playbook ¶

generate_playbooks_from_report ¶

main ¶

netops.playbooks.templates.remediation¶

remediation ¶

Classes¶

RemediationTemplate dataclass ¶

Functions:¶

get_template ¶

`netops.playbooks` — Ansible Playbook Generation¶

`netops.playbooks.generator`¶

GeneratedPlaybook `dataclass` ¶

`netops.playbooks.templates.remediation`¶

RemediationTemplate `dataclass` ¶