Парсинг полуструктурированного текста с Ansible

Зачем парсить текст?

Парсинг полуструктурированных данных, таких как конфигурации сети, в структурированные данные позволяет программно использовать данные с этого устройства. Сценарии использования включают автоматизированную диагностику, создание динамической документации, обновление инструментов IPAM (управление IP-адресами) и так далее. Вы можете выполнить это с помощью Ansible для использования встроенных возможностей Ansible, таких как:

• Оператор when для условного выполнения других задач или ролей
• Модуль assert для проверки соответствия конфигурации и операционного состояния
• Модуль template для создания отчетов о конфигурации и операционном состоянии
• Шаблоны и модули command или config для генерации команд или конфигурации хоста, устройства или платформы
• Модули текущей платформы facts для дополнения информации о фактах

Преобразуя полуструктурированный текст в стандартные структуры данных Ansible, вы можете в полной мере воспользоваться сетевыми модулями и плагинами Ansible.

Когда не следует парсить текст

Вы не должны парсить полуструктурированный текст, когда:

• Устройство, хост или платформа имеют RESTAPI и возвращают JSON.
• Существующие модули Ansible facts уже возвращают нужные данные.
• Существуют сетевые модули Ansible для управления конфигурацией устройства и ресурса.

Разбор с помощью встроенного движка разбора

Встроенный движок разбора включен в модуль cli_parse. Он использует данные, полученные с помощью регулярных выражений, для заполнения структуры данных, полученной в результате разбора. Встроенный движок разбора требует файл шаблона YAML для разбора вывода команды.

Ethernet1/1 is up
admin state is up, Dedicated Interface
  Hardware: 100/1000/10000 Ethernet, address: 5254.005a.f8bd (bia 5254.005a.f8bd)
  MTU 1500 bytes, BW 1000000 Kbit, DLY 10 usec
  reliability 255/255, txload 1/255, rxload 1/255
  Encapsulation ARPA, medium is broadcast
  Port mode is access
  full-duplex, auto-speed
  Beacon is turned off
  Auto-Negotiation is turned on  FEC mode is Auto
  Input flow-control is off, output flow-control is off
  Auto-mdix is turned off
  Switchport monitor is off
  EtherType is 0x8100
  EEE (efficient-ethernet) : n/a
  Last link flapped 4week(s) 6day(s)
  Last clearing of "show interface" counters never
<...>

---
- example: Ethernet1/1 is up
  getval: '(?P<name>\S+) is (?P<oper_state>\S+)'
  result:
    "{{ name }}":
      name: "{{ name }}"
      state:
        operating: "{{ oper_state }}"
  shared: true

- example: admin state is up, Dedicated Interface
  getval: 'admin state is (?P<admin_state>\S+),'
  result:
    "{{ name }}":
      name: "{{ name }}"
      state:
        admin: "{{ admin_state }}"

- example: "  Hardware: Ethernet, address: 5254.005a.f8b5 (bia 5254.005a.f8b5)"
  getval: '\s+Hardware: (?P<hardware>.*), address: (?P<mac>\S+)'
  result:
    "{{ name }}":
      hardware: "{{ hardware }}"
      mac_address: "{{ mac }}"

- name: "Run command and parse with native"
  ansible.utils.cli_parse:
    command: show interface
    parser:
      name: ansible.netcommon.native
    set_fact: interfaces

Ethernet1/1:
    hardware: 100/1000/10000 Ethernet
    mac_address: 5254.005a.f8bd
    name: Ethernet1/1
    state:
    admin: up
    operating: up
Ethernet1/10:
    hardware: 100/1000/10000 Ethernet
    mac_address: 5254.005a.f8c6
<...>

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
2: enp0s31f6: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN group default qlen 1000
    link/ether x2:6a:64:9d:84:19 brd ff:ff:ff:ff:ff:ff
3: wlp2s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether x6:c2:44:f7:41:e0 brd ff:ff:ff:ff:ff:ff permaddr d8:f2:ca:99:5c:82

