# Модуль decort_disk
## Обзор модуля decort_disk

Модуль **decort_disk** предназначен для выполнения следующих действий над дисками:
- создавать
- удалять (в корзину или безвозвратно)
- восстановливать из корзины
- изменять:
  - имя
  - размер
  - лимиты ввода/вывода
  - включать/отключать общий доступ
  - политику хранения

## Параметры модуля decort_disk
Ниже приведен список параметров для модуля **decort_disk** (за исключением [общих параметров авторизации](./введение.md#общие-параметры-модулей-для-авторизации)):

<table>
  <tr>
    <th colspan="6">Параметр</th>
    <th>Тип</th>
    <th>Описание</th>
  </tr>
  <tr>
    <td colspan="6">
      <a name="account_id">
        account_id
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
      Уникальный целочисленный идентификатор аккаунта, которому принадлежит данный диск.
      <br>При идентификации диска по имени (см. параметр <a href=#param_name>name</a>) должен быть задан либо идентификатор, либо имя аккаунта (см. параметр <a href=#account_name>account_name</a>).
      <br>Если одновременно заданы и <a href=#account_id>account_id</a>, и <a href=#account_name>account_name</a>, то <a href=#account_name>account_name</a> игнорируется.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="account_name">
        account_name
      </a>
    </td>
    <td>
      (str)
    </td>
    <td>
      Имя аккаунта, которому принадлежит данный диск.
      <br>При идентификации диска по имени (см. параметр <a href=#param_name>name</a>) должно быть задано либо имя, либо идентификатор учётной записи (см. параметр <a href=#account_id>account_id</a>).
      <br>Если одновременно заданы и <a href=#account_id>account_id</a>, и <a href=#account_name>account_name</a>, то <a href=#account_name>account_name</a> игнорируется.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="description">
        description
      </a>
    </td>
    <td>
      (str)
    </td>
    <td>
      Текстовое описание диска.
      <br>Данный параметр является опциональным и учитывается только при создании диска, а при всех прочих операциях игнорируется.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="param_id">
        id
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
      Уникальный целочисленный идентификатор диска.
      <br>Соответствующий диск должен существовать (таким образом, с помощью id нельзя создать новый диск, а только управлять уже имеющимися).
      <br>Если задан данный параметр, то параметры <a href=#param_name>name</a>, <a href=#account_name>account_name</a> и <a href=#account_id>account_id</a> игнорируются.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="force_detach">
        force_detach
      </a>
    </td>
    <td>
      (bool)
      <br>Default: <code>false</code>
    </td>
    <td>
      Задаёт поведение платформы при попытке удалить диск, подключённый к виртуальной машине.
      <br>По умолчанию, удаление подключённых дисков не разрешается, и попытка удалить такой диск приведёт к аварийному завершению модуля.
      <br>Чтобы изменить это поведение, явно установите <code>force_detach: true</code>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="limitIO">
        limitIO
      </a>
    </td>
    <td>
      (dict)
    </td>
    <td>
      Параметр, позволяющий ограничить скорость ввода/вывода диска как в iops, так и в байтах в секунду.
      <br>Обратите внимание, что параметры с total не задаются вместе с read/write.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        read_bytes_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        read_bytes_sec_max
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        read_iops_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        read_iops_sec_max
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        size_iops_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        total_bytes_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        total_bytes_sec_max
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        total_iops_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        total_iops_sec_max
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        write_bytes_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        write_bytes_sec_max
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        write_iops_sec
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
        write_iops_sec_max
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="param_name">
        name
      </a>
    </td>
    <td>
      (str)
    </td>
    <td>
      Имя диска.
      <br>Для идентификации диска требуется либо его <a href=#param_name>name</a> и информация об аккаунте (<a href=#account_id>account_id</a> или <a href=#account_name>account_name</a>), которому принадлежит диск, либо его <a href=#param_id>id</a>.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="permanently">
        permanently
      </a>
    </td>
    <td>
      (bool)
      <br>Default: <code>false</code>
    </td>
    <td>
      Параметр, использующийся при удалении диска.
      <br>При значении <code>true</code> - диск удалится навсегда, а при <code>false</code> - попадёт в корзину.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="place_with">
        place_with
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
      Идентификатор образа диска, из которого следует взять параметр <a href=#sep_id>sep_id</a>, чтобы разместить данный диск на той же системе хранения данных, что и указанный образ диска.
      <br>Данный параметр является опциональным и используется только на стадии создания диска.
      <br>Если задан <a href=#place_with>place_with</a>, то <a href=#sep_id>sep_id</a> игнорируется.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="pool">
        pool
      </a>
    </td>
    <td>
      (str)
    </td>
    <td>
      Название пула на системе хранения данных, в рамках которой следует создать данный диск.
      <br>Этот параметр используется только на стадии создания диска и игнорируется при операциях над уже существующими дисками.
      <br>Параметр является опциональным, если не задан, то платформа будет использовать пул, который сконфигурирован на целевой системе хранения как пул по умолчанию.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="reason">
        reason
      </a>
    </td>
    <td>
      (str)
      <br>Default: <code>Managed by Ansible decort_disk</code>
    </td>
    <td>
      Причина, по которой было выполнено какое-либо действие.
      <br>В данном модуле используется только при удалении диска.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="sep_id">
        sep_id
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
      Идентификатор системы хранения данных (Storage End-point).
      <br>Данный параметр определяет систему хранения данных, на ресурсах которой создаётся диск.
      <br>Используется только при создании диска и игнорируется при прочих операциях.
      <br>Альтернативой данному параметру является <a href=#place_with>place_with</a>, позволяющий разместить диск на той же системе хранения, что и указанный образ диска, на базе которого создаётся виртуальная машина.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="shareable">
        shareable
      </a>
    </td>
    <td>
      (bool)
      <br>Default: <code>false</code>
    </td>
    <td>
      Включение/отключение общего доступа к диску.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="size">
        size
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
      Размер диска в ГБ.
      <br>Этот параметр является обязательным при создании диска.
      <br>Если он задан для уже существующего диска, а текущий размер диска меньше заданного, то будет предпринята попытка увеличить размер диска.
      <br>При прочих операциях данный параметр игнорируется.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="state">
        state
      </a>
    </td>
    <td>
      (str)
      <br>Значения:
      <br><code>present</code>
      <br><code>absent</code>
      <br>Default: <code>present</code>
    </td>
    <td>
      Целевое состояние диска.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      <a name="storage_policy_id">
        storage_policy_id
      </a>
    </td>
    <td>
      (int)
    </td>
    <td>
      Идентификатор политики хранения.
      <br>Обязателен при создании.
    </td>
  </tr>
</table>

## Возвращаемые значения модуля decort_disk
Модуль **decort_disks** возвращает информацию о диске в виде словаря `facts` со следующими ключами:

<table>
  <tr>
    <th colspan="6">Ключ</th>
    <th>Тип</th>
    <th>Описание</th>
  </tr>
  <tr>
    <td colspan="6">
      account_id
    </td>
    <td>
      int
    </td>
    <td>
      Уникальный целочисленный идентификатор аккаунта, которому принадлежит диск.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      computes
    </td>
    <td>
      dict
    </td>
    <td>
      Словарь, в котором ключ - идентификатор, а значение - имя виртуальной машины, к которой в настоящий момент подключён диск. Если диск не подключён, то возвращается пустой словарь.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      gid
    </td>
    <td>
      int
    </td>
    <td>
      Идентификатор физического кластера (Grid ID), на ресурсах которого создан диск.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      id
    </td>
    <td>
      int
    </td>
    <td>
      Уникальный целочисленный идентификатор данного диска.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      iotune
    </td>
    <td>
      dict
    </td>
    <td>
      Текущие ограничения ввода/вывода диска.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      read_bytes_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      read_bytes_sec_max
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      read_iops_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      read_iops_sec_max
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      size_iops_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      total_bytes_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      total_bytes_sec_max
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      total_iops_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      total_iops_sec_max
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      write_bytes_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      write_bytes_sec_max
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      write_iops_sec
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td></td>
    <td colspan="5">
      write_iops_sec_max
    </td>
    <td>
      int | null
    </td>
    <td></td>
  </tr>
  <tr>
    <td colspan="6">
      name
    </td>
    <td>
      str
    </td>
    <td>
      Имя диска. Обратите внимание, что имя диска не является уникальным с точки зрения системы хранения данных, на которой этот диск расположен.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      pool
    </td>
    <td>
      str
    </td>
    <td>
      Имя пула на системе хранения данных, в котором размещаются ресурсы диска.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      sep_id
    </td>
    <td>
      int
    </td>
    <td>
      Идентификатор системы хранения данных (Storage Endpoint), на которой размещаются ресурсы данного диска.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      size
    </td>
    <td>
      int
    </td>
    <td>
      Размер диска в ГБ.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      size_available
    </td>
    <td>
      float
    </td>
    <td>
      Размер незанятого пространства в ГБ.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      size_used
    </td>
    <td>
      float
    </td>
    <td>
      Размер используемого пространства в ГБ.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      state
    </td>
    <td>
      str
    </td>
    <td>
      Текущий статус диска.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      storage_policy_id
    </td>
    <td>
      int
    </td>
    <td>
      Идентификатор политики хранения.
    </td>
  </tr>
  <tr>
    <td colspan="6">
      to_clean
    </td>
    <td>
      bool
    </td>
    <td>
      Диск помечен для очистки после удаления.
    </td>
  </tr>
</table>

## Пример использования модуля decort_disk

В данном примере создаётся диск размером 50ГБ (`size: 50`), на ресурсах системы хранения данных под номером 1 (`sep_id: 1`) в пуле "data01".

```
- name: Manage disk
  decort_disk:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    name: "DataDisk01"
    size: 50
    account_name: "MyAccount"
    sep_id: 1
    description: "Disk example"
    pool: data01
    storage_policy_id: 1
  register: my_data_disk01
```
В следующих двух примерах для существующего диска с именем "DataDisk01" задаются все доступные лимиты на операции ввода/вывода.

```
- name: Manage disk
  decort_disk:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    name: "DataDisk01"
    account_name: "MyAccount"
    limitIO:
      read_bytes_sec: 10000
      write_bytes_sec: 5000
      read_iops_sec и write_iops_sec
      read_iops_sec: 2500
      write_iops_sec: 1000
      read_bytes_sec_max: 11000
      write_bytes_sec_max: 6000
      read_iops_sec_max: 3000
      write_iops_sec_max: 1500
      size_iops_sec: 1000
  register: my_data_disk01

- name: Manage disk
  decort_disk:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    name: "DataDisk01"
    account_name: "MyAccount"
    limitIO:
      total_bytes_sec: 15000
      total_iops_sec: 3500
      total_bytes_sec_max: 17000
      total_iops_sec_max: 4500
      size_iops_sec: 1000
  register: my_data_disk01
```

В данном примере выполняется восстановление удаленного диска с id 111 из корзины.

```
- name: Manage disk
  decort_disk:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    id: 111
    size: 10
  register: my_data_disk01
```

В данном примере выполняется переименование диска с id 111 на новое имя "NewExampleDisk".

```
- name: Manage disk
  decort_disk:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    id: 111
    name: "NewExampleDisk"
    size: 10
  register: my_data_disk01
```

Здесь результат работы модуля decort_disk записывается в переменную my_data_disk01. Для получения идентификатора диска, например, при подключении его к виртуальной машине, следует воспользоваться показанной ниже конструкцией:

```
- name: Manage compute
  decort_kvmvm:
    << для краткости фрагмент опущен >>
    data_disks:
      - "{{ my_data_disk01.facts.id }}"
    << для краткости фрагмент опущен >>
```