Собственные типы полномочий

Собственные типы полномочий#

Astra Automation Controller позволяет создавать собственные типы полномочий.

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

  • Входные данные – данные, которые вводит пользователь при создании полномочия. В качестве входных данных могут использоваться имена пользователей, пароли, приватные ключи SSH и GPG, токены и тому подобное.

  • Инжектор – механизм, выполняющий преобразование данных полномочия в нужный формат.

  • Инжекция – процесс передачи данных полномочия в среду исполнения при выполнении задания.

Создание собственного типа полномочий имеет следующие особенности:

  • Каждый собственный тип полномочий должен содержать описание полей входных данных и настройки инжектора.

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

  • Следует избегать использования названий переменных, начинающихся с ANSIBLE_, поскольку они зарезервированы.

Работа контроллера с собственными типами полномочий показана на схеме:

../../../../_images/custom-credential-type-light.svg ../../../../_images/custom-credential-type-dark.svg
  1. При создании собственного типа полномочий администратор задает настройки входных данных и инжектора.

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

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

  4. Инжектор передает данные полномочия в среду исполнения.

    Возможны следующие способы передачи данных полномочия в среду исполнения:

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

    • дополнительная переменная (extra vars) Ansible;

    • текстовый файл, в том числе с возможностью генерации содержимого с использованием шаблонизатора Jinja.

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

Настройка входных данных#

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

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

Типовые настройки входных данных состоят из обязательного блока fields и опционального блока required.

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

  • id – идентификатор поля. Значение, указанное в этом поле, используется для передачи данных в инжектор.

  • type – тип поля:

    • string – строка;

    • boolean – логическое.

  • default – значение по умолчанию.

  • format – дополнительная проверка корректности значения, указанного в поле.

    Поддерживаются следующие значения:

    • ssh_private_key – приватный ключ SSH;

    • url – URI.

  • label – название поля при заполнении сведений о полномочии через графический интерфейс.

  • help_text – подсказка, которая выводится рядом с полем при заполнении сведений о полномочии через графический интерфейс.

  • secret – если равно true, вводимое значение является секретом.

    Для защиты секретов в полях ввода используется маскировка символов, а в таблице базы данных Astra Automation Controller – защитное преобразование.

  • multiline – логическое значение для полей типа string. При значении true поле позволяет вводить многострочный текст.

  • choices – массив доступных значений для полей типа string. Если массив не пуст, при заполнении поля через графический интерфейс значение нужно выбрать из списка, а не вводить вручную.

В блоке required содержится список идентификаторов полей, обязательных для заполнения.

Конфигурация инжектора#

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

---
extra_vars:
  auth_token: '{{ auth_token }}'

Дополнительной переменной Ansible auth_token присваивается значение поля входных данных с идентификатором auth_token.

Настройки инжектора могут содержать следующие блоки:

  • file – шаблон, на основе которого генерируется содержимое временного файла.

    Имя файла генерируется случайным образом. Оно хранится в переменной Ansible tower.filename.

    Если используется несколько полей для загрузки файлов, их следует описать в отдельных переменных, названия которых начинаются с префикса template.. Для получения имени файла следует обратиться к соответствующему значению словаря tower.filename, например:

    ---
    file:
      template.cert_file: '{{ tls_cert }}'
      template.key_file: '{{ tls_key }}'
    env:
      TLS_CERT_FILE_NAME: '{{ tower.filename.cert_file }}'
      TLS_KEY_FILE_NAME: '{{ tower.filename.key_file }}'
    

    Здесь для хранения сертификата и соответствующего ему ключа создаются два временных файла, имена которых сохраняются в переменных tower.filename.cert_file и tower.filename.key_file соответственно.

  • env – список названий переменных окружения и соответствующих им значений.

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

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

Примеры#

Пусть для работы с некоторым сервисом необходимы следующие учетные данные:

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

    Значение передается в среду исполнения через переменную окружения API_USERNAME.

  • Токен – строка, хранится в зашифрованном виде.

    Значение передается в среду исполнения через переменную окружения API_TOKEN в следующем формате:

    Bearer-Token: <token>
    
  • Уровень доступа – строка, может принимать значения low, medium и high. Значение по умолчанию – low.

    Значение передается в среду исполнения через дополнительную переменную Ansible api_access_level.

  • Приватный ключ SSH для защиты соединения.

    Значение передается в среду исполнения в виде файла, имя которого хранится в переменной окружения API_PRIVATE_SSH_KEY.

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

Параметр

Идентификатор

Тип

Обязательное

Название учетной записи

username

string

Да

Токен

token

string

Да

Уровень доступа

access_level

string

Да

Ключ SSH

ssh_key

string

Нет

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

Настройки входных данных#
---
fields:
  - id: username
    type: string
    label: Username

  - id: token
    type: string
    label: Token
    secret: true
    help_text: A string of 32 charactes long.

  - id: access_level
    type: string
    label: Access level
    choices:
      - low
      - medium
      - high
    default: low

 - id: ssh_key
   type: string
   label: SSH private key
   format: ssh_private_key
   secret: true

required:
  - username
  - token
  - access_level
Настройки инжектора#
---
env:
  API_USERNAME: '{{ username }}'
  API_TOKEN: 'Bearer-Token:: {{ token }}'
  API_PRIVATE_SSH_KEY: '{{ tower.filename.private_ssh_key }}'
extra_vars:
  api_access_level: '{{ access_level }}'
file:
  template.private_ssh_key: '{{ ssh_key }}'

Примечание

Два двоеточия в строке с параметром API_TOKEN необходимы для соблюдения корректности синтаксиса YAML. При передаче данных строка будет преобразована в указанный выше формат с одним двоеточием.

В графическом интерфейсе Astra Automation Controller форма для создания полномочий этого типа имеет следующий вид:

../../../../_images/credentials-custom-input-form.png