Security Groups

Ресурс Groups представляет собой введенную нами абстракцию, которая позволят объединить подсети в логические группы и применять к ним единые правила сетевого взаимодействия.

Terraform module
Terraform resource
API
nftables

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

Далее везде в документе подразумевается что все места, содержащие переменную $transport подразумевается одно из двух значений: icmp, icmp6.

название параметра	описание	тип данных	значение по умолчанию
name	Название Security Group	String
cidrs[]	Список CIDR, связанных с Security Group	String[]	[]
default_rules	Структура, описывающая правила по умолчанию, для пакетов не соответствующих ни одному из установленных правил в цепочке.	Object
default_rules.access	Структура, описывающая взаимодействие с пакетами не соответствующими ни одному из установленных правил в таблице.	Object
default_rules.access.default.logs	Включить/отключить логирование.	Boolean	false
default_rules.access.default.trace	Включить/отключить трассировку.	Boolean	false
default_rules.access.default.action	Определяет действие по умолчанию для пакетов, не соответствующих ни одному из установленных правил в цепочке.	Enum("ACCEPT", "DROP")	`ACCEPT`
default_rules.access.$transport	Структура, описывающая взаимодействие с ICMP-трафиком по умолчанию. Для обработки ICMP-трафика добавляется соответствующее правило в начало цепочки.	Object
default_rules.access.$transport.logs	Включить/отключить логирование.	Boolean	false
default_rules.access.$transport.trace	Включить/отключить трассировку.	Boolean	false
default_rules.access.$transport.type[]	Список, определяющий допустимые типы ICMP запросов.	Integer[]	[]
default_rules.access.$transport.action	Действие для пакетов в сформированных правил в цепочке.	Enum("ACCEPT", "DROP")	`ACCEPT`

Ограничения

name:
- Длина значения поля не должна превышать 256 символов.
- Значение поля должно начинаться и заканчиваться символами без пробелов.
- Значение должно быть уникальным в рамках типа ресурса.
cidrs[]:
- Значение элемента должно начинаться и заканчиваться символами без пробелов.
- Повторения значений в списке не допускаются.
- Необходимо указать минимум одно значение.
- В пределах одной Security Group и направления трафика (I/E), необходимо обеспечить, непересекаемость диапазонов адресов подсетей.
- Подсеть должна соответствовать формату записи, определенному в RFC 4632.
default_rules.access.icmp.type:
- Значение должно быть числом в диапазоне от 0 до 255.
- Повторения значений в списке не допускаются.
default_rules.access.icmp6.type:
- Значение должно быть числом в диапазоне от 0 до 255.
- Повторения значений в списке не допускаются.

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

name: sg-example
cidrs:
  - 10.0.0.0/24
  - 11.0.0.0/24
default_rules:
  access:
    default:
      logs: true
      trace: true
      action: ACCEPT

    icmp:
      action: DROP
      logs: true
      trace: true
      type: [0, 8]

    icmp6:
      action: DROP
      logs: true
      trace: true
      type: [0, 8]

Terraform resource является ключевым элементом в Terraform, предназначенным для управления различными аспектами инфраструктуры через код. Он позволяет задавать, настраивать и управлять инфраструктурными компонентами без привязки к их конкретным типам, обеспечивая автоматизацию развертывания и поддержки инфраструктуры согласно подходу Infrastructure as Code (IaC).

Далее везде в документе подразумевается что все места, содержащие переменную $transport ( Протокол L3/L4 уровня модели OSI.) подразумевается одно из двух значений: icmp, icmp6.

название	обязательность	тип данных	доп. описание
items	да	Object	Cписок ресурсов создаваемые terraform ресурсом.
items.key	да	String	Уникальный ключ блока items.
items.key.name	да	String	Имя Security Group.
items.key.networks	да	String[]	Список содержащий имена подсетей которые включены в указанную группу безопасности. Т.к. описывается имплементация Terrafom module в Terraform resource то имя Networks совпадает с CIDR хотя им не является.
items.key.logs	нет	Boolean	Включить/отключить логирование.
items.key.trace	нет	Boolean	Включить/отключить трассировку.
items.key.default_action	да	Enum("DROP", "ACCEPT")	Определяет действие по умолчанию для пакетов, не соответствующих ни одному из установленных правил в цепочке.
items.key.$transport	да	Object	Структура, описывающая взаимодействие с ICMP-трафиком по умолчанию. Для обработки ICMP-трафика добавляется соответствующее правило в начало цепочки.
items.key.$transport.logs	нет	Boolean	Включить/отключить логирование.
items.key.$transport.trace	нет	Boolean	Включить/отключить трассировку.
items.key.$transport.type[]	да	String[]	Список, определяющий допустимые типы ICMP запросов.
items.key.$transport.action	да	Enum("ACCEPT", "DROP")	Действие для пакетов в сформированных правил в цепочке.

Ограничения

