Руководство по системному администрированию#

Термины и сокращения#

Сценарии администрирования#

Компонент REQV не имеет собственного пользовательского интерфейса для администрирования. Все действия по управлению компонентом производятся с использованием интерфейсов, предоставляемых Платформой Kubernetes.

Ниже приведены возможные сценарии администрирования с использованием веб-интерфейcа Kubernetes и с использованием консоли клиента Kubernetes.

Программный компонент Request Validator (далее — Валидатор) может быть настроен на три режима приема запросов:

• Работа в режиме sidecar в Ingress Gateway Deployment (IGEG)

• Работа в режиме sidecar в Egress Gateway Deployment (IGEG)

• Работа в режиме отдельного сервиса Валидации

Базовое конфигурирование#

Для запуска тестового экземпляра валидатора запросов REQV используйте следующие артефакты Kubernetes:

Настройка приложения выполняется в конфигурации приложения (ConfigMap) с названием, определенным в документе «Руководство по установке». В блоке schemas данной конфигурации задаются параметры валидации тела запроса (поля) для каждого URL.

Общая настройка приложения в ConfigMap

Пример настройки REQV:

Описание полей schemas:

Описание полей audit:

Пример конфигурации для прикладного приложения

Данный пример нужен для настройки прикладного приложения для работы с REQV.

ConfigMap: Application settings: ConfigMap: Application settings

Конфигурация для добавления схем валидации

Приведенный ниже пример показывает как добавить схему валидации в REQV. Названия файлов схем используются в путях к схемам в конфигурации валидатора.

ConfigMap: Schemas: ConfigMap: Schemas

Настройка проверок валидации#

Для валидации тела запросов необходимо выполнить запрос на Ingress Gateway/Egress Gateway по заранее определенному порту, настроенному в файле с конфигурацией EnvoyFilter. Подробнее в документе Руководство по установке.

Запрос должен содержать метод POST и тело запроса в одном из форматов: XML или JSON. Путь запроса должен совпадать с определенным путем в необходимой схеме валидации (раздел "Параметры настройки" данного раздела)

Пример запроса:

curl --location --request POST 'http://ingress.ru/ping' \
--header 'Content-Type: application/xml' \
--header 'Cookie: a5bb735cfb6f25d78d49b337936fee0e=4833785809f819b4df782e9c198f83e1' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<address>
    <street>Orchardroad</street>
    <street-number>15</street-number>
    <city>Uusikaupunki</city>
    <zip>1313</zip>
    <country>Farawayistan</country>
</address>'

Настройка проверки валидации всех входящих запросов#

Для включения проверки валидации всех входящих запросов на нужный порт, например, 8088 требуется EnvoyFilter для Ingress Gateway (IGEG). Необходимо заменить {INGRESS_MATCH_LABEL} на актуальный лейбл деплоймента Ingress, чтобы данный фильтр применился к нужному Ingress, а также заменить {PORT} на 8088

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

• status_on_error: задается код ошибки при недоступности валидатора.

• max_request_bytes: максимальный размер тела запроса, поменять, если превышает.

• если сервис валидации развернут в среде Kubernetes (использование Envoy API V3), то необходимо указать порт "50052" поля grpc_service.google_grpc.target_uri.

Пример: Ingress: EnvoyFilter

Настройка проверки валидации ответов на запросы к внешним АС#

Для включения проверки валидации ответов на запросы к внешним АС на порт 8088 требуется EnvoyFilter для Egress Gateway (IGEG). Необходимо заменить {EGRESS_MATCH_LABEL} на актуальный лейбл деплоймента Egress, чтобы данный фильтр применился к нужному Egress Gateway.

Фильтр дает возможность кастомизации заголовков запросов и ответов в секциях envoy_on_response и envoy_on_request . При запросе возможна буферизация заголовков (например, заголовки path и method в секции envoy_on_request ), возможно добавление своих заголовков и изменение заголовков в запросе.

Для изменения кода ответа, не прошедшего валидацию, заголовок ":status" меняется на необходимый для прикладного сервиса.

