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

Термины и определения#

Термин/Аббревиатура	Определение
Платформа	Платформа оркестрации приложений со средствами автоматизации и управления на основе политик, например, Kubernetes
URL	Система унифицированных адресов электронных ресурсов
Тraces	Цепочка единичных операций (span), представляющих часть потока выполнения запроса. Тrace позволяет визуализировать активность запроса при его перемещении по системе и является самостоятельной единицей трассировки
Node Платформы	Единица Kubernetes, кластера инфраструктуры Платформы, предоставляющая среду для работы контейнеров
Zipkin хранилище	Внешняя система хранения и отображения данных трассировки совместимая с форматом Zipkin
Platform V Synapse Service Mesh	Программный продукт на базе Istio SE, обеспечивающий возможность создания сервисной сети поверх Платформенной в Kubernetes
Контрольная панель	Проект, где запущены управляющие приложения Synapse Service Mesh (компонент POLM)
Istio SE	Настраиваемая сервисная сетка с открытым исходным кодом, служащая для взаимодействия, мониторинга и обеспечения безопасности контейнеров в кластере Kubernetes
Управление политиками / POLM	Компонент Управление политиками из состава продукта Platform V Synapse Service Mesh
Сервис трассировки / TRAS	Компонент Сервис трассировки продукта Platform V Synapse Service Mesh

Программный компонент Сервис трассировки (код TRAS) из состава программного продукта Platform V Synapse Service Mesh (код SSM) не имеет собственного пользовательского интерфейса для администрирования. Все действия по управлению производятся с использованием интерфейсов, предоставляемых Платформой Kubernetes. Ниже приведены возможные сценарии администрирования с использованием веб-интерфейса Платформы и консоли клиента Платформы. Название Deployment или pod — synapse-tracer.

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

Сценарий 1. Конфигурирование для подключения#

Подключение осуществляется администраторами контрольной панели.

Для конфигурации компонента воспользуйтесь различными артефактами:

Артефакт	Содержание	Описание
Deployment	Параметры запуска контейнера приложения в Платформе	Артефакт устанавливает наименование экземпляра приложения, ссылку на образ контейнера приложения, запрашиваемые ресурсы, публикуемые порты, параметры liveness- и readiness-проб, параметры подключения sidecar-контейнеров и необходимость их использования, точки монтирования конфигурационных артефактов в файловую систему контейнера
Config Map	tracerconfig.json tracerconfigfilter.json	Файл, содержащий параметры конфигурации приложения
Secret	Ключи и сертификаты	Файлы, содержащие ключи и сертификаты. Содержат конфиденциальные данные, поэтому загружается в виде секрета
Service	Артефакт для регистрации приложения в service discovery Платформы	Селекторы и порты для подключения приложения к механизмам распределения трафика Платформы

Для работы traces необходимо внести корректировки в файл настройки конфигурации Service Mesh (kind: IstioOperator):

Пример фрагмента конфигурации:

spec:
  techPreview:
    meshConfig:
      defaultConfig:
        tracing:
          tlsSettings:
            caCertificates: /var/run/secrets/istio/root-cert.pem
            mode: SIMPLE
            subjectAltNames:
              - >-
                spiffe://cluster.local/ns/control-panel-namespace/sa/default
          zipkin:
            address: >-
              synapse-tracer-svc.control-panel-namespace.svc.cluster.local:8788

