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

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

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

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

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

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

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

../../../../_images/custom-credential-type-light.svg

../../../../_images/custom-credential-type-dark.svg

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

Возможны следующие способы передачи данных полномочия в среду исполнения:
- переменная окружения;
- дополнительная переменная (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

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

Содержание

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

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

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

Примеры#