# Модули Ansible для управления облачными ресурсами в платформе DECORT
## Введение

Настоящая документация содержит руководство пользователя по библиотеке модулей decort для Ansible. С помощью этих модулей Вы сможете управлять созданием и конфигурированием облачных ресурсов в платформе DECORT (Digital Energy Cloud Orchestration Technology).

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

## Системные требования
Убедитесь, что Ваша система соответствует требованиям для работы модуля DECORT.
Системные требования для работы модуля:
- Интерпретатор Python 3.12
  - необходимые библиотеки Python указаны в файле **requirements.txt** корневой папки проекта

## Подготовка к работе

Для начала работы необходимо, чтобы Ansible было известно местоположение файлов модулей, а также настроить удобный для визуального восприятия формат вывода результата работы модулей. Для этого необходимо в рабочей директории, из которой будет запускаться Ansible, разместить файл ansible.cfg:
```
[defaults]
library=./library  ; Путь к директории library
module_utils=./module_utils  ; Путь к директории module_utils

callback_result_format=yaml  ; Настройка удобного формата вывода результата работы модулей

```

## Авторизация

### Общие параметры модулей для авторизации

<table>
  <tr>
    <th colspan="6">Параметр</th>
    <th>Тип</th>
    <th>Описание</th>
  </tr>
  <tr>
    <td colspan="6">
      app_id
    </td>
    <td>
      (str)
    </td>
    <td>
      Идентификатор приложения, использующийся для получения токена в режимах 
        <code>authenticator: bvs</code> или <code>authenticator: decs3o</code>. 
        Данный параметр является обязательным для указанных режимов. Если
        параметр не задан в playbook, модуль будет использовать значение
        переменной окружения <code>DECORT_APP_ID</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      app_secret
    </td>
    <td>
      (str)
    </td>
    <td>
      Секретный ключ приложения, использующийся для получения токена в режимах
        <code>authenticator: bvs</code> или <code>authenticator: decs3o</code>.
        Данный параметр является обязательным для указанных режимов. 
        Так как он содержит секретную информацию, то его не рекомендуется 
        задавать непосредственно в playbook. Если параметр не задан в playbook,
        то модуль будет использовать значение переменной окружения
        <code>DECORT_APP_SECRET</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      authenticator
    </td>
    <td>
      (str)
      <br>Значения:
      <br/><code>bvs</code>
      <br/><code>decs3o</code>
      <br/><code>oauth2</code>
      <br/><code>jwt</code>
      <br>Default: <code>decs3o</code>
    </td>
    <td>
      Режим аутентификации для получения токена. 
        Значение <code>oauth2</code> является устаревшим и равнозначным 
        <code>decs3o</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      controller_url
    </td>
    <td>
      (str)
    </td>
    <td>
      URL контроллера, соответствующего экземпляру облачной платформы
        DECORT. Данный параметр является обязательным.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      domain
    </td>
    <td>
      (str)
    </td>
    <td>
      Домен BVS, использующийся для получения токена в режиме 
        <code>authenticator: bvs</code>. Данный параметр является 
        обязательным для указанного режима. Если параметр не задан в playbook, 
        модуль будет использовать значение переменной окружения 
        <code>DECORT_DOMAIN</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      jwt
    </td>
    <td>
      (str)
    </td>
    <td>
      JSON Web Token (JWT), который будет использоваться для подключения
        к контроллеру облачной платформы DECORT в режиме
        <code>authenticator: jwt</code>. Данный параметр является
        обязательным для указанного режима. Так как он содержит
        потенциально секретную информацию, а сам JWT, как правило,
        имеет ограниченное время жизни, то его не рекомендуется задавать
        непосредственно в playbook. Если этот параметр не определен в
        playbook, то модуль будет использовать значение переменной
        окружения <code>DECORT_JWT</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      oauth2_url
    </td>
    <td>
      (str)
    </td>
    <td>
      URL авторизационного сервера, работающего по протоколу Oauth2,
        который должен использоваться в режимах
        <code>authenticator: bvs</code> 
        или <code>authenticator: decs3o</code>. Данный параметр является
        обязательным для указанных режимов. Если параметр не задан в
        playbook, модуль будет использовать значение переменной
        окружения <code>DECORT_OAUTH2_URL</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      password
    </td>
    <td>
      (str)
    </td>
    <td>
      Пароль пользователя, который должен использоваться в режиме
        <code>authenticator: bvs</code>. Данный параметр является
        обязательным для указанного режима. Так как он содержит секретную 
        информацию, то его не рекомендуется задавать непосредственно
        в playbook. Если параметр не задан в playbook, модуль будет 
        использовать значение переменной окружения 
        <code>DECORT_PASSWORD</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      username
    </td>
    <td>
      (str)
    </td>
    <td>
      Логин пользователя, который должен использоваться в режиме
        <code>authenticator: bvs</code>. Данный параметр является
        обязательным для указанного режима. Если параметр не задан в playbook, 
        модуль будет использовать значение переменной окружения 
        <code>DECORT_USERNAME</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      verify_ssl
    </td>
    <td>
      (bool)
      <br>Default: <code>true</code>
    </td>
    <td>
      Позволяет отключить проверку SSL сертификатов при выполнении API
        вызовов в адрес контроллера облачной инфраструктуры, например,
        при работе с изолированной облачной инфраструктурой, использующей
        самоподписанные сертификаты. Применяйте данный параметр с
        осторожностью, предпочтительно в защищенных средах.
    </td>
  </tr>
</table>

### Пример авторизации с помощью DECS3O
```
- name: Example
  hosts: localhost
  tasks:
    - name: DECS3O auth
      decort_module_name:
        # Специфичные для модулей параметры упущены
        # Пример демонстрирует только параметры для авторизации
        app_id: "{{ app_id }}"
        app_secret: "{{ app_secret }}"
        authenticator: decs3o
        controller_url: https://dynamix.local
        oauth2_url: https://sso-dynamix.local
```

### Пример авторизации с помощью BVS
```
- name: Example
  hosts: localhost
  tasks:
    - name: BVS auth
      decort_module_name:
        # Специфичные для модулей параметры упущены
        # Пример демонстрирует только параметры для авторизации
        app_id: "{{ app_id }}"
        app_secret: "{{ app_secret }}"
        authenticator: bvs
        controller_url: https://dynamix.local
        oauth2_url: https://bvs.local
        domain: dynamix
        username: "{{ username }}"
        password: "{{ password }}"
```

### Пример авторизации с помощью JSON Web Token

```
- name: Example
  hosts: localhost
  tasks:
    - name: Auth with JWT
      decort_module_name:
        # Специфичные для модулей параметры упущены
        # Пример демонстрирует только параметры для авторизации
        authenticator: jwt
        controller_url: "{{ controller_url }}"
        jwt: "{{ jwt }}"
```