wiki-decort-ansible/10.0.0/модуль-decort_security_group.md

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

Модуль **decort_security_group** предназначен для выполнения следующих действий над группой безопасности:
- **получить информацию** (см. [примеры](#получить-информацию))
- **создать** (см. [примеры](#создать))
  - **с указанием описания** (см. [параметр description](#description) и [примеры](#с-указанием-описания))
- **удалить** (см. [параметр state](#state) и [примеры](#удалить))
- **изменить** (см. [примеры](#изменить))
  - **название** (см. [параметр name](#param_name) и [примеры](#название))
  - **описание** (см. [параметр description](#description) и [примеры](#описание))
  - **правила** (см. [параметр rules](#rules) и [примеры](#правила))

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

<table>
  <tr>
    <th colspan="4">Параметр</th>
    <th>Тип</th>
    <th>Описание</th>
  </tr>
  <tr>
    <td colspan="4">
        account_id
    </td>
    <td>
      (int)
    </td>
    <td>
      Идентификатор аккаунта. Обязательный при создании.<br>Не поддерживается изменение для существующей группы безопасности.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      <a name="description">
        description
      </a>
    </td>
    <td>
      (str)
    </td>
    <td>
      Описание.
    </td>
  </tr>
  <tr>
    <td colspan="4">
        id
    </td>
    <td>
      (int)
    </td>
    <td>
      Идентификатор.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      <a name="param_name">
        name
      </a>
    </td>
    <td>
      (str)
    </td>
    <td>
      Название. Обязательный при создании.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      <a name="rules">
        rules
      </a>
    </td>
    <td>
      (dict)
    </td>
    <td>
      Словарь, описывающий правила группы безопасности.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="3">
        mode
    </td>
    <td>
      (str)
      <br>Значения:
      <br><code>delete</code>
      <br><code>match</code>
      <br><code>update</code>
      <br>Default: <code>update</code>
    </td>
    <td>
      Режим работы параметра.
      <br><code>delete</code> - указанные управила отсутствуют.
      <br><code>match</code> - существуют только указанные правила.
      <br><code>update</code> - указанные правила существуют.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="3">
        objects
    </td>
    <td>
      (list)
    </td>
    <td>
      Cписок словарей, описывающих целевые правила.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td colspan="2">
        direction
    </td>
    <td>
      (str)
      <br>Значения:
      <br><code>INBOUND</code>
      <br><code>OUTBOUND</code>
    </td>
    <td>
      Направление трафика. Обязательный параметр.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td colspan="2">
        ethertype
    </td>
    <td>
      (str)
      <br>Значения:
      <br><code>IPV4</code>
      <br><code>IPV6</code>
    </td>
    <td>
      Протокол, инкапсулированный в Ethernet-кадр.<br>Значение по умолчанию при создании правила: <code>IPV4</code>
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td colspan="2">
        id
    </td>
    <td>
      (int)
    </td>
    <td>
      Идентификатор правила.
    </td>
  </tr>
    </tr>
    <tr>
      <td></td>
      <td></td>
    <td colspan="2">
        port_range
    </td>
    <td>
      (dict)
    </td>
    <td>
      Диапазон портов TCP/UDP.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td></td>
    <td colspan="1">
        min
    </td>
    <td>
      (int)
    </td>
    <td>
      Нижняя граница диапазона.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td></td>
    <td colspan="1">
        max
    </td>
    <td>
      (int)
    </td>
    <td>
      Верхняя граница диапазона.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td colspan="2">
        protocol
    </td>
    <td>
      (str)
      <br>Значения:
      <br><code>ICMP</code>
      <br><code>TCP</code>
      <br><code>UDP</code>
    </td>
    <td>
      Протокол, инкапсулированный в IP-пакет.
    </td>
  <tr>
    <td></td>
    <td></td>
    <td colspan="2">
        remote_ip_prefix
    </td>
    <td>
      (str)
    </td>
    <td>
      Подсеть, в которую должен входить IP-адрес удалённого хоста.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      <a name="state">
        state
      </a>
    </td>
    <td>
      (str)
      <br>Значения:
      <br><code>absent</code>
      <br><code>present</code>
    </td>
    <td>
      Целевое состояние.
      <br><code>absent</code> - безвозвратно удалён или не существует.
      <br><code>present</code> - существует и не удалён.
      <br>Значение по умолчнию при создании: <code>present</code>
    </td>
  </tr>
</table>

## Возвращаемые значения

Модуль **decort_security_group** возвращает информацию о группе безопасности в виде словаря `facts` со следующими ключами:

<table>
  <tr>
    <th colspan="3">
      Ключ
    </th>
    <th>
      Тип
      <br>данных
    </th>
    <th>
      Описание
    </th>
  </tr>
  <tr>
    <td colspan="3">
      account_id
    </td>
    <td>
      int
    </td>
    <td>
      Идентификатор аккаунта.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      created_by
    </td>
    <td>
      str
    </td>
    <td>
      Пользователь, создавший объект.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      created_timestamp
    </td>
    <td>
      int
    </td>
    <td>
      Unix-время создания.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      description
    </td>
    <td>
      str
    </td>
    <td>
      Описание.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      id
    </td>
    <td>
      int
    </td>
    <td>
      Идентификатор.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      name
    </td>
    <td>
      str
    </td>
    <td>
      Название.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      rules
    </td>
    <td>
      list
    </td>
    <td>
      Список словарей, описывающих правила.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="2">
      direction
    </td>
    <td>
      str
    </td>
    <td>
      Направление трафика.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="2">
      ethertype
    </td>
    <td>
      str
    </td>
    <td>
      Протокол, инкапсулированный в Ethernet-кадр.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="2">
      id
    </td>
    <td>
      int
    </td>
    <td>
      Идентификатор правила.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="2">
      port_range
    </td>
    <td>
      dict
    </td>
    <td>
      Диапазон портов TCP/UDP.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td colspan="1">
      min
    </td>
    <td>
      int
    </td>
    <td>
      Нижняя граница диапазона.
    </td>
  </tr>
  <tr>
    <td></td>
    <td></td>
    <td colspan="1">
      max
    </td>
    <td>
      int
    </td>
    <td>
      Верхняя граница диапазона.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="2">
      protocol
    </td>
    <td>
      str | null
    </td>
    <td>
      Протокол, инкапсулированный в IP-пакет.
    </td>
  </tr>
  <tr>
    <td></td>
    <td colspan="2">
      remote_ip_prefix
    </td>
    <td>
      str
    </td>
    <td>
      Подсеть, в которую должен входить IP-адрес удалённого хоста.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      updated_by
    </td>
    <td>
      str
    </td>
    <td>
      Пользователь, обновивший объект.
    </td>
  </tr>
  <tr>
    <td colspan="3">
      updated_timestamp
    </td>
    <td>
      int
    </td>
    <td>
      Unix-время обновления.
    </td>
  </tr>
</table>

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

### Получить информацию
```
- name: Example
  hosts: localhost
  tasks:
    - name: Get security group info
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
```

### Создать
```
- name: Example
  hosts: localhost
  tasks:
    - name: Create security group
      decort_security_group:
        # Параметры для авторизации упущены
        account_id: "{{ account_id }}"
        name: "{{ security_group_name }}"
        state: present
```

#### С указанием описания
```
- name: Example
  hosts: localhost
  tasks:
    - name: Create security group with description
      decort_security_group:
        # Параметры для авторизации упущены
        account_id: "{{ account_id }}"
        name: "{{ security_group_name }}"
        description: "{{ description }}"
        state: present
```

### Удалить
```
- name: Example
  hosts: localhost
  tasks:
    - name: Delete security group
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
        state: absent
```

### Изменить
#### Название
```
- name: Example
  hosts: localhost
  tasks:
    - name: Change security group name
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
        name: "{{ new_security_group_name }}"
```

#### Описание
```
- name: Example
  hosts: localhost
  tasks:
    - name: Change security group description
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
        description: "{{ new_security_group_description }}"
```

#### Правила
#### Обновить
```
- name: Example
  hosts: localhost
  tasks:
    - name: Update security group rules
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
        rules:
          mode: update
          objects:
            - direction: "{{ rule1_direction }}"
              ethertype: "{{ rule1_ethertype }}"
              port_range:
                min: "{{ rule1_port_min }}"
                max: "{{ rule1_port_max }}"
              protocol: "{{ rule1_protocol }}"
              remote_ip_prefix: "{{ rule1_remote_ip_prefix }}"
            - direction: "{{ rule2_direction }}"
              ethertype: "{{ rule2_ethertype }}"
              port_range:
                min: "{{ rule2_port_min }}"
                max: "{{ rule2_port_max }}"
              protocol: "{{ rule2_protocol }}"
              remote_ip_prefix: "{{ rule2_remote_ip_prefix }}"
```

#### Удалить
```
- name: Example
  hosts: localhost
  tasks:
    - name: Delete security group rules
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
        rules:
          mode: delete
          objects:
            - id: "{{ rule_id }}"
```

#### Привести в соответствие
```
- name: Example
  hosts: localhost
  tasks:
    - name: Match security group rules
      decort_security_group:
        # Параметры для авторизации упущены
        id: "{{ security_group_id }}"
        mode: match
          objects:
            - id: "{{ rule1_id }}"
            - id: "{{ rule2_id }}"
            - direction: "{{ rule3_direction }}"
              ethertype: "{{ rule3_ethertype }}"
              port_range:
                min: "{{ rule3_port_min }}"
                max: "{{ rule3_port_max }}"
              protocol: "{{ rule3_protocol }}"
              remote_ip_prefix: "{{ rule3_remote_ip_prefix }}"
```