Разбор полуструктурированного текста с помощью Ansible

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

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

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

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

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

Не следует разбирать полуструктурированный текст, если:

• Устройство, узел или платформа предоставляет REST API и возвращает JSON.
• Существующие модули сбора фактов Ansible уже возвращают нужные данные.
• Для управления конфигурацией устройства и ресурса доступны сетевые модули ресурсов 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 properties.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 Solution. Он включает множество предварительно заданных парсеров для различных сетевых платформ и команд. Предварительно заданные парсеры из пакета 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 задаёт для pyATS значение cisco.ios.ios, равное iosxe. Это значение можно переопределить с помощью параметра 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
  register: 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