Разработка модулей сетевых ресурсов

Понимание модели и построителя модулей ресурсов

Построитель модулей ресурсов — это Ansible Playbook, который помогает разработчикам создавать и поддерживать модуль Ansible ресурса. Он использует модель как единственный источник правды для модуля. Эта модель представляет собой yaml файл, который используется для раздела ДОКУМЕНТАЦИЯ модуля и спецификации аргументов.

Построитель модулей ресурсов обладает следующими возможностями:

• Использует определенную модель для создания структуры каталогов модуля ресурса и начальных файлов классов.
• Создает либо роль Ansible, либо коллекцию.
• Последующее использование построителя модулей ресурсов заменит только спецификацию модуля arspec и файл, содержащий строку документации модуля.
• Позволяет хранить сложные примеры вместе с моделью в одном каталоге.
• Поддерживает модель как единственный источник правды для модуля и использует построитель модулей ресурсов для обновления исходных файлов по мере необходимости.
• Создаёт рабочие примеры модулей для <network_os>_<resource> и <network_os>_facts.

Доступ к построителю модулей ресурсов

Для доступа к построителю модулей ресурсов:

1. клонируйте репозиторий GitHub:

git clone https://github.com/ansible-network/resource_module_builder.git

2. Установите необходимые зависимости:

pip install -r requirements.txt

Создание модели

Вы должны создать модель для вашего нового ресурса. Модель является единственным источником истины как для argspec, так и для строки документации, обеспечивая их синхронизацию. После утверждения вашей модели вы можете использовать построитель модулей ресурсов для генерации трёх элементов на основе модели:

• Каркас для нового модуля
• Argspec для нового модуля
• Строка документации для нового модуля

Для любых последующих изменений функциональности сначала обновите модель, а затем используйте построитель модулей ресурсов для обновления argspec и строки документации модуля.

Например, построитель моделей ресурсов включает пример myos_interfaces.yml в каталоге models, как показано ниже:

---
GENERATOR_VERSION: '1.0'

NETWORK_OS: myos
RESOURCE: interfaces
COPYRIGHT: Copyright 2019 Red Hat
LICENSE: gpl-3.0.txt

DOCUMENTATION: |
  module: myos_interfaces
  version_added: 1.0.0
  short_description: 'Manages <xxxx> attributes of <network_os> <resource>'
  description: 'Manages <xxxx> attributes of <network_os> <resource>.'
  author: Ansible Network Engineer
 notes:
    - 'Tested against <network_os> <version>'
  options:
    config:
      description: The provided configuration
      type: list
      elements: dict
      suboptions:
        name:
          type: str
          description: The name of the <resource>
        some_string:
          type: str
          description:
          - The some_string_01
          choices:
          - choice_a
          - choice_b
          - choice_c
          default: choice_a
        some_bool:
          description:
          - The some_bool.
          type: bool
        some_int:
          description:
          - The some_int.
          type: int
          version_added: '1.1.0'
        some_dict:
          type: dict
          description:
          - The some_dict.
          suboptions:
            property_01:
              description:
              - The property_01
              type: str
    state:
      description:
      - The state of the configuration after module completion.
      type: str
      choices:
      - merged
      - replaced
      - overridden
      - deleted
      default: merged
EXAMPLES:
  - deleted_example_01.txt
  - merged_example_01.txt
  - overridden_example_01.txt
  - replaced_example_01.txt

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

Поделитесь этой моделью в виде PR для проверки в репозитории моделей модулей ресурсов. Вы также можете найти больше примеров моделей в этом месте.

Создание каркаса коллекции из модели ресурса

Для использования построителя модулей ресурсов для создания каркаса коллекции из вашей утверждённой модели ресурса:

ansible-playbook -e rm_dest=<destination for modules and module utils> \
                 -e structure=collection \
                 -e collection_org=<collection_org> \
                 -e collection_name=<collection_name> \
                 -e model=<model> \
                 site.yml

Где параметры следующие:

• rm_dest: Каталог, в котором построитель модулей ресурсов размещает файлы и каталоги для модуля ресурса и модулей фактов.

• structure: Тип структуры каталогов (роль или коллекция)

  • role: Создать структуру каталогов роли.
  • collection: Создать структуру каталогов коллекции.
