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.7 <version> main
      

      Вместо <version> необходимо подставить версию устанавливаемой платформы, например, 1.1-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 – просмотр артефактов, собранных во время выполнения playbook.

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

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

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

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

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

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

ansible-navigator images list --mode stdout

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

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

   Name                                  Default Source                   Current
 0│Ansible runner artifact dir           True    Not set                  Not set
 1│Ansible runner rotate artifacts count True    Not set                  Not set
 2│Ansible runner timeout                True    Not set                  Not set
 3│Ansible runner write job events       True    Defaults                 False
 4│App                                   False   Command line             settings
 5│Cmdline                               True    Not set                  Not set
 6│Collection doc cache path             True    Defaults                 /home/vagrant/.cache/ansible-navigator/c
 7│Config                                True    Not set                  Not set
 8│Container engine                      False   Automatically determined docker
 9│Container options                     True    Not set                  Not set
10│Current settings file                 True    None                     None
11│Display color                         True    Defaults                 True
12│Editor command                        True    Defaults                 vi +{line_number} {filename}
13│Editor console                        True    Defaults                 True
14│Enable prompts                        True    Defaults                 False
15│Exec command                          True    Defaults                 /bin/bash
16│Exec shell                            True    Defaults                 True
17│Execution environment                 True    Defaults                 True
18│Execution environment image           True    Defaults                 registry.astralinux.ru/aa/aa-creator-ee:
19│Execution environment volume mounts   True    Not set                  Not set
^b/PgUp page up       ^f/PgDn page down       ↑↓ scroll       esc back       [0-9] goto       :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:
  #     config:
  #       help: False
  #       path: /tmp/ansible.cfg
  #     cmdline: "--forks 15"
  #     doc:
  #       help: False
  #       plugin:
  #         name: shell
  #         type: become
  #     inventory:
  #       help: False
  #       entries:
  #         - /tmp/test_inventory.yml
  #     playbook:
  #       help: False
  #       path: /tmp/test_playbook.yml
  #
  #   ansible-builder:
  #     help: False
  #     workdir: /tmp/
  #
  #   ansible-lint:
  #     config: ~/ansible-lint.yml
  #     lintables: ~/myproject/
  #
  #   ansible-runner:
  #     artifact-dir: /tmp/test1
  #     rotate-artifacts-count: 10
  #     timeout: 300
  #     job-events: False
  #
  #   app: run
  #
  #   collection-doc-cache-path: /tmp/cache.db
  #
  #   color:
  #     enable: False
  #     osc4: False
  #
  #   editor:
  #     command: vim_from_setting
  #     console: False
  #
  #   enable-prompts: False
  #
  #   exec:
  #     shell: False
  #     command: /bin/foo
  #
  #   execution-environment:
  #     container-engine: podman
  #     enabled: False
  #     environment-variables:
  #       pass:
  #         - ONE
  #         - TWO
  #         - THREE
  #       set:
  #         KEY1: VALUE1
  #         KEY2: VALUE2
  #         KEY3: VALUE3
  #     image: test_image:latest
  #     pull:
  #       arguments:
  #         - "--tls-verify=false"
  #       policy: never
  #     volume-mounts:
  #       - src: "/tmp"
  #         dest: "/test1"
  #         options: "Z"
  #     container-options:
  #       - "--net=host"
  #
  #   format: json
  #
  #   images:
  #     details:
  #       - ansible_version
  #       - python_version
  #
  #   inventory-columns:
  #     - ansible_network_os
  #     - ansible_network_cli_ssh_type
  #     - ansible_connection
  #
  logging:
    level: critical
#     append: False
#     file: /tmp/log.txt
#
#   mode: stdout
#
#   playbook-artifact:
#     enable: True
#     replay: /tmp/test_artifact.json
#     save-as: /tmp/test_artifact.json
#
#   settings:
#     effective: False
#     sample: False
#     schema: json
#     sources: False
#
#   time-zone: Japan

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

Примеры

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

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

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

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

  ansible-navigator config --hc
  

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

  ansible-navigator collections --mode stdout
  

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

  ansible-navigator collections \
     --eei registry.astralinux.ru/aa/aa-creator-ee:latest \
     --mode stdout
  

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

  ansible-navigator images --mode stdout
  

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

  ansible-navigator images \
     --mode stdout \
     --eei registry.astralinux.ru/aa/aa-creator-ee:latest
  