В случае установки в контрольную панель Istio-se версии выше 1.12 необходимо добавить следующий блок, что бы в trace попадали необходимые заголовки, изменения будут выглядеть так:

  spec:
    techPreview:
      meshConfig:
        defaultConfig:
          tracing:
            custom_tags:
              method:
                header:
                  defaultValue: method-empty
                  name: ':method'
              x-synapse-spname:
                header:
                  defaultValue: x-synapse-spname-empty
                  name: x-synapse-spname
              authority:
                header:
                  defaultValue: authority-empty
                  name: ':authority'
              scheme:
                header:
                  defaultValue: scheme-empty
                  name: ':scheme'
              host:
                header:
                  defaultValue: host-empty
                  name: host
              x-envoy-internal:
                header:
                  defaultValue: x-envoy-internal-empty
                  name: x-envoy-internal
              grpc-accept-encoding:
                header:
                  defaultValue: grpc-accept-encoding-empty
                  name: grpc-accept-encoding
              x-synapse-messageid:
                header:
                  defaultValue: x-synapse-messageid-empty
                  name: x-synapse-messageid
              x-forwarded-proto:
                header:
                  defaultValue: x-forwarded-proto-empty
                  name: x-forwarded-proto
              x-envoy-decorator-operation:
                header:
                  defaultValue: x-envoy-decorator-operation-empty
                  name: x-envoy-decorator-operation
              x-synapse-custom:
                header:
                  defaultValue: x-synapse-custom-empty
                  name: x-synapse-custom
              x-b3-spanid:
                header:
                  defaultValue: x-b3-spanid-empty
                  name: x-b3-spanid
              content-type:
                header:
                  defaultValue: content-type-empty
                  name: content-type
              x-request-id:
                header:
                  defaultValue: x-request-id-empty
                  name: x-request-id
              x-synapse-status-code:
                header:
                  defaultValue: x-synapse-status-code-empty
                  name: x-synapse-status-code
              x-synapse-rqtm:
                header:
                  defaultValue: x-synapse-rqtm-empty
                  name: x-synapse-rqtm
              x-b3-sampled:
                header:
                  defaultValue: x-b3-sampled-empty
                  name: x-b3-sampled
              x-synapse-scname:
                header:
                  defaultValue: x-synapse-scname-empty
                  name: x-synapse-scname
              x-b3-parentspanid:
                header:
                  defaultValue: x-b3-parentspanid-empty
                  name: x-b3-parentspanid
              x-synapse-corellationid:
                header:
                  defaultValue: x-synapse-corellationid-empty
                  name: x-synapse-corellationid
              x-synapse-rquid:
                header:
                  defaultValue: x-synapse-rquid-empty
                  name: x-synapse-rquid
              x-forwarded_for:
                header:
                  defaultValue: x-forwarded-for-empty
                  name: x-forwarded-for
              x-synapse-operationname:
                header:
                  defaultValue: x-synapse-operationname-empty
                  name: x-synapse-operationname
              x-b3-traceid:
                header:
                  defaultValue: x-b3-traceid-empty
                  name: x-b3-traceid
              x-synapse-serviceversion:
                header:
                  defaultValue: x-synapse-serviceversion-empty
                  name: x-synapse-serviceversion
              x-synapse-from-pod-name:
                header:
                  defaultValue: x-synapse-from-pod-name-empty
                  name: x-synapse-from-pod-name
            max_path_tag_length: 256
            sampling: 100
            tlsSettings:
              caCertificates: /var/run/secrets/istio/root-cert.pem
              mode: SIMPLE
              subjectAltNames:
                - 'spiffe://cluster.local/ns/istio-system/sa/default'
            zipkin:
              address: 'synapse-tracer-svc.istio-system.svc.cluster.local:8788'    

Перечень параметров конфигурирования traces (файл tracerconfig.json):

Пример конфигурационного файла

{"host":"http://egw-istio-system-svc.istio-system.svc.cluster.local:6767/api/v2/spans",
"second_host":"http://egw-istio-system-svc.istio-system.svc.cluster.local:6768/api/v2/spans",
"is_timeout_on": true,
"clientTimeout":500,
"is_retry_on": false,
"retry_count": 1,
"retry_wait_time_msec":100,
"client_max_conn":100,
"https_port":":8788",
"server_max_request_per_conn":100,
"tls_server_uncheck": false,
"spanBuffer":30,
"log_time":10,
"stop_trigger": 10,
"time_to_pausing_sec": 10,
"max_input_rate": 2000,
"control_panel_tag":"istio-system",
"cluster_name_tag": "syn-dev",
"config_name":"tracerconfig.json",
"filter_name": "tracerconfigfilter.json",
"path":"/var/synapsetracer/configs/",
"enable_tls_from_sidecars": true}

host - endpoint по которому traces будет отправлять traces (в случае с Egress traces направляются непосредственно на сервис Egress, а конечная точка определяется параметрами роутинга);
is_timeout_on - флаг, определяющий будет ли использоваться таймаут, заданный в параметре clientTimeout;
clientTimeout - таймаут для ожидания ответа от endpoint;
is_retry_on - флаг, определяющий будет ли попытка повтора отправки;
retry_count - в случае включения повторов необходимо определить количество попыток повтора;
retry_wait_time - в случае включения повторов необходимо определить время таймаута между повторами;
client_max_conn - максимальное количество коннектов допустимое для клиента (при отправке сообщений в endpoint);
https_port - номер порта, на котором работает сервер, принимающий запросы от граничных прокси;
server_max_request_per_conn - максимальное количество запросов, прошедших к серверу в рамках одной сессии (требуется для распределения нагрузки);
tls_server_uncheck - параметр, убирающий валидацию серверного сертификата endpoint (только для тестов);
spanBuffer - количество span в одной отправке (бандл);
log_time - период времени через который выводится справочная информация в консоли pod traces;
stop_trigger - количество неуспешных отправок бандлов в trace коллектор, при котором отправка встает на паузу;
time_to_pausing_sec - время паузы отправки бандлов в trace коллектор;
max_input_rate - максимальное количество span на входе trace, при котором отправка бандлов в trace коллектор ставится на паузу;
control_panel_tag - имя проекта в котором установлен trace (будет добавляться к каждому span в качестве тега);
cluster_name_tag - имя кластера в котором установлен trace (будет добавляться к каждому span в качестве тега);
config_name - имя конфигурационного файла параметров trace (не подлежит изменению);
filter_name - имя файла с параметрами фильтрации (не подлежит изменению);
path - путь, по которому монтируется конфигурация (не подлежит изменению).
*-second - параметры резервного хранилища

