Created YY. Модуль decort_jwt (markdown)

YY.-Модуль-decort_jwt.md

@@ -0,0 +1,59 @@
+# Вспомогательный модуль для получения авторизационного JWT токена decort_jwt
+
+## 11.1 Обзор модуля _decort_jwt_
+Модуль _decort_jwt_ предназначен для получения авторизационного токена JWT (JSON Web Token). Данный модуль может быть полезен при массовом создании виртуальных серверов на базе одного и того же образа, так как позволяет оптимизировать количество API вызовов, инициируемых в адрес контроллера облачной платформы.
+
+По сути, данный модуль является провайдером информации и не управляет облачными ресурсами (всегда возвращает `changed: False`).
+
+## 11.2 Параметры модуля _decort_jwt_
+Ниже в алфавитном порядке приведен полный список параметров для модуля _decort_jwt_. Актуальную информацию по параметрам, которые поддерживает версия модуля, установленного на вашем Ansible-сервере, можно получить командой:
+
+`ansible-doc -t module decort_jwt`
+
+| Параметр | Тип, допустимые значения | Описание |
+| --- | --- | --- |
+| app_id | (string) | Идентификатор приложения, использующийся для подключения к авторизационному серверу. Данный параметр является обязательным.<br/> Если параметр не задан в _playbook_, модуль будет использовать значение переменной окружения _DECS_APP_ID_. |
+| app_secret | (string) | Секретный ключ приложения, который используется для подключения к авторизационному серверу. Данный параметр является обязательным. Так как он содержит секретную информацию, то его не рекомендуется задавать непосредственно в _playbook_.<br/> Если параметр не задан в _playbook_, то модуль будет использовать значение переменной окружения _DECS_APP_SECRET_. |
+| oauth2_url | (string) | URL авторизационного сервера, работающего по протоколу _Oauth2_, у которого запрашивается JWT.<br/>Данный параметр является обязательным.<br/>Если параметр не задан в _playbook_, модуль будет использовать значение переменной окружения _DECS_OAUTH2_URL_. |
+| validity | (int) | Срок действия JWT в секундах.<br/>Данный параметр является опциональным, значение по умолчанию - 3600 сек. |
+| verify_ssl | (bool)<br/>`True` <- default<br/>`False` | Позволяет отключить проверку SSL сертификатов при выполнении API вызовов в адрес авторизационного сервера, например, при работе с изолированной облачной инфраструктурой, использующей самоподписанные сертификаты.<br/>Применяйте данный параметр с осторожностью, предпочтительно в защищенных средах. |
+| workflow_callback | (string) | URL, по которому вышестоящее приложение (например, пользовательский портал или оркестратор верхнего уровня, инициирующий запуск Ansible playbook) ожидает API вызова, в параметрах которого модуль _desc_vm_ будет оперативно передавать информацию о своем статусе и текущей фазе исполнения.<br/>Данный параметр является опциональным.<br/>Функциональность callbacks в текущей версии модуля не реализована.|
+| workflow_context | (string) | Контекстная информация, которая будет содержаться в параметрах API вызова, адресованного к `workflow_callback` URL.<br>Данная информация призвана однозначно идентифицировать задачу, выполняемую модулем в настоящий момент, чтобы оркестратор верхнего уровня мог сопоставить получаемые через вызов `workflow_callback` данные со своим внутренним состоянием и отслеживать инициированные им задачи.<br/>Параметр является опциональным и имеет значение только при условии, что также задан `workflow_callback`.<br/>Функциональность callbacks в текущей версии модуля не реализована.|
+
+## 11.3 Возвращаемые значения модуля _decort_jwt_
+При успешном выполнении модуль _decort_jwt_ возвращает словарь, в котором по ключу `jwt` находится значение JWT-токена  (тип _string_).
+
+## 11.4 Пример использования модуля _decort_jwt_
+В данном примере сначала получается JWT со сроком действия 1200 сек., а затем этот JWT используется для создания виртуального сервера в режиме авторизации _jwt_ (подробнее о данном режиме см. в разделе [«Примеры различных режимов авторизации»]()).
+
+```
+---
+- hosts: ansible_master
+  tasks:
+  - name: obtain JWT with validity of 1200 sec from the OAuth2 provider 
+    decort_jwt:
+      app_id: "{{ my_app_id }}"
+      app_secret: "{{ my_app_secret }}"
+      oauth2_url: "https://sso.digitalenergy.online"
+      validity: 1200
+    delegate_to: localhost
+    register: token
+
+  - name: manage KVM VM in JWT authorization mode
+    decort_kvmvm:
+      authenticator: jwt
+      jwt: "{{ token.jwt }}"
+      controller_url: "https://cloud.digitalenergy.online"
+      name: NewVM01
+      state: present
+      cpu: 2
+      ram: 4096
+    <<<дальнейшие детали опущены>>>
+...
+```
+
+Обратите внимание, как используется JWT при создании нового виртуального сервера (в предположении, что результат выполнения _task_ для модуля _decort_jwt_ был сохранен в переменной `token`):
+
+`    jwt: "{{ token.jwt }}"`
+
+