• Загрузка образа aa-creator-ee:0.2.0:

  ansible-navigator images \
     --mode stdout \
     --eei registry.astralinux.ru/aa/aa-creator-ee:0.2.0
  

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

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

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

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

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

   ansible-navigator images --mode interactive
   

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

     Image                   Tag         Execution environment                  Created                Size
   0│aa-base-ee              latest      True                                   6 days ago             1.1GB
   1│aa-base-ee              0.6.0       True                                   10 days ago            1.1GB
   2│aa-base-ee              0.5.1       False                                  3 months ago           945MB
   3│aa-creator-ee           latest      True                                   6 days ago             1.76GB
   4│aa-creator-ee           0.2.0       True                                   10 days ago            1.76GB
   

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

   1. Нажмите 3.

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

        Image: aa-creator-ee:latest                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│aenum              3.1.15   Advanced Enumerations (compatible with Python's stdlib Enum), NamedTuples, and N
        1│aiohttp            3.8.3    Async http client/server framework (asyncio)
        2│aiosignal          1.3.1    aiosignal: a list of registered asynchronous callbacks
        3│ansible-compat     4.1.11   Ansible compatibility goodies
        4│ansible-core       2.15.10  Radically simple IT automation
        5│ansible-lint       6.22.2   Checks playbooks for practices and behavior that could potentially be improved
        6│ansible-pylibssh   1.0.0    Python bindings for libssh client specific to Ansible use case
        7│ansible-runner     2.3.6    "Consistent Ansible Python API and CLI with container and process isolation runt
        8│appdirs            1.3.0    A small Python module for determining appropriate " +         "platform-specific
        9│argcomplete        3.4.0    Bash tab completion for argparse
       10│async-timeout      4.0.2    Timeout context manager for asyncio programs
       11│attrs              23.2.0   Classes Without Boilerplate
       12│bcrypt             4.1.2    Modern password hashing for your software and your servers
       13│black              24.4.2   The uncompromising code formatter.
       14│bracex             2.4      Bash style brace expander.
       15│cachetools         5.3.2    Extensible memoizing collections and decorators
       16│certifi            2024.2.2 Python package for providing Mozilla's CA Bundle.
       17│cffi               1.16.0   Foreign Function Interface for Python calling C code.
       18│charset-normalizer 2.1.1    The Real First Universal Charset Detector. Open, modern and actively maintained
       19│click              8.1.7    Composable command line interface toolkit
       20│click-help-colors  0.9.4    Colorization of help messages in Click
       21│coverage           7.5.3    Code coverage measurement for Python
       22│cryptography       42.0.7   cryptography is a package which provides cryptographic recipes and primitives to
       23│Cython             3.0.10   The Cython compiler for writing C extensions in the Python language.
       24│decorator          5.1.1    Decorators for Humans
       25│dicttoxml          1.7.16   Converts a Python dictionary or other native data type into a valid XML string.
       26│distlib            0.3.8    Distribution utilities
       27│distro             1.9.0    Distro - an OS platform information API
       28│docutils           0.19     Docutils -- Python Documentation Utilities
       29│dogpile.cache      1.3.2    A caching front-end based on the Dogpile lock.
       30│dumb-init          1.2.5    Simple wrapper script which proxies signals to a child
       31│enrich             1.2.7    enrich
      ^b/PgUp page up       ^f/PgDn page down       ↑↓ scroll       esc back       [0-9] goto       :help help
      

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

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

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

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

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

   ansible-navigator collections \
      --eei registry.astralinux.ru/aa/aa-creator-ee:latest
   

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

     Name            Version Shadowed Type      Path
   0│ansible.builtin 2.15.10 False    contained /usr/local/lib/python3.9/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
   

2. Для просмотра сведений о коллекции ansible.posix нажмите 1.

   В терминал выводится список модулей и функций обратного вызова (callback), входящих в коллекцию, например:

      Ansible.posix      Type     Added Deprecated Description
    0│acl                module   1.0.0 False      Set and retrieve file ACL information.
    1│at                 module   1.0.0 False      Schedule the execution of a command or script file via the at co
    2│authorized_key     module   1.0.0 False      Adds or removes an SSH authorized key
    3│cgroup_perf_recap  callback None  False      Profiles system activity of tasks and full execution using cgrou
    4│csh                shell    None  False      C shell (/bin/csh)
    5│debug              callback None  False      formatted stdout/stderr display
    6│firewalld          module   None  False      Manage arbitrary ports/services with firewalld
    7│firewalld_info     module   None  False      Gather information about firewalld
    8│fish               shell    None  False      fish shell (/bin/fish)
    9│json               callback None  False      Ansible screen output as JSON
   10│jsonl              callback None  False      Ansible screen output as JSONL (lines in json format)
   11│mount              module   1.0.0 False      Control active and configured mount points
   12│patch              module   1.0.0 False      Apply patch files using the GNU patch tool
   13│profile_roles      callback None  False      adds timing information to roles
   14│profile_tasks      callback None  False      adds time information to tasks
   15│rhel_facts         module   1.5.0 False      Facts module to set or override RHEL specific facts.
   16│rhel_rpm_ostree    module   1.5.0 False      Ensure packages exist in a RHEL for Edge rpm-ostree based system
   17│rpm_ostree_upgrade module   1.5.0 False      Manage rpm-ostree upgrade transactions
   18│seboolean          module   1.0.0 False      Toggles SELinux booleans
   19│selinux            module   1.0.0 False      Change policy and state of SELinux
   20│skippy             callback None  True       Ansible screen output that ignores skipped status
   21│synchronize        module   1.0.0 False      A wrapper around rsync to make common tasks in your playbooks qu
   22│sysctl             module   1.0.0 False      Manage entries in sysctl.conf.
   23│timer              callback None  False      Adds time to play stats
   

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

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