Все параметры, не касающиеся сервера, возможно изменить без рестарта pod.

Пример файла с параметрами фильтрации

 {"tags":
 [
   {"tag":"sometag","value":"somevalue"},{"tag":"sometag","value":"somevalue"},{"tag":"sometag","value":"somevalue"}
 ],
 "namespaces":
  [
   {"namespace":"all_namespaces"},{"namespace":"somenamespace"},{"namespace":"somenamespace"}
  ]
 }

В блоке "tags" перечисляются ключи и значения тегов по которым необходимо отфильтровать span, то есть span в которых встретится тег с таким значением будут отброшены.

В блоке "namespaces" перечисляются неймспейсы, span которых необходимо добавить в обработку, остальные будут отброшены. Если в блоке "namespases" есть элемент — "namespace":"all_namespaces", независимо от остальной части раздела все span, попадающие на traces, будут добавлены в обработку. Параметры фильтрации применяются без рестарта pods trace.

Сценарий 2. Настройка заголовков для HTTP-вызова#

Компонент нужен для получения traces от Граничного и Сервисного прокси и передачи их в Zipkin-хранилище.

На каждом этапе цепочки вызовов микросервисов необходима передача следующих HTTP-заголовков с момента их первой генерации:

Заголовок	Описание
`x-request-id`	Уникальный идентификатор сообщения. Формат: GUID. Генерируется с помощью Envoy, если запрос еще не имеет такого заголовка
`x-b3-traceid`	Уникальный идентификатор Trace. Формат: строка с hex-представлением 64- или 128-битного целого числа. Генерируется с помощью Envoy, если запрос еще не имеет такого заголовка
`x-b3-spanid`	Уникальный идентификатор Span. Формат: строка с hex-представлением 64-битного целого числа
`x-b3-parentspanid`	Уникальный идентификатор родительского Span. Формат: строка с hex-представлением 64-битного целого числа
`x-b3-sampled`	Признак сэмплирования запроса. Если значение равно `1`, то трассировка этого запроса будет отправлена в систему сбора информации
`x-b3-flags`	Дополнительные флаги: отладка и другие

Сервисный прокси генерирует данные заголовки автоматически, если они отсутствуют при вызове компонента.

Стандартные заголовки#

Каждый сервис, который вызывается в единой цепочке вызовов, должен передавать полученные при его вызове заголовки.

Для HTTP-вызова:

Пример передачи заголовков для HTTP:

@RequestMapping(method = RequestMethod.POST, path = "/")
public ResponseEntity postInfo(@RequestHeader HttpHeaders inHeaders) {
Map<String, String> outHeaders = new HashMap<>();
outHeaders.put("x-request-id", inHeaders.getFirst("x-request-id"));
outHeaders.put("x-b3-traceid", inHeaders.getFirst("x-b3-traceid"));
outHeaders.put("x-b3-spanid", inHeaders.getFirst("x-b3-spanid"));
outHeaders.put("x-b3-parentspanid", inHeaders.getFirst("x-b3-parentspanid"));
outHeaders.put("x-b3-sampled", inHeaders.getFirst("x-b3-sampled"));
outHeaders.put("x-b3-flags", inHeaders.getFirst("x-b3-flags"));
outHeaders.put("x-ot-span-context", inHeaders.getFirst("x-ot-span-context"));
HttpEntity<Object> requestHttpEntity = new HttpEntity<>(requestBody, outHeaders);
ResponseEntity<Object> responseHttpEntity = restTemplate.postForEntity(url, requestHttpEntity, Object.class);
}

Для gRPC-вызова:

Пример передачи заголовков gRPC:

    @Grpc(serviceName = "com.sbt.synapse.gateway.MessageAsyncChannel/processMessage")
