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

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

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

## Системные требования
Убедитесь, что Ваша система соответствует требованиям для работы модуля DECORT.
Системные требования для работы модуля:
- Ansible 10.5.0
- Python 3.10.12
- PyJWT 2.9.0 Python module
- requests 2.32.3 Python module
- DynamiX Enterprise 4.1.0

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

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

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

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

<table>
  <tr>
    <th colspan="6">Параметр</th>
    <th>Тип</th>
    <th>Описание</th>
  </tr>
  <tr>
    <td colspan="6">
      app_id
    </td>
    <td>
      (str)
    </td>
    <td>
      Идентификатор приложения, использующийся для подключения к контроллеру
        облачной платформы DECORT в режиме <code>authenticator: oauth2</code>.
        Данный параметр является обязательным для указанного режима. Если
        параметр не задан в playbook, модуль будет использовать значение
        переменной окружения <code>DECORT_APP_ID</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      app_secret
    </td>
    <td>
      (str)
    </td>
    <td>
      Секретный ключ приложения, который используется для подключения к
        контроллеру облачной платформы DECORT в режиме
        <code>authenticator: oauth2</code>. Данный параметр является
        обязательным для указанного режима. Так как он содержит секретную
        информацию, то его не рекомендуется задавать непосредственно в
        playbook. Если параметр не задан в playbook, то модуль будет
        использовать значение переменной окружения
        <code>DECORT_APP_SECRET</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      authenticator
    </td>
    <td>
      (str)
      <br>Значения:
      <br/><code>oauth2</code>
      <br/><code>jwt</code>
    </td>
    <td>
      Режим аутентификации при подключении к контроллеру облачной платформы
        DECORT. Обязательный параметр.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      controller_url
    </td>
    <td>
      (str)
    </td>
    <td>
      URL контроллера, соответствующего экземпляру облачной платформы
        DECORT. Данный параметр является обязательным.
    </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: oauth2</code>. Данный параметр является
        обязательным для указанного режима. Если параметр не задан в
        playbook, модуль будет использовать значение переменной
        окружения <code>DECORT_OAUTH2_URL</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      verify_ssl
    </td>
    <td>
      (bool)
      <br>Default: <code>true</code>
    </td>
    <td>
      Позволяет отключить проверку SSL сертификатов при выполнении API
        вызовов в адрес контроллера облачной инфраструктуры, например,
        при работе с изолированной облачной инфраструктурой, использующей
        самоподписанные сертификаты. Применяйте данный параметр с
        осторожностью, предпочтительно в защищенных средах.
    </td>
  </tr>
</table>

### Пример авторизации с помощью app_id и app_secret

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

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

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