• collection_org: Организация коллекции, необходимая при structure=collection.
• collection_name: Название коллекции, необходимое при structure=collection.
• model: Путь к файлу модели.

Для использования построителя модулей ресурсов для создания каркаса роли:

ansible-playbook -e rm_dest=<destination for modules and module utils> \
                 -e structure=role \
                 -e model=<model> \
                 site.yml

Структура каталогов коллекции

Этот пример демонстрирует структуру каталогов для следующих:

• network_os: myos
• resource: interfaces

ansible-playbook -e rm_dest=~/github/rm_example \
                 -e structure=collection \
                 -e collection_org=cidrblock \
                 -e collection_name=my_collection \
                 -e model=models/myos/interfaces/myos_interfaces.yml \
                 site.yml

├── docs
├── LICENSE.txt
├── playbooks
├── plugins
|   ├── action
|   ├── filter
|   ├── inventory
|   ├── modules
|   |   ├── __init__.py
|   |   ├── myos_facts.py
|   |   └──  myos_interfaces.py
|   └──  module_utils
|       ├── __init__.py
|       └──  network
|           ├── __init__.py
|           └──  myos
|               ├── argspec
|               |   ├── facts
|               |   |   ├── facts.py
|               |   |   └──  __init__.py
|               |   ├── __init__.py
|               |   └──  interfaces
|               |       ├── __init__.py
|               |       └──  interfaces.py
|               ├── config
|               |   ├── __init__.py
|               |   └──  interfaces
|               |       ├── __init__.py
|               |       └──  interfaces.py
|               ├── facts
|               |   ├── facts.py
|               |   ├── __init__.py
|               |   └──  interfaces
|               |       ├── __init__.py
|               |       └──  interfaces.py
|               ├── __init__.py
|               └──  utils
|                   ├── __init__.py
|                   └──  utils.py
├── README.md
└──  roles

Структура каталогов роли

Этот пример отображает структуру каталогов роли для следующих:

• network_os: myos
• resource: interfaces

ansible-playbook -e rm_dest=~/github/rm_example/roles/my_role \
                 -e structure=role \
                 -e model=models/myos/interfaces/myos_interfaces.yml \
                 site.yml

roles
└── my_role
    ├── library
    │   ├── __init__.py
    │   ├── myos_facts.py
    │   └── myos_interfaces.py
    ├── LICENSE.txt
    ├── module_utils
    │   ├── __init__.py
    │   └── network
    │       ├── __init__.py
    │       └── myos
    │           ├── argspec
    │           │   ├── facts
    │           │   │   ├── facts.py
    │           │   │   └── __init__.py
    │           │   ├── __init__.py
    │           │   └── interfaces
    │           │       ├── __init__.py
    │           │       └── interfaces.py
    │           ├── config
    │           │   ├── __init__.py
    │           │   └── interfaces
    │           │       ├── __init__.py
    │           │       └── interfaces.py
    │           ├── facts
    │           │   ├── facts.py
    │           │   ├── __init__.py
    │           │   └── interfaces
    │           │       ├── __init__.py
    │           │       └── interfaces.py
    │           ├── __init__.py
    │           └── utils
    │               ├── __init__.py
    │               └── utils.py
    └── README.md

Использование коллекции

Этот пример демонстрирует использование сгенерированной коллекции в playbook:

----
- hosts: myos101
  gather_facts: False
  tasks:
  - cidrblock.my_collection.myos_interfaces:
    register: result
  - debug:
      var: result
  - cidrblock.my_collection.myos_facts:
  - debug:
      var: ansible_network_resources

Использование роли

Этот пример демонстрирует использование сгенерированной роли в playbook:

- hosts: myos101
  gather_facts: False
  roles:
  - my_role

- hosts: myos101
  gather_facts: False
  tasks:
  - myos_interfaces:
    register: result
  - debug:
      var: result
  - myos_facts:
  - debug:
      var: ansible_network_resources

Интеграционные тесты модулей ресурсов

Требования к интеграционным тестам высокого уровня для новых модулей ресурсов таковы:

1. Напишите тестовый случай для каждого состояния.
2. Напишите дополнительные тестовые случаи для проверки поведения модуля, когда пустой config.yaml предоставлен.
3. Добавьте тестовый случай обратного хода. Это включает операцию merge, за которой следует gather_facts, обновление merge с дополнительной конфигурацией, а затем возвращение к базовой конфигурации с использованием ранее собранных фактов с state установленным в значение overridden.
4. В тех случаях, когда это применимо, утверждения должны проверяться после и перед dicts по отношению к жестко закодированному Источнику Истины.

Мы используем Zuul в качестве CI для запуска интеграционного теста.

• Чтобы просмотреть отчет, щелкните Подробности в комментарии CI в PR
• Чтобы просмотреть отчет о сбое, щелкните ansible/check и выберите не пройденный тест.
• Чтобы просмотреть журналы во время выполнения теста, найдите свой номер PR на панели статуса Zuul.
• Чтобы исправить локальный сбой статического теста, выполните tox -e black в корневой папке коллекции.

Чтобы просмотреть журналы выполнения Ansible и отлаживать сбои тестов:

1. Щелкните не пройденную задачу, чтобы получить сводку, и щелкните Журналы для получения журнала.
2. Щелкните консоль и прокрутите вниз, чтобы найти не пройденный тест.
3. Щелкните > рядом с не пройденным тестом для получения полных подробностей.

---
- import_tasks: cli.yaml
  tags:
    - cli

---
- name: collect all cli test cases
  find:
    paths: "{{ role_path }}/tests/cli"
    patterns: "{{ testcase }}.yaml"
  register: test_cases
  delegate_to: localhost

- name: set test_items
  set_fact: test_items="{{ test_cases.files | map(attribute='path') | list }}"

- name: run test cases (connection=network_cli)
  include_tasks:
     file: "{{ test_case_to_run }}"
  vars:
     ansible_connection: network_cli
  with_items: "{{ test_items }}"
  loop_control:
    loop_var: test_case_to_run

- name: run test case (connection=local)
  include_tasks:
     file: "{{ test_case_to_run }}"
  vars:
     ansible_connection: local
     ansible_become: false
  with_first_found: "{{ test_items }}"
  loop_control:
    loop_var: test_case_to_run

---
- debug:
 msg: START vyos_l3_interfaces merged integration tests on connection={{ ansible_connection
   }}

- import_tasks: _remove_config.yaml

- block:

 - import_tasks: _populate.yaml

 - name: Overrides all device configuration with provided configuration
   register: result
   vyos.vyos.vyos_l3_interfaces: &id001
     config:

       - name: eth0
         ipv4:

           - address: dhcp

       - name: eth1
         ipv4:

           - address: 192.0.2.15/24
     state: overridden

 - name: Assert that before dicts were correctly generated
   assert:
     that:
       - "{{ populate | symmetric_difference(result['before']) |length == 0 }}"

 - name: Assert that correct commands were generated
   assert:
     that:
       - "{{ overridden['commands'] | symmetric_difference(result['commands'])\
         \ |length == 0 }}"

 - name: Assert that after dicts were correctly generated
   assert:
     that:
       - "{{ overridden['after'] | symmetric_difference(result['after']) |length\
         \ == 0 }}"

 - name: Overrides all device configuration with provided configurations (IDEMPOTENT)
   register: result
   vyos.vyos.vyos_l3_interfaces: *id001

 - name: Assert that the previous task was idempotent
   assert:
     that:
       - result['changed'] == false

 - name: Assert that before dicts were correctly generated
   assert:
     that:
       - "{{ overridden['after'] | symmetric_difference(result['before']) |length\
         \ == 0 }}"
always:

 - import_tasks: _remove_config.yaml

- name: Collect interface list
  connection: ansible.netcommon.network_cli
  register: intout
  cisco.nxos.nxos_command:
    commands:
      - show interface brief | json

- set_fact:
    intdataraw: "{{ intout.stdout_lines[0]['TABLE_interface']['ROW_interface'] }}"

- set_fact:
    nxos_int1: '{{ intdataraw[1].interface }}'

- set_fact:
    nxos_int2: '{{ intdataraw[2].interface }}'

- set_fact:
    nxos_int3: '{{ intdataraw[3].interface }}'

cd test/integration
cp inventory.network.template inventory.networking
${EDITOR:-vi} inventory.networking
# Add in machines for the platform(s) you wish to test

ansible-test network-integration  --inventory ~/myinventory -vvv vyos_facts
ansible-test network-integration  --inventory ~/myinventory -vvv vyos_.*