items:
- Каждое правило должно обладать уникальным ключом для предотвращения конфликтов.
items.key:
- Имя ключа должно совпадать с значением из поля name.
items.key.name:
- Длина значения поля не должна превышать 256 символов.
- Значение поля должно начинаться и заканчиваться символами без пробелов.
- Значение должно быть уникальным в рамках типа ресурса.
items.key.networks:
- Значение поля должно начинаться и заканчиваться символами без пробелов.
- В пределах одной Security Group и направления трафика (I/E), необходимо обеспечить, непересекаемость диапазонов адресов подсетей.
- Подсеть должна соответствовать формату записи, определенному в RFC 4632.
items.key.icmp.type:
- Значение должно быть числом в диапазоне от 0 до 255.
- Повторения значений в списке не допускаются.
items.key.icmp6.type:
- Значение должно быть числом в диапазоне от 0 до 255.
- Повторения значений в списке не допускаются.

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

resource "sgroups_groups" "groups" {
    items = {
        key = {
            name           = "sg-example"
            networks       = ["10.0.0.0/24", "11.0.0.0/24"]
            logs           = true
            trace          = true
            default_action = "ACCEPT"
            icmp = {
                logs = true
                trace = true
                type = [0, 8]
                action = "DROP"
            }
            icmp6 = {
                logs = true
                trace = true
                type = [0, 8]
                action = "DROP"
            }
        }
    }
}

Более подробную документацию по API можно посмотреть здесь.
Более подробно по организации БД можно посмотреть здесь и здесь.

Приведеные ранее примеры создания Security Group c правилами по умолчанию для ICMP с использованием Terraform Module и Terraform Resource преобразуются в два API запроса.

Входные параметры

groups.grous[] - Структура, содержащая описание создаваемых Security Group
groups.groups[].defaultAction - представляет действие по умолчанию в конце цепочек для SG
groups.groups[].logs - Включить/отключить логирование.
groups.groups[].name - Security Group относительно которой рассматриваются правила.
groups.groups[].networks - Имена подсетей
groups.groups[].trace - Включить/отключить трассировку.
sgIcmpRules.rules[] - Структура, содержащая описание создаваемых правил.
sgIcmpRules.rules[].ICMP - Структура, содержащая описание создаваемых правил типа ICMP.
sgIcmpRules.rules[].ICMP.IPv - Версия IP для ICMP (IPv4 или IPv6).
sgIcmpRules.rules[].ICMP.Types - Список, определяющий допустимые типы ICMP запросов.
sgIcmpRules.rules[].SG - Security Group относительно которой рассматриваются правила.
sgIcmpRules.rules[].logs - Включить/отключить логирование.
sgIcmpRules.rules[].trace - Включить/отключить трассировку.
sgIcmpRules.rules[].action - Действие для пакетов в сформированных правил в цепочке.
syncOp - Поле определяющее действие с данными из запроса.

название	обязательность	тип данных	Значение по умолчанию	API request
название	обязательность	тип данных	Значение по умолчанию	groups	sgIcmpRules
groups.groups[]	да	Object[]		✔
groups.groups[].defaultAction	да	Enum("ACCEPT", "DROP")		✔
groups.groups[].logs	нет	Boolean	false	✔
groups.groups[].name	да	String		✔
groups.groups[].networks	нет	String[]	[]	✔
groups.groups[].trace	нет	Boolean	false	✔
sgIcmpRules.rules[]	да	Object[]			✔
sgIcmpRules.rules[].ICMP	да	Object			✔
sgIcmpRules.rules[].ICMP.IPv	да	Enum("IPv4", "IPv6")			✔
sgIcmpRules.rules[].ICMP.Types	нет	String[]	[]		✔
sgIcmpRules.rules[].SG	да	String			✔
sgIcmpRules.rules[].logs	нет	Boolean	false		✔
sgIcmpRules.rules[].trace	нет	Boolean	false		✔
sgIcmpRules.rules[].action	да	Enum("UNDEF", "ACCEPT", "DROP")			✔
syncOp	да	Enum("Delete", "Upsert", "FullSync")		✔	✔

Ограничения

groups.groups[].name:
- Длина значения поля не должна превышать 256 символов.
- Значение поля должно начинаться и заканчиваться символами без пробелов.
- Значение должно быть уникальным в рамках типа ресурса.
groups.groups[].networks[]:
- Значение элемента должно начинаться и заканчиваться символами без пробелов.
- Повторения значений в списке не допускаются.
- Необходимо указать минимум одно значение.
- В пределах одной Security Group и направления трафика (I/E), необходимо обеспечить, непересекаемость диапазонов адресов подсетей.
- Подсеть должна соответствовать формату записи, определенному в RFC 4632.
sgIcmpRules.rules[].SG:
- Длина значения поля не должна превышать 256 символов.
- Значение поля должно начинаться и заканчиваться символами без пробелов.
- Значение должно быть уникальным в рамках типа ресурса.
$node.rules[].type[]:
- Значение должно быть числом в диапазоне от 0 до 255.
- Повторения значений в списке не допускаются.

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