Внимание! При неуспешной валидации тело ответа все равно доходит до прикладного сервиса, для результата валидации необходимо ориентироваться на код ответа.

Алгоритм валидирования ответов:

1. Прикладной сервис отправляет запрос к внешней АС.

2. Запрос идет через прокси Egress Gateway на определенный для запроса порт.

3. Ответ от внешней АС отправляется на sidecar Валидатора.

4. Если валидация успешная, то ответ от внешней АС приходит к прикладному сервису.

5. Если валидация неуспешная (получен ответ с HTTP кодом от Валидатора, отличный от "200"), то прикладному сервису приходит ответ с кодом "403".

Пример: Egress: EnvoyFilter

В случае валидации ответа через Egress Gateway, необходимо, также, добавить ServiceEntry для ссылки на sidecar валидатора из фильтр ( " outbound|8787||auth.local")

Egress: ServiceEntry: Egress: ServiceEntry

Проверка валидации запросов#

Проверка валидации запросов в режиме Ingress Gateway и Egress Gateway#

Для валидации тела запросов необходимо выполнить запрос на Ingress Gateway/Egress Gateway по заранее определенному порту, настроенному согласно документу Руководство по установке.

Запрос должен содержать метод POST и тело запроса в одном из форматов: XML или JSON. Путь запроса должен совпадать с определенным путем в необходимой схеме валидации.

Пример схемы валидации bar.xsd из configMap validator-schemas :

data:
  bar.xsd: |-
    <?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <xs:element name="address">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="street" type="xs:string"/>
                    <xs:element name="street-number" type="xs:string"/>
                    <xs:element name="city" type="xs:string"/>
                    <xs:element name="zip" type="xs:string"/>
                    <xs:element name="country" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
        </xs:element>
    </xs:schema>

Пример валидного XML запроса для схемы bar.xsd:

  curl -X POST -v 'reqv-ingressgateway.namespace.svc:8080/ping' \
  --header 'Content-Type: application/xml' \
  --header 'Cookie: a5bb735cfb6f25d78d49b337936fee0e=4833785809f819b4df782e9c198f83e1' \
  --header 'BAR: 1223' \
  --header 'FOO: 23432' \
  --data-raw '<?xml version="1.0" encoding="UTF-8"?>
  <address>
      <street>Orchardroad</street>
      <street-number>15</street-number>
      <city>Uusikaupunki</city>
      <zip>1313</zip>
      <country>Farawayistan</country>
  </address>'

Пример схемы валидации foo.json из configMap validator-schemas :

data:
  foo.json: |-
    {
      "$id": "http://json-schema.org/draft/2019-09/json-schema-core.html",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$comment": "sample comment",
      "title": "Config dump",
      "type": "object",
      "properties": {
        "configs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "@type": {
                "type": "string"
              },
              "last_updated": {
                "type": "string"
              },
              "bootstrap": {
                "type": "object",
                "properties": {
                  "admin": {
                    "type": "object"
                  },
                  "dynamic_resources": {
                    "type": "object"
                  },
                  "node": {
                    "type": "object"
                  },
                  "static_resources": {
                    "type": "object"
                  },
                  "stats_config": {
                    "type": "object"
                  }
                },
                "required": ["admin", "dynamic_resources", "node", "static_resources", "stats_config"]
              }
            },
            "required": ["@type", "last_updated", "bootstrap"]
          }
        }
      },
      "required": [
        "configs"
      ]
    }

Пример валидного JSON запроса для схемы foo.json:

  curl --location --request POST -v 'reqv-ingressgateway.namespace.svc:8080/' \
  --header 'method: POST' \
  --header 'path: /' \
  --header 'x-foo-first: foo1' \
  --header 'foo: BAZZZ' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "configs": [
          {
              "@type": "type.googleapis",
              "last_updated": "2020-08-29T10:45:09.046Z",
              "bootstrap": {
                  "admin": {},
                  "dynamic_resources": {},
                  "node": {},
                  "static_resources": {},
                  "stats_config": {}
              }
          }
      ]
  }'

Проверка валидации запросов в режиме sidecar#