ansible-test network-integration --inventory  /path/to-collection-module/test/integration/inventory.networking vyos_.*

ansible-test network-integration --inventory  /path/to-collection-module/test/integration/inventory.networking vyos_l3_interfaces

# Only run vyos_l3_interfaces/tests/cli/gathered.yaml
ansible-test network-integration --inventory  /path/to-collection-module/test/integration/inventory.networking vyos_l3_interfaces --testcase gathered

 # Only run nxapi test
ansible-test network-integration --inventory  /path/to-collection-module/test/integration/inventory.networking  --tags="nxapi" nxos_.*

# Skip any cli tests
 ansible-test network-integration --inventory  /path/to-collection-module/test/integration/inventory.networking  --skip-tags="cli" nxos_.*

ansible-test network-integration --help

Требования к модульным тестам

Требования к модульным тестам высокого уровня, которым должны следовать новые модули ресурсов:

1. Напишите тестовые случаи для всех состояний со всеми возможными комбинациями значений конфигурации.
2. Напишите тестовые случаи для проверки условий ошибок (отрицательные сценарии).
3. Проверьте значение ключей changed и commands в каждом тестовом случае.

Мы запускаем все модульные тестовые случаи на нашем наборе тестов Zuul на последней версии Python, поддерживаемой нашей системой CI.

Используйте ту же процедуру, что и для интеграционных тестов, для просмотра отчетов и журналов модульных тестов Zuul.

См. тестирование модулей модулей для общих подробностей о модульных тестах.

Использование эмуляторов для модульного тестирования сетевых модулей ресурсов Ansible

Мок-объекты могут быть очень полезными при создании модульных тестов для особых или сложных случаев, но они также могут привести к сложным и запутанным ситуациям программирования. Одно хорошее применение эмуляторов — моделирование API. Пакет mock поставляется с Ansible (используйте import units.compat.mock).

Вы можете смоделировать подключение к устройству и вывод от устройства следующим образом:

self.mock_get_config = patch( "ansible_collections.ansible.netcommon.plugins.module_utils.network.common.network.Config.get_config"
)
self.get_config = self.mock_get_config.start()

self.mock_load_config = patch(
"ansible_collections.ansible.netcommon.plugins.module_utils.network.common.network.Config.load_config"
)
self.load_config = self.mock_load_config.start()

self.mock_get_resource_connection_config = patch(
"ansible_collections.ansible.netcommon.plugins.module_utils.network.common.cfg.base.get_resource_connection"
)
self.get_resource_connection_config = (self.mock_get_resource_connection_config.start())

self.mock_get_resource_connection_facts = patch(
"ansible_collections.ansible.netcommon.plugins.module_utils.network.common.facts.facts.get_resource_connection"
)
self.get_resource_connection_facts = (self.mock_get_resource_connection_facts.start())

self.mock_edit_config = patch(
"ansible_collections.arista.eos.plugins.module_utils.network.eos.providers.providers.CliProvider.edit_config"
)
self.edit_config = self.mock_edit_config.start()

self.mock_execute_show_command = patch(
"ansible_collections.arista.eos.plugins.module_utils.network.eos.facts.l2_interfaces.l2_interfaces.L2_interfacesFacts.get_device_data"
)
self.execute_show_command = self.mock_execute_show_command.start()

Файл фактов модуля теперь включает новый метод get_device_data. Вызовите get_device_data здесь, чтобы эмулировать вывод устройства.

Эмуляция данных устройства

Чтобы смоделировать получение результатов от устройств или предоставить другие сложные структуры данных, поступающие из внешних библиотек, вы можете использовать fixtures для чтения предварительно сгенерированных данных. Текстовые файлы для этих предварительно сгенерированных данных находятся в test/units/modules/network/PLATFORM/fixtures/. См., например, файл eos_l2_interfaces.cfg.

Загрузите данные с помощью метода load_fixture и установите эти данные в качестве возвращаемого значения метода get_device_data в файле фактов:

def load_fixtures(self, commands=None, transport='cli'):
    def load_from_file(*args, **kwargs):
        return load_fixture('eos_l2_interfaces_config.cfg')
    self.execute_show_command.side_effect = load_from_file

См. файл модульного теста test_eos_l2_interfaces для практического примера.