Security Groups
ICMP

curl '127.0.0.1:9007/v2/sync' \
--header 'Content-Type: application/json' \
--data '{
    "groups": {
        "groups": [{
            "defaultAction": "ACCEPT",
            "logs": true,
            "name": "sg-example",
            "networks": ["10.0.0.0/24", "11.0.0.0/24"],
            "trace": true
        }]
    },
    "syncOp": "Upsert"
}'

Выходные параметры

название	тип данных	описание
-	Object	в случае успеха возвращается пустое тело

Возможные ошибки API

Пользователь указал некорректные значения агрументов

HTTP code: 400
gRPC code: INVALID_ARGUMENT
gRPC number: 3

Не найден метод

HTTP code: 404
gRPC code: NOT_FOUND
gRPC number: 5

Диаграмма последовательности

curl '127.0.0.1:9007/v2/sync' \
--header 'Content-Type: application/json' \
--data '{
    "sgIcmpRules": {
        "rules": [{
            "ICMP": {
                "IPv": "IPv4",
                "Types": [0,8]
            },
            "SG": "sg-example",
            "logs": true,
            "trace": true,
            "action": "DROP",
        },
        {
            "ICMP": {
                "IPv": "IPv6",
                "Types": [0,8]
            },
            "SG": "sg-example",
            "logs": true,
            "trace": true,
            "action": "DROP",
        }]
    },
    "syncOp": "Upsert"
}'

Выходные параметры

название	тип данных	описание
-	Object	в случае успеха возвращается пустое тело

Возможные ошибки API

Пользователь указал некорректные значения агрументов

HTTP code: 400
gRPC code: INVALID_ARGUMENT
gRPC number: 3

Не найден метод

HTTP code: 404
gRPC code: NOT_FOUND
gRPC number: 5

В этом разделе мы покажем, как ресурс groups, созданный с помощью Terraform/API, внедряется в настройки nftables. В контексте HBF мы интерпретируем ресурс groups как проекцию на ресурсы IPSet и Chains которые функционируют в рамках инструмента nftables, обеспечивая более широкие возможности для управления подсетями и правилами.

$Trace - Включить/отключить трассировку.
$Transport - Протокол L3/L4 уровня модели OSI.
$TypeList - Список, определяющий допустимые типы ICMP запросов.
$Log - Включить/отключить логирование.
$Counter - Счетчик количества байтов и пакетов.
$Verdict - Результат применения правила, определяющий действие, которое будет применено к пакету.

шаблон параметра	структура параметра	значение	общие	icmp
$Trace	`nftrace set`	1 - трассировка включена 0 - трассировка выключена	✔	✔
$Transport	`icmp`			✔
$TypeList	`type {}`	Набор целочисленных значений от 0 до 255		✔
$Log	`log`	`level debug flags ip options`	✔	✔
$Counter	`counter`	`packets 0 bytes 0`	✔	✔
$Verdict	`accept`	$Verdict определяет действие, которое будет применено к пакету в соответсвии с правилом. Это поле может принимать значение `accept` или `drop` в зависимости от указанного в правиле. Подробнее: Verdict statement	✔	✔

Шаблон

chain INGRESS-INPUT-sgName {
    # **********
    $Trace $Transport $TypeList $Counter $Log $Verdict    //ICMP
    # **********
    $Trace $Counter $Log $Verdict                         //Общие
}

chain EGRESS-POSTROUTING-sgName {
    # **********
    $Trace $Transport $TypeList $Counter $Log $Verdict    //ICMP
    # **********
    $Trace $Counter $Log $Verdict                         //Общие
}

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

chain INGRESS-INPUT-sg-example {
    # **********
    nftrace set 1 icmp   type { 0, 8 } counter packets 0 bytes 0 log level debug flags ip options drop  //ICMP
    nftrace set 1 icmpv6 type { 0, 8 } counter packets 0 bytes 0 log level debug flags ip options drop  //ICMP
    # **********
    nftrace set 1 counter packets 0 bytes 0 log level debug flags ip options accept                       //Общие
}


chain EGRESS-POSTROUTING-sg-example {
    # **********
    nftrace set 1 icmp   type { 0, 8 } counter packets 0 bytes 0 log level debug flags ip options drop  //ICMP
    nftrace set 1 icmpv6 type { 0, 8 } counter packets 0 bytes 0 log level debug flags ip options drop  //ICMP
    # **********
    nftrace set 1 counter packets 0 bytes 0 log level debug flags ip options accept                       //Общие
}

Security Groups

Ограничения​

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

Ограничения​

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

Входные параметры​

Ограничения

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

Выходные параметры

Возможные ошибки API

Диаграмма последовательности

Выходные параметры

Возможные ошибки API

Шаблон​

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

Ограничения

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

Ограничения

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

Входные параметры

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

Шаблон

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