---
- example: '1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000'
  getval: |
    (?x)                                                # free-spacing
    \d+:\s                                              # the interface index
    (?P<name>\S+):\s                                    # the name
    <(?P<properties>\S+)>                               # the properties
    \smtu\s(?P<mtu>\d+)                                 # the mtu
    .*                                                  # gunk
    state\s(?P<state>\S+)                               # the state of the interface
  result:
    "{{ name }}":
        name: "{{ name }}"
        loopback: "{{ 'LOOPBACK' in stats.split(',') }}"
        up: "{{ 'UP' in properties.split(',')  }}"
        carrier: "{{ not 'NO-CARRIER' in properties.split(',') }}"
        broadcast: "{{ 'BROADCAST' in properties.split(',') }}"
        multicast: "{{ 'MULTICAST' in properties.split(',') }}"
        state: "{{ state|lower() }}"
        mtu: "{{ mtu }}"
  shared: True

- example: 'inet 192.168.122.1/24 brd 192.168.122.255 scope global virbr0'
  getval: |
   (?x)                                                 # free-spacing
   \s+inet\s(?P<inet>([0-9]{1,3}\.){3}[0-9]{1,3})       # the ip address
   /(?P<bits>\d{1,2})                                   # the mask bits
  result:
    "{{ name }}":
        ip_address: "{{ inet }}"
        mask_bits: "{{ bits }}"

- name: Run command and parse
  ansible.utils.cli_parse:
    command: ip addr show
    parser:
      name: ansible.netcommon.native
    set_fact: interfaces

lo:
  broadcast: false
  carrier: true
  ip_address: 127.0.0.1
  mask_bits: 8
  mtu: 65536
  multicast: false
  name: lo
  state: unknown
  up: true
enp64s0u1:
  broadcast: true
  carrier: true
  ip_address: 192.168.86.83
  mask_bits: 24
  mtu: 1500
  multicast: true
  name: enp64s0u1
  state: up
  up: true
<...>

Разбор JSON

Хотя Ansible по умолчанию преобразует сериализованный JSON в структуру данных Ansible при распознавании, вы также можете использовать модуль cli_parse для этого преобразования.

Пример задачи:

- name: "Run command and parse as json"
  ansible.utils.cli_parse:
    command: show interface | json
    parser:
      name: ansible.utils.json
    register: interfaces

Более подробное рассмотрение этой задачи:

• Выполняется команда show interface | json на устройстве.
• Вывод устанавливается как переменная interfaces для устройства.
• Поддержка JSON предоставляется в основном для согласованности выполнения задач.

Разбор с использованием ntc_templates

Библиотека Python ntc_templates включает предварительно определённые textfsm шаблоны для разбора вывода различных сетевых команд устройств.

Пример задачи:

- name: "Run command and parse with ntc_templates"
  ansible.utils.cli_parse:
    command: show interface
    parser:
      name: ansible.netcommon.ntc_templates
    set_fact: interfaces

Более подробное рассмотрение этой задачи:

• Вывод ansible_network_os устройства преобразуется в формат ntc_template cisco_nxos. В качестве альтернативы, вы можете указать os с помощью опции parser/os.
• Шаблон cisco_nxos_show_interface.textfsm, включённый в пакет ntc_templates, выполняет разбор вывода.
• Дополнительную информацию о библиотеке Python ntc_templates см. в файле README ntc_templates.

В этой задаче и заданных шаблонах переменная interfaces устанавливается как значение переменной

interfaces:
- address: 5254.005a.f8b5
  admin_state: up
  bandwidth: 1000000 Kbit
  bia: 5254.005a.f8b5
  delay: 10 usec
  description: ''
  duplex: full-duplex
  encapsulation: ARPA
  hardware_type: Ethernet
  input_errors: ''
  input_packets: ''
  interface: mgmt0
  ip_address: 192.168.101.14/24
  last_link_flapped: ''
  link_status: up
  mode: ''
  mtu: '1500'
  output_errors: ''
  output_packets: ''
  speed: 1000 Mb/s
- address: 5254.005a.f8bd
  admin_state: up
  bandwidth: 1000000 Kbit
  bia: 5254.005a.f8bd
  delay: 10 usec

Разбор с помощью pyATS

pyATS является частью решения Cisco Test Automation & Validation. Оно включает множество предварительно определенных парсеров для ряда сетевых платформ и команд. Вы можете использовать предварительно определенные парсеры, которые входят в пакет pyATS с модулем cli_parse.

