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

Доступ к конструктору модуля ресурсов
Создание модели
Использование конструктора модуля ресурсов
Примеры
Структура и рабочий процесс модуля ресурсов
Примечания разработчикам

Конструктор модулей ресурсов — это Ansible Playbook, который помогает разработчикам создавать и поддерживать модуль ресурсов сети Ansible.

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

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

Доступ к конструктору модуля ресурсов

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

клонировать репозиторий github:

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

установить необходимые компоненты:

pip install -r requirements.txt

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

Вы должны создать модель для нового ресурса. Конструктор модуля ресурсов использует эту модель для создания:

Шаблона нового модуля
Argspec для нового модуля
Строки документации для нового модуля

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

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

---
GENERATOR_VERSION: '1.0'
ANSIBLE_METADATA: |
    {
        'metadata_version': '1.1',
        'status': ['preview'],
        'supported_by': '<support_group>'
    }
NETWORK_OS: myos
RESOURCE: interfaces
COPYRIGHT: Copyright 2019 Red Hat
LICENSE: gpl-3.0.txt

DOCUMENTATION: |
  module: myos_interfaces
  version_added: 2.9
  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'
        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

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

См. модели ресурсов сети Ansible для получения дополнительных примеров.

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

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

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

Структура и рабочий процесс модуля ресурсов

Структура модуля ресурсов включает следующие компоненты:

Модуль

library/<ansible_network_os>_<resource>.py.
Импортирует пакет ресурсов module_utils и вызывает API execute_module

def main():
    result = <resource_package>(module).execute_module()

Argspec модуля

module_utils/<ansible_network_os>/argspec/<resource>/.
Argspec для ресурса.

Факты

module_utils/<ansible_network_os>/facts/<resource>/.
Заполнение фактов для ресурса.
Запись в module_utils/<ansible_network_os>/facts/facts.py для API get_facts для поддержания синхронизации модуля <ansible_network_os>_facts и собранных фактов для модуля ресурсов для каждого подмножества.
Запись подмножества ресурса в список FACTS_RESOURCE_SUBSETS в module_utils/<ansible_network_os>/facts/facts.py для работы сбора фактов.

Пакет модуля в module_utils

module_utils/<ansible_network_os>/<config>/<resource>/.
Реализует API execute_module , загружающий конфигурацию на устройство и генерирующий результат с ключами changed, commands, before и after.
Вызывает API get_facts , возвращающий фактические данные конфигурации <resource> или возвращает разницу, если устройство поддерживает diff onbox.
Сравнивает собранные факты и заданные ключевые значения, если diff не поддерживается.
Генерирует окончательную конфигурацию.

Утилиты

module_utils/<ansible_network_os>/utils.
Утилиты для платформы <ansible_network_os>.

Примечания разработчикам

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

rm -rf rmb_tests/roles/my_role
ansible-playbook -e rm_dest=./rmb_tests/roles/my_role \
                 -e structure=role \
                 -e model=models/myos/interfaces/myos_interfaces.yml \
                 site.yml

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/network/dev_guide/developing_resource_modules_network.html