public class GrpcService implements BaseSynapseService<Message.ProtoMessage, HeartbeatOuterClass.Heartbeat> {
   @Grpc(serviceName = "com.sbt.synapse.gateway.MessageAsyncChannel/processMessage")
   private GrpcService<Message.ProtoMessage, HeartbeatOuterClass.Heartbeat> grpcService;

   ...
   @Override
   public HeartbeatOuterClass.Heartbeat processSync(SynapseMessage<Message.ProtoMessage> message) {
     MessageHeaders outHeaders = message.getHeaders();
             grpcService.invoke(protoMessage)
                 .authority(authority)
                 .headers(outHeaders);
     ...
       }
 ...
}

Для передачи gRPC-заголовков используется библиотека com.sbt.synapse:synapse-grpc-core:2.0.12.

Пользовательские заголовки (необязательные)#

На данный момент в состав Span включаются следующие пользовательские теги:

Имя тега	Значение
`synapse.corellationid`	`request.headers["x-synapse-corellationid"]`
`synapse.messageid`	`request.headers["x-synapse-messageid"]`
`synapse.rquid`	`request.headers["x-synapse-rquid"]`
`synapse.rqtm`	`request.headers["x-synapse-rqtm"]`
`synapse.scname`	`request.headers["x-synapse-scname"]`
`synapse.servicename`	`request.headers["x-synapse-servicename"]`
`synapse.serviceversion`	`request.headers["x-synapse-serviceversion"]`
`synapse.spname`	`request.headers["x-synapse-spname"]`
`synapse.status_code`	`response.headers["x-synapse-status-code"]` или `request.headers["x-synapse-status-code"]`
`synapse.status_desc_bin`	`response.headers["x-synapse-status-desc-bin"]` или `request.headers["x-synapse-status-desc-bin"]`

Сценарий 3. Запуск#

Для запуска через веб-интерфейс Платформы:

Шаг	Действие
Авторизуйтесь в веб-консоли Платформы	Перейдите по ссылке URL веб-консоли нужного кластера Платформы. В окне ввода учетных данных введите логин и пароль
Перейдите в нужный проект	Выполните следующие действия: 1. В пункте меню Projects выберите из списка нужный проект
Запустите pod	2. Выберите в меню пункт Workload/Deployments. 3. Найдите на странице нужный Deployment. Воспользуйтесь при необходимости поиском по имени . 4. Пройдите по ссылке в наименовании на вкладку :Workload/Deployments: --> (Deployment): 4. Стрелкой вверх (Increase the pod count) установите нужное количество pods
Выйдите из веб-консоли Платформы	5. Раскройте меню нажатием на имя пользователя и выберите пункт Log out. 6. Закройте окно браузера

Для запуска через консоль Платформы:

Шаг	Действие
Войдите в консольного клиента платформы	Ведите в окне командной строки в приглашении команды: `kubectl config set-credentials <user>/<host-alias-без-точек>:<port> \--token=<token>` `kubectl config set-cluster <host-alias-без-точек>:<port> \--insecure-skip-tls-verify=true --server=https://<host>:<port>` `kubectl config set-context <namespace>/<host-alias-без-точек>:<port>/<user> \--user=<user>/<host-alias-без-точек>:<port> \--namespace=maximov-test --cluster=<host-alias-без-точек>:<port>` `kubectl config use-context <namespace>/<host-alias-без-точек>:<port>/<user>`
Запустите компонент	Выполните в консоли команду: `kubectl scale --replicas=<N> deployment/<имя Деплоймента>`, где: `N`>0 — требуемое количество запущенных pods

Сценарий 4. Остановка#

Для остановки через веб-интерфейс Платформы:

Шаг	Действие
Авторизуйтесь в веб-консоли Платформы	Перейдите по ссылке URL веб-консоли нужного кластера Платформы. Введите в окне ввода учетных данных логин и пароль
Перейдите в нужный проект	Выполните следующие действия: 1. Выберите в пункте меню Projects из списка нужный проект
Остановите компоненты	2. Выберите в меню пункт Workload/Deployments. 3. Найдите на странице нужный Deployment. Воспользуйтесь при необходимости поиском по имени. 4. Пройдите по ссылке в наименовании на вкладку Detail и стрелкой вниз (Decrease the pod count) установите значение 0
Выйдите из веб-консоли Платформы	5. Раскройте меню нажатием на имя пользователя и выберите пункт Log out. 6. Закройте окно браузера

Для остановки через консоль Платформы:

Шаг	Действие
Войдите в консольного клиента платформы	Введите в окне командной строки в приглашении команды: kubectl config set-credentials <user>/<host-alias-без-точек>:<port> \--token=<token> <br>kubectl config set-cluster <host-alias-без-точек>:<port> \--insecure-skip-tls-verify=true --server=https://<host>:<port> <br>kubectl config set-context <namespace>/<host-alias-без-точек>:<port>/<user> \--user=<user>/<host-alias-без-точек>:<port> \--namespace=maximov-test --cluster=<host-alias-без-точек>:<port> <br>kubectl config use-context <namespace>/<host-alias-без-точек>:<port>/<user>
Остановите компоненты	Выполните в консоли команду: `kubectl scale --replicas=0 deployment/<имя Деплоймента>`
Завершите сеанс работы	Выполните в консоли команду: `kubectl logout`

Сценарий 5. Настройка выделения ресурсов#

Для настройки через веб-интерфейс Платформы:

Шаг	Действие
Авторизуйтесь в веб-консоли Платформы	Перейдите по ссылке URL веб-консоли нужного кластера Платформы. Введите в окне ввода учетных данных логин и пароль
Перейдите в проект	Выберите в пункте меню Projects из списка нужный проект
Откройте Deployment	Выполните следующие действия: 1. Выберите в пункте меню Workload/Deployments 2. Найдите на странице нужный Deployment. Воспользуйтесь при необходимости поиском по имени. 3. Пройдите по ссылке в наименовании на вкладку Detail → YAML
Скорректируйте параметры	Найдите в окне редактирования параметры: `spec.template.spec.containers[0].resources.limits.cpu` `spec.template.spec.containers[0].resources.limits.memory` `spec.template.spec.containers[0].resources.requests.cpu` `spec.template.spec.containers[0].resources.requests.memory` Установите нужные значения
Сохраните изменения	Нажмите Save
Проверьте конфигурацию	Нажмите Reload. Проверьте сохранение изменений
Выйдите из веб-консоли Платформы	Раскройте меню нажатием на имя пользователя и выберите пункт Log out. 8. Закройте окно браузера

Сценарий 6. Просмотр событий системного журнала#

Для просмотра системного журнала через веб-интерфейс Платформы:

Шаг	Действие
Авторизуйтесь в веб-консоли Платформы	Перейдите по ссылке URL веб-консоли нужного кластера Платформы. Введите в окне ввода учетных данных логин и пароль
Перейдите в проект	Выберите в пункте меню Projects из списка нужный проект
Перейдите в Pods	Выполнить следующие действия: 1. Выберите в меню пункт Workload/Pods; 2. Найдите на странице нужный pod. Воспользуйтесь при необходимости поиском по имени. 3. Пройдите по ссылке в наименовании на вкладку Logs
Посмотрите события	Проверьте в терминале системные журналы pod
Выйдите из веб-консоли Платформы	Раскройте меню нажатием на имя пользователя и выберите пункт Log out. Закройте окно браузера

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

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

Системный журнал приложения можно видеть во вкладке logs (описано в сценарии просмотра системного журнала). Предусмотрен уровень логирования событий системного журнала: info.

В режиме «info» (режим по умолчанию) в событиях системного журнала периодически (в соответствии с заданным в конфигурации приложения TRAS периодом) выводятся сообщения о статистике отправляемых traces:

Текст ошибки	Описание
printing stats for log time	Период вывода статистики
bandle sends (all time)	Количество отправленных блоков (объединений) span в хранилище. Счетчик сквозной, показывает общее количество за время существования pod
spanConverts (in second for logTime period)	Количество обработанных span в секунду за период логирования
error send to collector (all time)	Количество ошибок при попытке отправить бандл, показывает общее количество за время существования pod
maximal time of request per logTime period	Максимальное время отклика Zipkin хранилища при отправке в него бандла, за период логирования
error send to collector (delta)	Количество ошибок при попытке отправить бандл, за период вывода статистики

Также выводятся сообщения об ошибках в процессе работы приложения:

Текст ошибки	Описание
non 200 response from collector:	Ошибка отправки бандла в Zipkin хранилище. После двоеточия выводится текст ошибки
non 200 bundle:	Ошибка отправки в Zipkin хранилище сопровождается выводом неотправленного бандла в консоль

Вернуть журнал в режим по умолчанию можно командой:

curl localhost:9192/loglevel -d ""

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

Компонент TRAS не интегрирован с компонентом Объединенный мониторинг Unimon Plaform V Monitor (MONA). Для наблюдения за состоянием pods используйте существующие средства мониторинга Платформы, описанные в документации на конкретную платформу.

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

Проблема	Решение
В логах pods встречаются ошибки типа: 2022-05-20T10:03:54.718Z warn non 200 response from collector: no healthy upstream	Убедитесь, что endpoint Zipkin хранилища, настроен и готов к работе, убедитесь в наличии физического доступа до endpoint из кластера Платформы