Пример задачи:

- name: "Run command and parse with pyats"
  ansible.utils.cli_parse:
    command: show interface
    parser:
      name: ansible.netcommon.pyats
    set_fact: interfaces

Более подробное рассмотрение этой задачи:

• Модуль cli_parse преобразует ansible_network_os автоматически (в этом примере ansible_network_os установлено как cisco.nxos.nxos, преобразуется в nxos для pyATS. В качестве альтернативы, вы можете установить операционную систему с помощью опции parser/os).
• Используя комбинацию команды и операционной системы, pyATS выбирает следующий парсер: https://pubhub.devnetcloud.com/media/genie-feature-browser/docs/#/parsers/show%2520interface.
• Модуль cli_parse устанавливает cisco.ios.ios на iosxe для pyATS. Вы можете переопределить это с помощью опции parser/os.
• cli_parse использует только предварительно определённые парсеры в pyATS. См. документацию pyATS и полный список включённых в pyATS парсеров.

В этой задаче переменная interfaces устанавливается как значение переменной

mgmt0:
  admin_state: up
  auto_mdix: 'off'
  auto_negotiate: true
  bandwidth: 1000000
  counters:
    in_broadcast_pkts: 3
    in_multicast_pkts: 1652395
    in_octets: 556155103
    in_pkts: 2236713
    in_unicast_pkts: 584259
    rate:
      in_rate: 320
      in_rate_pkts: 0
      load_interval: 1
      out_rate: 48
      out_rate_pkts: 0
    rx: true
    tx: true
  delay: 10
  duplex_mode: full
  enabled: true
  encapsulations:
    encapsulation: arpa
  ethertype: '0x0000'
  ipv4:
    192.168.101.14/24:
      ip: 192.168.101.14
      prefix_length: '24'
  link_state: up
  <...>

Парсинг с помощью textfsm

textfsm — это модуль Python, который реализует основанную на шаблонах конечный автомат для парсинга полуформатированного текста.

Следующий пример textfsm шаблон хранится как templates/nxos_show_interface.textfsm

Value Required INTERFACE (\S+)
Value LINK_STATUS (.+?)
Value ADMIN_STATE (.+?)
Value HARDWARE_TYPE (.\*)
Value ADDRESS ([a-zA-Z0-9]+.[a-zA-Z0-9]+.[a-zA-Z0-9]+)
Value BIA ([a-zA-Z0-9]+.[a-zA-Z0-9]+.[a-zA-Z0-9]+)
Value DESCRIPTION (.\*)
Value IP_ADDRESS (\d+\.\d+\.\d+\.\d+\/\d+)
Value MTU (\d+)
Value MODE (\S+)
Value DUPLEX (.+duplex?)
Value SPEED (.+?)
Value INPUT_PACKETS (\d+)
Value OUTPUT_PACKETS (\d+)
Value INPUT_ERRORS (\d+)
Value OUTPUT_ERRORS (\d+)
Value BANDWIDTH (\d+\s+\w+)
Value DELAY (\d+\s+\w+)
Value ENCAPSULATION (\w+)
Value LAST_LINK_FLAPPED (.+?)

Start
  ^\S+\s+is.+ -> Continue.Record
  ^${INTERFACE}\s+is\s+${LINK_STATUS},\sline\sprotocol\sis\s${ADMIN_STATE}$$
  ^${INTERFACE}\s+is\s+${LINK_STATUS}$$
  ^admin\s+state\s+is\s+${ADMIN_STATE},
  ^\s+Hardware(:|\s+is)\s+${HARDWARE_TYPE},\s+address(:|\s+is)\s+${ADDRESS}(.*bia\s+${BIA})*
  ^\s+Description:\s+${DESCRIPTION}
  ^\s+Internet\s+Address\s+is\s+${IP_ADDRESS}
  ^\s+Port\s+mode\s+is\s+${MODE}
  ^\s+${DUPLEX}, ${SPEED}(,|$$)
  ^\s+MTU\s+${MTU}.\*BW\s+${BANDWIDTH}.\*DLY\s+${DELAY}
  ^\s+Encapsulation\s+${ENCAPSULATION}
  ^\s+${INPUT_PACKETS}\s+input\s+packets\s+\d+\s+bytes\s\*$$
  ^\s+${INPUT_ERRORS}\s+input\s+error\s+\d+\s+short\s+frame\s+\d+\s+overrun\s+\d+\s+underrun\s+\d+\s+ignored\s\*$$
  ^\s+${OUTPUT_PACKETS}\s+output\s+packets\s+\d+\s+bytes\s\*$$
  ^\s+${OUTPUT_ERRORS}\s+output\s+error\s+\d+\s+collision\s+\d+\s+deferred\s+\d+\s+late\s+collision\s\*$$
  ^\s+Last\s+link\s+flapped\s+${LAST_LINK_FLAPPED}\s\*$$