Подключение валидатора как sidecar к отдельному сервису выполняется по аналогии с подключением к Ingress Gateway и Egress Gateway: добавление контейнера с валидатором в деплоймент сервиса. Обращение к сервису валидации выполняется по localhost:8787/check (порт зависит от предустановленного значения в конфигурации валидатора).

Запрос выполняется методом POST с обязательными заголовками: path и method , по которым будет выполнена выборка необходимой схемы валидации. Также, для корректного логирования и аудита необходимо включать заголовок x-request-id.

Пример запроса curl в сервис валидации из сервиса:

curl -X POST 'localhost:8787/check' \
--header 'path: /alone' \
--header 'method: POST' \
--header 'Content-Type: application/xml' \
--header 'x-request-id: xxx123xxx' \
--header 'BAR: 1223' \
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<address>
    <street1>Orchardroad</street1>
    <street-number>15</street-number>
    <city>Uusikaupunki</city>
    <zip>1313</zip>
    <country>Farawayistan</country>
</address>' -i

Для всех режимов работы валидатора предусмотрена возможность настройки допустимых значений (white list) для заголовков запросов. Для этого необходимо добавить в configMap validator-config следующий блок:

schemas:
  - name: 'xml-test'
    validate_headers:
      - key: BAR # имя заголовка
        required: true # если true, то заголовок должен обязательно присутствовать в запросе
        white_list: # при наличии white_list блока действует правило: все, что не разрешено - запрещено
          - pattern: ^([0-9]){4}$ 
          - pattern: ^abc$ 

В примере выше есть блок white_list с ключами pattern, в которых указываются регулярные выражения. По ним будет проверяться валидность заголовка BAR. Если хотя бы одно из регулярных выражений соответствует значению заголовка, то он считается валидным.

Добавление дочерних XSD схем#

Для использования дочерних XSD схем, содержащих дополнительные неймсмпейсы необходимо добавить их отдельными файлами в ConfigMap.

Пример использования неймспейсов в XSD схемах для валидации XML:

kind: ConfigMap
apiVersion: v1
metadata:
    name: validator-schemas
    labels:
    app: validator
data:
    foo.json: |
    {
        "$id": "http://json-schema.org/draft/2019-09/json-schema-core.html",
        ...
        "required": [
        "configs"
        ]
    }
    midi.xsd: |
    <?xml version="1.0" encoding="UTF-8" ?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
     ...
    </xs:schema>

В основной XSD схеме включается название неймспейса (xmlns:midi="1") и импорт схемы с включаемым неймспейсом по ее абсолютному пути (<xs:import namespace="1" schemaLocation="file:///schemas/midi.xsd"/>).

Пример использования неймспейса в схеме: <xs:element name="Card" type="midi:note" />

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:midi="1">
    <xs:import namespace="1" schemaLocation="file:///schemas/midi.xsd"/>
    <xs:element name="address">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="street" type="xs:string"/>
                <xs:element name="street-number" type="xs:string"/>
                <xs:element name="city" type="xs:string"/>
                <xs:element name="zip" type="xs:string"/>
                <xs:element name="country" type="xs:string"/>
                <xs:element name="Card" type="midi:note" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

Пример содержимого дополнительной схемы:

<?xml version="1.0" encoding="utf-8"?>
<xsx:schema elementFormDefault="qualified"
           xmlns:xsx="http://www.w3.org/2001/XMLSchema"
           targetNamespace="1">

    <xsx:complexType name="note">
        <xsx:sequence>
            <xsx:element name="CardNum" type="xsx:string"/>
        </xsx:sequence>
    </xsx:complexType>
</xsx:schema>

Пример валидируемого XML, включающий проверку неймспейсов:

<?xml version="1.0" encoding="UTF-8"?>
<address>
    <street>Orchardroad</street>
    <street-number>15</street-number>
    <city>Uusikaupunki</city>
    <zip>1313</zip>
    <country>Farawayistan</country>
    <Card>
        <midi:CardNum xmlns:midi="1">EXAMPLE</midi:CardNum>
    </Card>
