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

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


Обратите внимание:

- Загрузочный диск для виртуальной машины создаётся и подключается автоматически в процессе создания этой машины.
- Модуль decort_disk служит для управления дополнительными дисками (т.н. data-дисками);
- Подключение дополнительных дисков, созданных посредством decort_disk, к виртуальным машинам выполняется с помощью модуля управления виртуальными машинами (см. модуль decort_kvmvm).

## Параметры модуля decort_disk

Ниже в алфавитном порядке приведен полный список параметров для модуля decort_disk. Актуальную информацию по параметрам, которые поддерживает версия модуля, установленного на вашем Ansible-сервере, можно получить командой:
`ansible-doc -t module decort_disk`


| Параметр | Тип, допустимые значения | Описание |
| ------ | ------ | ------ |
| account_id | (int) | Уникальный целочисленный идентификатор аккаунта, которому принадлежит данный диск. При идентификации диска по имени (см. параметр `name`) должно быть задан либо идентификатор, либо имя аккаунта (см. параметр `account_name`). Если одновременно заданы и `account_id`, и `account_name`, то `account_name` игнорируется.|
|account_name | (string) | Имя аккаунта, которому принадлежит данный диск. При идентификации диска по имени (см. параметр name) должно быть задано либо имя, либо идентификатор учётной записи (см. параметр `account_id`). Если одновременно заданы и `account_id`, и `account_name`, то `account_name` игнорируется. |
| annotation | (string)<br>Default: `Disk by decort_disk` | Текстовое описание диска. Данный параметр является опциональным и учитывается только при создании диска, а при всех прочих операциях игнорируется.|
| app_id | (string) | Идентификатор приложения, использующийся для подключения к контроллеру облачной платформы DECORT в режиме authenticator: oauth2. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль будет использовать значение переменной окружения `DECORT_APP_ID`.|
|app_secret | (string) | Секретный ключ приложения, который используется для подключения к контроллеру облачной платформы DECORT в режиме authenticator: oauth2. Данный параметр является обязательным для указанного режима. Так как он содержит секретную информацию, то его не рекомендуется задавать непосредственно в playbook. Если параметр не задан в playbook, то модуль будет использовать значение переменной окружения `DECORT_APP_SECRET`.|
| authenticator | Значения:<br/>`oauth2`<br/>`jwt` | Режим аутентификации при подключении к контроллеру облачной платформы DECORT. Данный параметр является обязательным. |
|controller_url | (string) | URL контроллера, соответствующего экземпляру облачной платформы DECORT, в рамках которого должен быть создан (или уже существует) данный диск. Данный параметр является обязательным.|
|id | (int) | Уникальный целочисленный идентификатор диска. Соответствующий диск должен существовать (таким образом, с помощью id нельзя создать новый диск, а только управлять уже имеющимися). Если задан данный параметр, то параметры `name`, `account_name` и `account_id` игнорируются.|
| iops | (int)<br>Default: `2000` | Ограничение ввода/вывода диска. Используется при создании диска. |
| force_detach | (bool)<br/>Default: `false` | Задаёт поведение платформы при попытке удалить диск, подключённый к виртуальной машине.<br/>По умолчанию, удаление подключённых дисков не разрешается, и попытка удалить такой диск приведёт к аварийному завершению модуля. Чтобы изменить это поведение, явно установите `force_detach: true`. |
|jwt | (string) | JSON Web Token (JWT), который будет использоваться для подключения к контроллеру облачной платформы DECORT в режиме `authenticator: jwt` Данный параметр является обязательным для указанного режима. Так как он содержит потенциально секретную информацию, а сам JWT, как правило, имеет ограниченное время жизни, то его не рекомендуется задавать непосредственно в playbook. Если этот параметр не определен в playbook, то модуль будет использовать значение переменной окружения `DECORT_JWT`.|
| limitIO | (dict) | Параметр, позволяющий ограничить скорость ввода/вывода диска как в iops, так и в байтах в секунду.  Обратите внимание, что параметры с total не задаются вместе с read/write. Все возможные подпараметры можно увидеть в примерах. |
| name | (string) | Имя диска. Для идентификации диска требуется либо его `name` и информация об аккаунте (`account_id` или `account_name`), которому принадлежит диск, либо его `id`.|
|oauth2_url | (string) | URL авторизационного сервера, работающего по протоколу Oauth2, который должен использоваться в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль будет использовать значение переменной окружения `DECORT_OAUTH2_URL`.|
| permanently | (bool)<br>Default: `false` | Параметр, использующийся при удалении диска, при значении `true` - диск удалится навсегда, а при `false` - попадёт в корзину. |
| place_with | (int) | Идентификатор образа диска, из которого следует взять параметр `sep_id`, чтобы разместить данный диск на той же системе хранения данных, что и указанный образ диска. Данный параметр является опциональным и используется только на стадии создания диска. Если задан `place_with`, то `sep_id` игнорируется.|
| pool | (string) | Название пула на системе хранения данных, в рамках которой следует создать данный диск. Этот параметр используется только на стадии создания диска и игнорируется при операциях над уже существующими дисками. Параметр является опциональным, если не задан, то платформа будет использовать пул, который сконфигурирован на целевой системе хранения как пул по умолчанию. |
| reason | (string)<br>Default: `Managed by Ansible decort_disk` | Причина, по которой было выполнено какое-либо действие. В данном модуле используется только при удалении диска. |
| sep_id | (int) | Идентификатор системы хранения данных (Storage End-point). Данный параметр определяет систему хранения данных, на ресурсах которой создаётся диск. Используется только при создании диска и игнорируется при прочих операциях. Альтернативой данному параметру является `place_with`, позволяющий разместить диск на той же системе хранения, что и указанный образ диска, на базе которого создаётся виртуальная машина.|
| shareable | (bool)<br>Default: `false` | Включение/отключение общего доступа к диску.
| size | (int) | Размер диска в ГБ. Этот параметр является обязательным при создании диска. Если он задан для уже существующего диска, а текущий размер диска меньше заданного, то будет предпринята попытка увеличить размер диска. При прочих операциях данный параметр игнорируется.|
| state | (str)<br>Значения:<br>`present`<br>`absent`<br>Default: `present` | Целевое состояние диска. |
| type | (string)<br>Значения:<br>`B`<br>`D`<br>Default: `D` | Тип создаваемого диска. `B` - Boot/загрузочный, `D` - Data/с данными. |
| verify_ssl | (bool)<br/>Default: `false` | Позволяет отключить проверку SSL сертификатов при выполнении API вызовов в адрес контроллера облачной инфраструктуры, например, при работе с изолированной облачной инфраструктурой, использующей самоподписанные сертификаты.<br/>Применяйте данный параметр с осторожностью, предпочтительно в защищенных средах. |