Следующая задача использует пример шаблона для textfsm с модулем cli_parse.

- name: "Run command and parse with textfsm"
  ansible.utils.cli_parse:
    command: show interface
    parser:
      name: ansible.utils.textfsm
    set_fact: interfaces

Более глубокий анализ этой задачи:

• ansible_network_os для устройства (cisco.nxos.nxos) преобразуется в nxos. В качестве альтернативы можно указать операционную систему в опции parser/os.
• Имя шаблона textfsm по умолчанию templates/nxos_show_interface.textfsm с помощью комбинации операционной системы и исполненной команды. В качестве альтернативы можно переопределить путь к сгенерированному шаблону с помощью опции parser/template_path.
• Подробности см. в README файла textfsm.
• textfsm ранее был доступен как плагин фильтра. Пользователям Ansible следует перейти на модуль cli_parse.

Эта задача устанавливает следующий факт как interfaces факт для хоста:

- ADDRESS: X254.005a.f8b5
  ADMIN_STATE: up
  BANDWIDTH: 1000000 Kbit
  BIA: X254.005a.f8b5
  DELAY: 10 usec
  DESCRIPTION: ''
  DUPLEX: full-duplex
  ENCAPSULATION: ARPA
  HARDWARE_TYPE: Ethernet
  INPUT_ERRORS: ''
  INPUT_PACKETS: ''
  INTERFACE: mgmt0
  IP_ADDRESS: 192.168.101.14/24
  LAST_LINK_FLAPPED: ''
  LINK_STATUS: up
  MODE: ''
  MTU: '1500'
  OUTPUT_ERRORS: ''
  OUTPUT_PACKETS: ''
  SPEED: 1000 Mb/s
- ADDRESS: X254.005a.f8bd
  ADMIN_STATE: up
  BANDWIDTH: 1000000 Kbit
  BIA: X254.005a.f8bd

Парсинг с помощью TTP

TTP — это библиотека Python для парсинга полуструктурированного текста с использованием шаблонов. TTP использует синтаксис, похожий на jinja, чтобы уменьшить необходимость в регулярных выражениях. Пользователям, знакомым с шаблонами jinja, синтаксис шаблонов TTP может показаться знакомым.

Следующий пример шаблона TTP хранится как templates/nxos_show_interface.ttp:

{{ interface }} is {{ state }}
admin state is {{ admin_state }}{{ ignore(".\*") }}

Следующая задача использует этот шаблон для парсинга вывода команды show interface:

- name: "Run command and parse with ttp"
  ansible.utils.cli_parse:
    command: show interface
    parser:
      name: ansible.utils.ttp
    set_fact: interfaces

Более глубокий анализ этой задачи:

• Путь к шаблону по умолчанию templates/nxos_show_interface.ttp был сгенерирован с помощью ansible_network_os для хоста и command.

• TTP поддерживает несколько дополнительных переменных, которые будут переданы парсеру. К ним относятся:

  • parser/vars/ttp_init — Дополнительный параметр, передаваемый при инициализации парсера.
  • parser/vars/ttp_results — Дополнительные параметры, используемые для влияния на вывод парсера.
  • parser/vars/ttp_vars — Дополнительные переменные, доступные в шаблоне.
• Подробности см. в документации TTP.

Задача устанавливает следующий факт в качестве interfaces факта для хоста:

- admin_state: up,
  interface: mgmt0
  state: up
