Ansible Navigator

Ansible Navigator предоставляет удобный единый интерфейс для использования возможностей многих утилит Ansible в командной строке. Ansible Navigator может вызывать эти утилиты из среды исполнения (основной рекомендуемый вариант использования) или непосредственно из рабочей станции.

Установка

Для установки Ansible Navigator выполните следующие действия:

1. Подключите репозиторий Astra Automation.

   Инструкция по подключению репозитория

   1. В каталоге /etc/apt/sources.list.d/ создайте файл astra-automation.list со ссылкой на репозиторий Astra Automation:

      deb https://dl.astralinux.ru/aa/aa-debs-for-alse-1.8 <version> main
      

      Вместо <version> необходимо подставить версию устанавливаемой платформы, например, 1.2-upd1.

      Доступные версии продукта опубликованы в таблице История обновлений.

   2. Обновите список доступных пакетов:

      sudo apt update
      

2. Выполните команду:

   sudo apt-get install ansible-navigator --yes
   

Вместе с Ansible Navigator также устанавливаются:

• Ansible Builder;

• Ansible Lint;

• Ansible Runner;

• Docker.

  Совет

  Вместо Docker рекомендуется использовать Podman. Необходимо учесть, что для корректной работы Podman следует провести дополнительные настройки.

Установка при отсутствии доступа к интернету описана в документе Средства разработки.

Команды и утилиты

Основу Ansible Navigator составляет утилита ansible-navigator, вызов которой имеет следующий вид:

ansible-navigator <command> [<arguments>]

Здесь:

• <command> – команда;

• <arguments> – аргументы.

Команды, используемые для вызова других утилит Ansible:

Команда	Вызываемая утилита	Пример
builder	ansible-builder	ansible-navigator builder build --tag ee:0.0.1
config	ansible-config	ansible-navigator config init
doc	ansible-doc	ansible-navigator doc ansible.builtin.apt
inventory	ansible-inventory	ansible-navigator inventory -i ./inventory.ini
lint	ansible-lint	ansible-navigator lint ./playbooks/*.yml
run	ansible-playbook	ansible-navigator run ./playbook.yml -i ./inventory.yml

Собственные команды Ansible Navigator:

• collections – просмотр сведений об имеющихся коллекциях Ansible.

• exec – запуск команды Ansible в среде исполнения.

• images – управление образами среды исполнения.

• replay – просмотр артефактов, собранных во время выполнения сценариев.

• settings – просмотр действующих значений настроек Ansible Navigator.

• welcome – интерактивный режим работы.

Подробное описание команд и возможных аргументов см. в справочных данных.

Режимы работы

Ansible Navigator может работать в интерактивном (по умолчанию) и неинтерактивном режимах.

Для запуска Ansible Navigator в неинтерактивном режиме добавьте аргумент --mode со значением stdout, например:

ansible-navigator images list --mode stdout

Интерактивный режим работы

При запуске в интерактивном режиме Ansible Navigator предоставляет псевдографический интерфейс следующего вида:

 0│Welcome
 1│———————————————————————————————————————————————————————————————————————————————————————————————————
 2│
 3│Some things you can try from here:
 4│- :collections                                    Explore available collections
 5│- :config                                         Explore the current ansible configuration
 6│- :doc <plugin>                                   Review documentation for a module or plugin
 7│- :help                                           Show the main help page
 8│- :images                                         Explore execution environment images
 9│- :inventory -i <inventory>                       Explore an inventory
10│- :log                                            Review the application log
11│- :lint <file or directory>                       Lint Ansible/YAML files (experimental)
12│- :open                                           Open current page in the editor
13│- :replay                                         Explore a previous run using a playbook artifact
14│- :run <playbook> -i <inventory>                  Run a playbook in interactive mode
15│- :settings                                       Review the current ansible-navigator settings
16│- :quit                                           Quit the application
17│
18│happy automating,
19│
20│-winston
^b/PgUp page up        ^f/PgDn page down        ↑↓ scroll        esc back        :help help

Этот интерфейс состоит из следующих элементов, сверху вниз:

1. Заголовки столбцов. Первый столбец не имеет названия и используется для вывода номера пункта списка.

2. Список записей.

3. Строка с подсказками.

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

• Для прокрутки списка используются клавиши ↑, ↓, PgUp и PgDn.

• Для завершения работы с Ansible Navigator или перехода на уровень выше используется клавиша Esc.

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

  1. Ввести символ : и сразу же после него название команды или номер строки, например, :help или :19.

  2. Нажать Enter.

  Совет

  Для перехода к строкам с номерами от 0 до 9 можно использовать быстрый ввод – достаточно нажать соответствующую клавишу цифрового ряда клавиатуры.

• При работе с некоторыми разделами можно использовать клавиши - и + для перехода к предыдущему и следующему пунктам списка соответственно.

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

Неинтерактивный режим работы

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

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

Настройки

Значения настроек Ansible Navigator могут быть заданы следующими способами:

• аргументы командной строки;

• переменные окружения;

• конфигурационный файл.

При запуске Ansible Navigator выполняет поиск своего конфигурационного файла в следующем порядке:

1. Путь, указанный в переменной окружения ANSIBLE_NAVIGATOR_CONFIG.

2. Файл ansible-navigator.<ext> в каталоге проекта.

3. Файл .ansible-navigator.<ext> в домашнем каталоге.

Здесь <ext> – расширение имени файла, .yml, .yaml или .json.

Поиск прекращается при первом совпадении. Например, если в каталоге проекта существует файл ansible-navigator.yml, настройки из файла ~/.ansible-navigator.yml, расположенного в домашнем каталоге, загружены не будут.

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

• Доступны форматы YAML и JSON.

• При использовании формата JSON название файла должно иметь расширение .json.

• При использовании формата YAML название файла должно иметь расширение .yml или .yaml.

• В каталоге проекта и домашнем каталоге должен быть только один конфигурационный файл Ansible Navigator. В противном случае Ansible Navigator выводит сообщение об ошибке.

Пример файла с настройками

ansible-navigator.yml

---
ansible-navigator:
  # Основные настройки Ansible
  ansible:
    cmdline: -vv # Более подробный вывод чем обычно
    config:
      path: ./ansible.cfg # Путь к конфигурационному файлу Ansible
    inventory:
      entries: # Пути к файлам с инвентарными списками
        - ./inventory.yml

  # Настройки Ansible Builder
  ansible-builder:
    workdir: ./execution-environment/ # Рабочий каталог

  # Настройки Ansible Runner
  ansible-runner:
    artifact-dir: ./artifacts/ # Каталог для сохранения артефактов
    timeout: 600 # Ограничение по времени - 10 минут
    job-events: true # Сохранение событий в журнал

  # Настройки цветового оформления
  color:
    enable: true # Включено
    osc4: true # Использовать формат OSC4

  # Настройки текстового редактора
  editor:
    console: true # Запустить в TUI
    command: emacs +{line_number} {filename} # GNU Emacs

  # Настройки среды исполнения
  execution-environment:
    container-engine: podman # Инструмент контейнеризации - Podman
    enabled: true # Использование сред исполнения разрешено
    environment-variables:
      pass: # Список переменных, импортируемых из текущего окружения в контейнер
        - ANSIBLE_GALAXY_SERVER_VALIDATED_TOKEN
      set: # Значения переменных, которые должны быть переданы в контейнер
        USER: aa-service-account
        HOST: hub.example.com
    image: private-hub.example.com/aa-full-ee:latest # Образ EE
    pull:
      policy: missing # Загрузить образ только при его отсутствии
    volume-mounts: # Монтирование каталогов в файловую систему контейнера
      - src: ./playbooks/
        dest: /playbooks

  # Настройки журналирования
  logging:
    file: ./logs/ansible-navigator.log # Путь к файлу журнала
    level: error # Игнорировать сообщения с уровнем ниже Error

  # Порядок обработки настроек самого Ansible Navigator
  settings:
    effective: true # Показ фактических значений
    sources: true # Отображать источники значений

  # Часовой пояс
  time-zone: Europe/Moscow

Подробное описание настроек см. в справочных данных.

Примеры

Изучите использование Ansible Navigator в неинтерактивном и интерактивном режимах на примерах.

Использование Ansible Navigator в неинтерактивном режиме

Для работы с Ansible Navigator в неинтерактивном режиме используйте аргумент --mode со значением stdout.

• Получение справочной информации об использовании команды ansible-config в неинтерактивном режиме:

  ansible-navigator config --hc
  

• Получение сведений о коллекциях, доступных в окружении используемой ОС:

  ansible-navigator collections --mode stdout
  

• Получение сведений о коллекциях, доступных в образе aa-full-ee:latest:

  ansible-navigator collections \
     --eei hub.astra-automation.ru/aa-1.2/aa-full-ee:latest \
     --mode stdout
  

• Получение сведений о загруженных образах среды исполнения:

  ansible-navigator images --mode stdout
  

• Загрузка самой новой версии образа aa-cdk из реестра:

  ansible-navigator images \
     --mode stdout \
     --eei hub.astra-automation.ru/aa-1.2/aa-cdk:latest
  

• Загрузка образа aa-cdk:0.1.2:

  ansible-navigator images \
     --mode stdout \
     --eei hub.astra-automation.ru/aa-1.2/aa-cdk:0.1.2
  

Использование Ansible Navigator в интерактивном режиме

Для использования Ansible Navigator в интерактивном режиме используйте аргумент --mode со значением interactive.

Получение сведений об образах среды исполнения

Для получения сведения о составе образов среды исполнения выполните следующие действия:

1. Выполните команду ansible-navigator с аргументами images и --mode:

   ansible-navigator images --mode interactive
   

   В терминал выводится список образов, например:

     Image          Tag     Execution environment   Created      Size
   0│aa-full-ee     latest  True                    2 weeks ago  1.09 GB
   1│aa-full-ee     0.1.1   True                    4 weeks ago  998 MB
   2│aa-minimal-ee  latest  True                    5 weeks ago  284 MB
   3│aa-minimal-ee  1.0.3   True                    5 weeks ago  281 MB
   4│aa-minimal-ee  1.0.2   True                    5 weeks ago  273 MB
   

2. Для просмотра сведений об образе aa-full-ee:0.1.1 выполните следующие действия:

   1. Последовательно нажмите клавиши :, 1 и Enter.

      В терминал выводится меню следующего вида:

        Image: aa-full-ee:0.1.1          Description
      0│Image information                Information collected from image inspection
      1│General information              OS and python version information
      2│Ansible version and collections  Information about ansible and ansible collections
      3│Python packages                  Information about python and python packages
      4│Operating system packages        Information about operating system packages
      5│Everything                       All image information
      

   2. Нажмите соответствующую клавишу для перехода в нужный раздел. Например, для выбора раздела Python packages нажмите 3.

      Дождитесь загрузки сведений о пакетах Python. По окончании загрузки в терминал выводятся строки следующего вида:

         Name                         Version   Summary
       0│ansible-compat               24.9.1    Ansible compatibility goodies                                           ▒
       1│ansible-core                 2.15.10   Radically simple IT automation                                          ▒
       2│ansible-lint                 24.9.2    Checks playbooks for practices and behavior that could potentially be im▒
       3│ansible-runner               2.4.0     "Consistent Ansible Python API and CLI with container and process isolat▒
       4│ansible-sign                 0.1.1     Ansible content validation library and CLI                              ▒
       5│attrs                        22.2.0    Classes Without Boilerplate                                             ▒
       6│backports.ssl_match_hostname 3.7.0.1   The ssl.match_hostname() function from Python 3.5                       ▒
       7│bcrypt                       3.2.2     Modern password hashing for your software and your servers
       8│black                        24.10.0   The uncompromising code formatter.
       9│bracex                       2.5.post1 Bash style brace expander.
      10│certifi                      2022.9.24 Python package for providing Mozilla's CA Bundle.
      11│cffi                         1.15.1    Foreign Function Interface for Python calling C code.
      12│chardet                      5.1.0     Universal encoding detector for Python 3
      13│charset-normalizer           3.0.1     The Real First Universal Charset Detector. Open, modern and actively mai
      14│click                        8.1.3     Composable command line interface toolkit
      15│colorama                     0.4.6     Cross-platform colored terminal text.
      16│cryptography                 42.0.8    cryptography is a package which provides cryptographic recipes and primi
      17│distlib                      0.3.6     Distribution utilities
      18│dnspython                    2.3.0     DNS toolkit
      19│docker                       7.1.0     A Python library for the Docker Engine API.
      20│dumb-init                    1.2.5     Simple wrapper script which proxies signals to a child
      21│filelock                     3.9.0     A platform independent file lock.
      ^b/PgUp page up       ^f/PgDn page down       ↑↓ scroll       esc back       [0-9] goto       :help help
      

   3. Для просмотра сведений о пакете cffi введите строку :11 и нажмите Enter.

3. Для возврата в предыдущее меню нажмите Esc.

Получение сведений о коллекциях

Для получения сведения о коллекциях, входящих в образ среды исполнения aa-full-ee:latest, выполните следующие действия:

1. Выполните команду ansible-navigator с аргументами collections и --eei:

   ansible-navigator collections \
      --eei hub.astra-automation.ru/aa-1.2/aa-full-ee:latest
   

   В терминал выводится список коллекций, например:

      Name                Version Shadowed Type      Path
    0│ansible.builtin     2.15.10 False    contained /usr/lib/python3/dist-packages/ansible                                ▒
    1│ansible.posix       1.5.4   False    contained /usr/share/ansible/collections/ansible_collections/ansible/posix      ▒
    2│ansible.utils       3.0.0   False    contained /usr/share/ansible/collections/ansible_collections/ansible/utils      ▒
    3│astra.aa_controller 0.14.0  False    contained /usr/share/ansible/collections/ansible_collections/astra/aa_controller▒
    4│astra.ald_pro       3.0.0   False    contained /usr/share/ansible/collections/ansible_collections/astra/ald_pro      ▒
    5│astra.astralinux    0.5.0   False    contained /usr/share/ansible/collections/ansible_collections/astra/astralinux   ▒
    6│astra.brest         4.0.3   False    contained /usr/share/ansible/collections/ansible_collections/astra/brest        ▒
    7│astra.ceph          3.0.3   False    contained /usr/share/ansible/collections/ansible_collections/astra/ceph         ▒
    8│astra.chrony        0.2.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/chrony       ▒
    9│astra.cups          1.3.4   False    contained /usr/share/ansible/collections/ansible_collections/astra/cups         ▒
   10│astra.dcimanager    0.2.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/dcimanager   ▒
   11│astra.dhcp          2.0.2   False    contained /usr/share/ansible/collections/ansible_collections/astra/dhcp         ▒
   12│astra.docker        4.0.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/docker
   13│astra.etcd          0.2.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/etcd
   14│astra.freeipa       0.4.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/freeipa
   15│astra.grafana       2.0.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/grafana
   16│astra.haproxy       2.0.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/haproxy
   17│astra.hardening     0.3.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/hardening
   18│astra.iscsi         0.4.2   False    contained /usr/share/ansible/collections/ansible_collections/astra/iscsi
   19│astra.keepalived    0.3.0   False    contained /usr/share/ansible/collections/ansible_collections/astra/keepalived
   20│astra.keycloak      2.0.2   False    contained /usr/share/ansible/collections/ansible_collections/astra/keycloak
   21│astra.memcached     3.0.1   False    contained /usr/share/ansible/collections/ansible_collections/astra/memcached
   

2. Для просмотра сведений о коллекции astra.grafana введите строку :15 и нажмите Enter.

   В терминал выводится список модулей и ролей, входящих в коллекцию.

3. Для просмотра сведений о нужном модуле или роли введите : и номер нужной строки, после чего нажмите Enter.

4. Для возврата в предыдущее меню нажмите Esc.