## Возвращаемые значения модуля decort_disk

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


|Ключ |	Тип данных |	Описание|
| ------ | ------ | ------ |
| account_id |	int |	Уникальный целочисленный идентификатор аккаунта, которому принадлежит диск.|
| attached_to |	int |	Идентификатор виртуальной машины, к которой в настоящий момент подключён диск. Если диск не подключён, то `attached_to: 0`|
| gid |	int |	Идентификатор физического кластера (Grid ID), на ресурсах которого создан диск.|
| id |	int |	Уникальный целочисленный идентификатор данного диска.|
| iotune | dict | Текущие ограничения ввода/вывода диска. |
| name |	string |	Имя диска. Обратите внимание, что имя диска не является уникальным с точки зрения системы хранения данных, на которой этот диск расположен.|
| pool |	string |	Имя пула на системе хранения данных, в котором размещаются ресурсы диска.|
|sep_id |	int |	Идентификатор системы хранения данных (Storage Endpoint), на которой размещаются ресурсы данного диска.|
| size |	int |	Размер диска в ГБ.|
| state |	string | Текущий статус диска. |


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

В данном примере создаётся диск размером 50ГБ (`size: 50`), с ограничением ввода/вывода в 2000 iops, на ресурсах системы хранения данных под номером 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
    iops: 2000
    annotation: "Disk example"
    pool: data01
  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 }}"
    << для краткости фрагмент опущен >>
```