</address>

Настройками схем валидации#

Узнать какая схема валидации была применена к запросу можно в debug режиме. Для этого в comfigMap validator-config меняем log_level с info на debug (только в целях тестирования). После выполнения запроса в логах валидатора будет сообщение с именем схемы, которая подошла под запрос:

DEBUG применяется схема валидации: имя схемы 

Если ни одна схема не подходит под запрос, код ответа будет 403 Forbidden, в логах валидатора увидим ошибку:

ERROR ошибка получения схемы для запроса 'POST:/': подходящая схема валидации для запроса 'POST:/' не найдена

Приоритет имеет первая схема в comfigMap validator-config соответствующая параметрам запроса. Например, если требуется пропустить все запросы с методом POST идущие на любой путь, то первой указываем схему с типом pass.

  - name: pass-request
    method: POST
    path: '/*'
    type: 'pass'

После выполнения запроса в логах видим сообщение:

 DEBUG применяется схема валидации: pass-request
 DEBUG пропуск запроса 'POST:/ping' без валидации (тип pass)

Если требуется валидировать определенные запросы, а все остальные, под которые не нашлось подходящей схемы пропускать - схему с типом pass нужно указать последней. Она будет иметь самый низкий приоритет и срабатывать в последнюю очередь.

Масштабирование#

Масштабирование сервиса валидации происходит посредством увеличения количества Pod экземпляров Ingress Gateway/Egress Gateway, а также отдельных сервисов, sidecar которых сервис валидации является.

Просмотр журнала событий приложения REQV#

Для просмотра и настройки логов необходимо:

• Зайти в проект контрольной панели;

• В меню выбрать пункт Workload/Pods ;

• На странице найти нужный pod;

• Перейти по сcылке в этот pod;

• Перейти на вкладку ≡ (Logs). В консоли не должно быть ошибок.

События системного журнала#

Компонент REQV оснащен собственным системным журналом. Системный журнал находится по пути /opt/synapse/logs/general. Системный лог выводится в консоль контейнера приложения. Уровень логирования задается настройками в ConfigMap, где изменяется установкой параметров log_level и log_path. Подробнее указано в разделе "Настройками схем валидации" и "Общая настройка приложения" в ConfigMap документа «Руководство по системному администрированию».

Предусмотрены следующие уровни логирования событий системного журнала: "info", "warn", "error"… По умолчанию установлен режим "info". В данном режиме выводятся события уровней "info", "warn" и "error". Уровень логирования debug и trace не рекомендуется включать при промышленной эксплуатации REQV.

log внутри контейнера REQV и содержит записи формата JSON с полями:

{
"projectName": "Имя проекта",
"podSource": "Имя pods",
"event_timestamp": "Время записи",
"message": "Текст сообщения",
"information": "Дополнительная информация, если требуется",
"rqUID": "Уникальный идентификатор запроса",
"serviceReceiver": "Имя вызываемого сервиса (получателя)",
"operationName": "Название операции (корневого тега)",
"status": "Статус (описание)"
}

Список параметров в событиях системного журнала:

• METHOD - используемый HTTP метод в запросе

• PATH - путь запроса до конечного сервиса

• VALIDATOR - название схемы валидации в конфигурационном файле

• ERROR - описание ошибки

События мониторинга#

Компонент REQV предоставляет метрики в формате Prometheus для регистрации основных событий валидации. Путь до метрик приложения находиться: localhost:9191/metrics. Для получения метрик по умолчанию назначен порт: 9191. Если нужно сменить порт, то это можно сделать в конфигурационном файле настроек ConfigMap, сменив значение параметра metrics на нужный порт. Пример настройки приведен в разделе Общая настройка приложения в ConfigMap.

Каждая метрика включает теги:

• mode — показывает режим работы сервиса валидации (ingress, egress, check).

• type — тип обращения к сервису (response, request).

• app — название приложения.

• namespace — название проекта приложения.

• pod — название Pod приложения.

• node_name — название Node, где работает приложение.

Часто встречающиеся проблемы и пути их устранения#