# 03.05 Модуль decort_rg

## Обзор модуля decort_rg

Модуль decort_rg предназначен для создания, редактирования и удаления ресурсных групп (Resource Group, RG) в облачной платформе DECORT, а также для получения информации об уже существующей ресурсной группе. Модуль decort_rg позволяет:

- Создавать\\удалять ресурсные группы.
- Запрашивать информацию об уже существующих ресурсных группах.
- Редактировать ресурсные группы.
- Настраивать квоты в ресурсных группах.
- Восстанавливать ресурсные группы.
- Задавать стандартную сеть ресурсной группы.
- Настраивать доступ к ресурсным группам.

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

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

| Параметр | Тип, допустимые значения | Описание |
|----------|--------------------------|----------|
| account_id | (int) | Уникальный целочисленный идентификатор учётной записи (account), в рамках которой создаётся или уже существует данная ресурсная группа. Должен быть задан либо идентификатор, либо имя учётной записи (см. параметр `account_name`). Если одновременно заданы и `account_id`, и `account_name`, то account_name игнорируется. |
| account_name | (string) | Имя учётной записи (account), в рамках которой создаётся или уже существует данная ресурсная группа. Должно быть задано либо имя, либо идентификатор учётной записи (см. параметр `account_id`). Если одновременно заданы и `account_id`, и `account_name`, то `account_name` игнорируется. |
| access | (dict) | Параметр, позволяющий выдать,забрать, изменить права у пользователя в ресурсной группе. |
| annotation | (string) | Текстовое описание ресурсной группы. Данный аргумент является опциональным и учитывается только при создании ресурсной группы, а при всех прочих операциях игнорируется. |
| app_id | (string) | Идентификатор приложения, использующийся для подключения к контроллеру облачной платформы DECORT в режиме `authenticator: oauth2`. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль будет использовать значение переменной окружения `DECORT_APP_ID`. |
| app_secret | (string) | Секретный ключ приложения, который используется для подключения к контроллеру облачной платформы DECORT в режиме authenticator: oauth2. Данный параметр является обязательным для указанного режима. Так как он содержит секретную информацию, то его не рекомендуется задавать непосредственно в playbook. Если параметр не задан в playbook, то модуль будет использовать значение переменной окружения DECORT_APP_SECRET. |
| authenticator | Значения:<br>`legacy`<br>`oauth2`<br>`jwt` <- default | Режим аутентификации при подключении к контроллеру облачной платформы DECORT. |
| controller_url | (string) | URL контроллера, соответствующего экземпляру облачной платформы DECORT, в рамках которого должен быть создан (или уже существует) данный виртуальный сервер. Данный параметр является обязательным. |
| def_netType | (string) <br>Значения:<br>`PRIVATE` <- default<br>`PUBLIC`<br>`NONE` | Тип сети по умолчанию в ресурсной группе. Используется при создании ресурсной группы, а также, чтобы изменить ресурсную группу по умолчанию. Не обязателен. |
| def_netId | (int) | Уникальный целочисленный идентификатор сети (ViNS), используется для изменения сети по умолчанию в ресурсной группе. |
| extNetIp | (string) | IP-адрес внешней сети, к которой ресурсная группа будет подключена при создании. |
| owner | (string) | Владелец ресурсной группы. Задаётся при создании ресурсной группы, не обязателен. Если оставить пустое значение - владельцем ресурсной группы будет пользователь, создавший ресурсную группу. |
| ipcidr | (string) | IP-адрес приватной сети. Используется при создании ресурсной группы, чтобы задать ip адрес ViNS, который создастся вместе с ресурсной группой. Задаётся при параметре `def_netType` в значении `PRIVATE`. |
| jwt | (string) | JSON Web Token (JWT), который будет использоваться для подключения к контроллеру облачной платформы DECORT в режиме `authenticator: jwt`<br>Данный параметр является обязательным для указанного режима.<br>Так как он содержит потенциально секретную информацию, а сам JWT, как правило, имеет ограниченное время жизни, то его не рекомендуется задавать непосредственно в _playbook_.<br>Если этот параметр не определен в _playbook_, то модуль будет использовать значение переменной окружения _DECORT_JWT_. |
| oauth2_url | (string) | URL авторизационного сервера, работающего по протоколу Oauth2, который должен использоваться в режиме authenticator: oauth2. Данный параметр является обязательным для указанного режима. Если параметр не задан в playbook, модуль будет использовать значение переменной окружения `DECORT_OAUTH2_URL`. |
| rename | (string) | Новое имя ресурсной группы. Используется при переименовании ресурсной группы. |
| quotas | (dict) | Зарезервировано для будущих расширений, предназначено для задания или изменения квоты на ресурсы в составе данной ресурсной группы. |
| resType | (list) | Типы ресурсов, которые можно создать в ресурсной группе. |
| rg_name | (string) | Имя ресурсной группы. Данный параметр является обязательным. |
| rg_id | (int) | Уникальный целочисленный идентификатор ресурсной группы. |
| state | Значения:<br>`present` <- default<br>`absent`<br>`enabled`<br>`disabled` | Целевое состояние ресурсной группы. |
| permanently | (bool)<br>`False` <- default<br>`True` | Параметр, использующийся при удалении ресурсной группы, при значении True - ресурсная группа удалится навсегда, а при False - попадёт в корзину. |
| verify_ssl | (bool)<br>`True` <- default<br>`False` | Позволяет отключить проверку SSL сертификатов при выполнении API вызовов в адрес контроллера облачной инфраструктуры, например, при работе с изолированной облачной инфраструктурой, использующей самоподписанные сертификаты.<br>Применяйте данный параметр с осторожностью, предпочтительно в защищенных средах. |
| workflow_callback | (string) | URL, по которому вышестоящее приложение (например, пользовательский портал или оркестратор верхнего уровня, инициирующий запуск Ansible playbook) ожидает API вызова, в параметрах которого модуль будет оперативно передавать информацию о своем статусе и текущей фазе исполнения.<br>Данный параметр является опциональным.<br>Функциональность callbacks в текущей версии модуля не реализована. |
| workflow_context | (string) | Контекстная информация, которая будет содержаться в параметрах API вызова, адресованного к `workflow_callback` URL.<br>Данная информация призвана однозначно идентифицировать задачу, выполняемую модулем в настоящий момент, чтобы оркестратор верхнего уровня мог сопоставить получаемые через вызов `workflow_callback` данные со своим внутренним состоянием и отслеживать инициированные им задачи.<br>Параметр является опциональным и имеет значение только при условии, что также задан `workflow_callback`.<br>Функциональность callbacks в текущей версии модуля не реализована. |

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