- admin_state: up,
  interface: Ethernet1/1
  state: up
- admin_state: up,
  interface: Ethernet1/2
  state: up

Парсинг с помощью JC

JC — это библиотека python, которая преобразует выходные данные десятков распространенных командных инструментов Linux/UNIX/macOS/Windows и типов файлов в python словари или списки словарей для более удобного парсинга. JC доступен как плагин фильтра в коллекции community.general.

Следующий пример использования JC для парсинга вывода команды dig:

- name: "Run dig command and parse with jc"
  hosts: ubuntu
  tasks:
  - shell: dig example.com
    register: result
  - set_fact:
      myvar: "{{ result.stdout | community.general.jc('dig') }}"
  - debug:
      msg: "The IP is: {{ myvar[0].answer[0].data }}"

• Проект JC и документацию можно найти здесь.
• См. эту запись блога для получения дополнительной информации.

Преобразование XML

Хотя Ansible содержит ряд плагинов, которые могут преобразовать XML в собственные структуры данных Ansible, модуль cli_parse выполняет команду на устройствах, возвращающих XML, и возвращает преобразованные данные в одной задаче.

Эта примерная задача выполняет команду show interface и анализирует вывод как XML:

- name: "Run command and parse as xml"
    ansible.utils.cli_parse:
      command: show interface | xml
      parser:
        name: ansible.utils.xml
  set_fact: interfaces

Эта задача устанавливает interfaces факт для хоста на основе этого возвращённого вывода:

nf:rpc-reply:
  '@xmlns': http://www.cisco.com/nxos:1.0:if_manager
  '@xmlns:nf': urn:ietf:params:xml:ns:netconf:base:1.0
  nf:data:
    show:
      interface:
        __XML__OPT_Cmd_show_interface_quick:
          __XML__OPT_Cmd_show_interface___readonly__:
            __readonly__:
              TABLE_interface:
                ROW_interface:
                - admin_state: up
                  encapsulation: ARPA
                  eth_autoneg: 'on'
                  eth_bia_addr: x254.005a.f8b5
                  eth_bw: '1000000'

Предоставление полного пути к шаблону

Используйте опцию template_path для переопределения пути к шаблону по умолчанию в задаче:

- name: "Run command and parse with native"
  ansible.utils.cli_parse:
    command: show interface
    parser:
      name: ansible.netcommon.native
      template_path: /home/user/templates/filename.yaml

Предоставление команде парсера, отличной от выполняемой команды

Используйте подопцию command для parser для настройки команды, ожидаемой парсером, если она отличается от команды, которую cli_parse выполняет:

- name: "Run command and parse with native"
  ansible.utils.cli_parse:
    command: sho int
    parser:
      name: ansible.netcommon.native
      command: show interface

Предоставление пользовательского значения ОС

Используйте подопцию os для парсера, чтобы напрямую установить ОС вместо использования ansible_network_os или ansible_distribution для генерации пути к шаблону или с указанным парсером:

- name: Use ios instead of iosxe for pyats
  ansible.utils.cli_parse:
    command: show something
    parser:
      name: ansible.netcommon.pyats
      os: ios

- name: Use linux instead of fedora from ansible_distribution
  ansible.utils.cli_parse:
    command: ps -ef
    parser:
      name: ansible.netcommon.native
      os: linux

Парсинг существующего текста

Используйте опцию text вместо command для парсинга текста, собранного ранее в книге.

# using /home/user/templates/filename.yaml
- name: "Parse text from previous task"
  ansible.utils.cli_parse:
    text: "{{ output['stdout'] }}"
    parser:
      name: ansible.netcommon.native
      template_path: /home/user/templates/filename.yaml

 # using /home/user/templates/filename.yaml
- name: "Parse text from file"
  ansible.utils.cli_parse:
    text: "{{ lookup('file', 'path/to/file.txt') }}"
    parser:
      name: ansible.netcommon.native
      template_path: /home/user/templates/filename.yaml

# using templates/nxos_show_version.yaml
- name: "Parse text from previous task"
  ansible.utils.cli_parse:
    text: "{{ sho_version['stdout'] }}"
    parser:
      name: ansible.netcommon.native
      os: nxos
      command: show version