Bug Report: ACL Statistics Parameter Missing in Gathered Facts

[tukaisg]

Bug Report: ACL Statistics Parameter Missing in Gathered Facts

Issue Description

The cisco.nxos.nxos_acls module does not support the statistics per-entry parameter when gathering facts or configuring access lists. This parameter is essential for monitoring and troubleshooting access list performance but is ignored during facts collection and configuration deployment.

Affected Versions

• ansible [core 2.15.4]
• cisco.nxos collection (current version)
• AAP_VERSION=2.4

Reproduction Case

Device Configuration

ip access-list TAC
  statistics per-entry
  10 permit ip any any
  20 deny tcp any any

Current Module Behavior

The statistics per-entry parameter is not captured in gathered facts and cannot be configured through the nxos_acls module.

Test Case Analysis

The existing test cases in the collection demonstrate the issue by including statistics per-entry in the input but ignoring it in expected results:

File: cisco.nxos/tests/unit/modules/network/nxos/test_nxos_acls.py

def test_nxos_acls_parsed(self):
    set_module_args(
        dict(
            running_config=dedent(
                """
                ip access-list ACL1v4
                  statistics per-entry
                  10 permit ip any any
                  20 deny udp any any dscp AF23 precedence critical
                """,
            ),
            state="parsed",
        ),
    )
    result = self.execute_module(changed=False)
    compare_list = [
        {
            "afi": "ipv4",
            "acls": [
                {
                    "name": "ACL1v4",
                    "aces": [
                        {
                            "grant": "permit",
                            "sequence": 10,
                            "protocol": "ip",
                            "source": {"any": True},
                            "destination": {"any": True},
                        },
                        {
                            "grant": "deny",
                            "sequence": 20,
                            "protocol": "udp",
                            "source": {"any": True},
                            "destination": {"any": True},
                            "dscp": "AF23",
                            "precedence": "critical",
                        },
                    ],
                },
            ],
        },
    ]
    self.assertEqual(result["parsed"], compare_list, result["parsed"])

Critical Issue: The test case includes statistics per-entry in the input configuration but completely omits it from the expected results (compare_list). This demonstrates that:

1. The module silently ignores the statistics parameter during parsing
2. No validation occurs to ensure statistics configuration is captured
3. The test passes despite missing functionality, effectively masking the bug

Expected Result Should Include:

{
    "afi": "ipv4",
    "acls": [
        {
            "name": "ACL1v4",
            "statistics": {
                "per_entry": True  # This is missing from current test
            },
            "aces": [...]
        }
    ]
}

Root Cause

The cisco.nxos.nxos_acls module implementation lacks support for the statistics option. The module's argument specification and parsing logic do not include this parameter.

Detailed Technical Analysis

1. Module Argument Specification Gap

File: cisco.nxos/plugins/module_utils/network/nxos/argspec/acls/acls.py

The argument specification for the nxos_acls module completely lacks any definition for statistics parameters. The argspec only includes basic ACE parameters but no statistics parameter at the ACL level.

2. Facts Gathering Implementation Gap

File: cisco.nxos/plugins/module_utils/network/nxos/facts/acls/acls.py

The facts gathering logic in the render_config method processes various ACL parameters but has no logic to parse or extract statistics configuration. The current parsing covers ACL name extraction and ACE entries but is missing parsing logic for statistics per-entry commands.

3. Configuration Template Gap

The configuration generation logic lacks support for rendering statistics commands since the argspec doesn't define them.

4. Device Command Pattern Not Recognized

The facts gathering uses regex patterns to parse running configuration, but there's no pattern to match:

ip access-list TAC
  statistics per-entry

The current parsing logic splits on ACL boundaries but doesn't look for statistics commands within ACL definitions.

Impact

• Incomplete ACL configuration management
• Unable to enable per-entry statistics for monitoring and troubleshooting
• Configuration drift between intended and deployed ACL configurations
• Manual intervention required for ACL statistics configuration

Gather Facts Completeness Issue

Core Principle Violation

The gather facts functionality should include ALL facts related to the specific module. The nxos_acls module's facts gathering is fundamentally incomplete because it fails to capture the statistics per-entry parameter that is part of the ACL configuration.

Expected Behavior for Facts Gathering

When using state: gathered, the module should return complete and accurate facts that represent the entire ACL configuration on the device, including:

• ACL names and types (IPv4/IPv6)
• All ACE entries with their parameters
• Statistics configuration (currently missing)
• Any other ACL-level parameters

Current Facts Gathering Gap

The current implementation violates the principle of complete facts gathering by:

1. Selective Parsing: Only parsing ACE entries while ignoring ACL-level parameters like statistics
2. Incomplete State Representation: The gathered facts do not represent the true device state
3. Configuration Drift: Subsequent deployments based on incomplete facts will lose the statistics configuration

Impact on Automation Workflows

This incomplete facts gathering breaks common automation patterns:

# Step 1: Gather current configuration
- name: Gather ACL facts
  cisco.nxos.nxos_acls:
    state: gathered
  register: current_acls

# Step 2: Modify configuration (statistics will be lost!)
- name: Update ACL configuration  
  cisco.nxos.nxos_acls:
    config: "{{ current_acls.gathered | modify_acls }}"
    state: merged

Result: The statistics configuration is silently lost during this workflow because it was never captured in the gathered facts.

Expected Behavior

The module should support a statistics parameter that allows configuration of:

• statistics per-entry - Enable per-entry statistics collection

Current Workarounds

• Using cisco.nxos.nxos_config module with raw commands
• Manual configuration of statistics parameter outside Ansible automation

Recommended Solution

1. Enhance the nxos_acls module to support the statistics parameter
2. Update the module's argument specification to include statistics options
3. Add test cases covering statistics parameter scenarios
4. Update module documentation with statistics parameter usage
5. Review and include other ACL-level configuration parameters (besides statistics) in the gathered facts to ensure comprehensive and accurate representation of ACLs.

Status

• Issue identified: July 8, 2025
• GitHub issue to be created in cisco.nxos collection repository
• Status: In Progress - Waiting for module enhancement