Модуль decort_rg возвращает информацию о XXX в виде словаря facts со следующими ключами:
| Ключ | Тип данных | Описание |
|------|------------|----------|
| account_id | int | Уникальный целочисленный идентификатор учётной записи (account), которому принадлежит данная ресурсная группа. |
| gid | int | Идентификатор физического кластера (Grid ID), на базе которого развёрнута ресурсная группа. |
| id | int | Уникальный целочисленный идентификатор ресурсной группы. |
| name | string | Имя ресурсной группы. Обратите внимание, что это имя уникально только в рамках учётной записи, которой принадлежит данная ресурсная группа. |
| state | string | Текущее состояние ресурсной группы. Корректные состояния: CREATED, DISABLED, DELETED, DESTROYED |
| quota | dict | Текущие квоты ресурсной группы. |
| resTypes | list | Список типов ресурсов, разрешенных к созданию в данной ресурсной группе. |
| defNetId | int | Уникальный целочисленный идентификатор сети по умолчанию в данной ресурсной группе. |
| defNetType | string | Тип сети по умолчанию в данной ресурсной группе. Корректные типы сети по умолчанию: NONE, PRIVATE, PUBLIC. |

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

В данном примере показано, как создать ресурсную группу по имени MyRG в учётной записи MyAccount.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере показано, как создать ресурсную группу по имени MyRG в учётной записи MyAccount, также ограничить в ней доступ к ресурсам, задать квоты и выдать права на чтение пользователю MyUser.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    access:
      action: "grant"
      user: "MyUser"
      right: "R"
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере показано, как выдать доступ на чтение и запись пользователю MyUser в ресурсной группе по имени MyRG в учётной записи MyAccount.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    access:
      action: "grant"
      user: "MyUser"
      right: "RCX"
    quotas:
      cpu: 16
      ram: 16384
      disk: 100
      ext_ips: 20
      net_transfer: 1000
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере показано, как сменить квоту в ресурсной группе по имени MyRG в учётной записи MyAccount.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    quotas:
      cpu: 16
      ram: 16384
      disk: 100
      ext_ips: 20
      net_transfer: 1000
    resType:
      - vins
      - compute
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере показано, как изменить сеть по умолчанию в ресурсной группе по имени MyRG в учётной записи MyAccount.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    def_netType: "PRIVATE"
    def_netId: 99
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере показано, как переименовать ресурсную группу по имени MyRG на новое имя "NewRg" в учётной записи MyAccount.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    rename: "NewRg"
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере показано, как ограничить типы создаваемых ресурсов в ресурсной группе MyRG в учётной записи MyAccount.

```
- name: manage resource group
  decort_rg:
    authenticator: oauth2
    app_id: "{{ my_app_id }}"
    app_secret: "{{ my_app_secret }}"
    oauth2_url: "https://sso.digitalenergy.online"
    controller_url: "https://cloud.digitalenergy.online"
    account_name: "MyAccount"
    rg_name: "MyRG"
    resType:
      - vins
      - compute
      - k8s
      - openshift
      - lb
      - flipgroup
    state: present
  register: my_rg
  delegate_to: localhost
```

В данном примере результат работы модуля decort_rg записывается в переменную my_rg.

Модули DECORT, которым для работы требуется ресурсная группа, в качестве одного из параметров, как правило, принимают идентификатор `rg_id`. Так, например, используя модуль `decort_kvmvm` для создания виртуального сервера необходимо указать ресурсную группу, к которой будет принадлежать этот виртуальный сервер. Сделать это можно следующим образом:

```
   <прочие детали опущены>
   rg_id: "{{ my_rg.facts.id }}"
```