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

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

Термин/Аббревиатура

Определение

CPU

Central Processing Unit

АС

Автоматизированная система

JSON

JavaScript Object Notation

Pod

Набор контейнеров внутри узла кластера Kubernetes

Deployment

Набор инструкций для запуска приложения в кластере Kubernetes

Ниже приведены возможные сценарии администрирования компонента App Hub Application Controller, (AHAC) с использованием консоли клиента Kubernetes (kubectl).

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

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

Запуск компонента#

Шаг

Действия

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

Запустите компонент App Hub Application Controller, (AHAC)

В консоли выполните команду:
kubectl scale --replicas=<N> deployment/<имя deployment>

N>0 — требуемое количество запущенных Pod

Остановка компонента#

Шаг

Действие

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

-

Остановите компонент App Hub Application Controller, (AHAC)

В консоли выполните команду:
kubectl scale --replicas=0 deployment/<имя deployment>

-

Механизм перезапуска подов#

Шаг

Действие

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

-

Установите Application в текущий namespace

В консоли выполните команду:
kubectl apply -f <имя файла>.yaml

-

Проверьте Deployment на наличие аннотации synapse.sber/recid

В консоли выполните команду:
kubectl get deployment <имя деплоймента> найдите аннотацию synapse.sber/recid

Аннотация synapse.sber/recid находится в разделе spec.template.metadata.annotations позволяет перезапускать поды у Workloads(Deployment,DaemonSet,StatefulSet,ReplicaSet,Pod) при её изменении, предоставляя возможность перечитывать конфигурацию приложений. Добавление аннотации synapse.sber/recid можно отключить настройкой recIdDisabled

Обновите конфигурацию вашего приложения в Application

В консоли выполните команду:
kubectl apply -f <имя файла>.yaml с обновленной конфигурацией, затем команду kubectl get deployment <имя деплоймента> она покажет, что synapse.sber/recid изменилась и поды перезапустились

-

Проверка работоспособности#

Шаг

Действие

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

-

Проверьте работоспособность компонента App Hub Application Controller, (AHAC)

В консоли выполните команду:
kubectl port-forward pod/<имя пода> <portnum>:<portnum>
Запустите еще одно окно консоли, в нем выполните команду:
curl -v localhost:<portnum>readyz.
В ответ должна быть получен код 200 и статус OK
Завершите проброс портов, для этого нажмите Ctrl+C

<portnum> - номер порта указанный в аргументе запуска health-probe-bind-address компонента App Hub Application Controller, (AHAC)

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

Шаг

Действие

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

-

Сохраните Deployment

В консоли выполните команду:
kubectl get -o yaml deployment/<имя deployment> > <путь к файлу>.yaml

-

Скорректируйте параметры

Откройте файл, полученный на предыдущем шаге в текстовом редакторе (например, Notepad++), найдите в нем параметры:
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
 Укажите нужные значения

-

Загрузите Deployment

В консоли выполните команду:
kubectl apply -f <путь к файлу>.yaml

-

Выгрузка системного журнала#

Шаг

Действия

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

-

Выгрузите лог

В консоли выполните команду:
kubectl logs -c <имя контейнера> <имя пода> > <имя файла>.txt
где <имя контейнера> - название контейнера приложения компонента App Hub Application Controller, (AHAC)

-

Просмотр метрик мониторинга#

Шаг

Действия

Примечание

Установите нужный проект в текущем контексте пользователя

Введите команду:
kubectl config set-context --current -n <имя проекта>

-

Получите метрики мониторинга

В консоли выполните команду:
kubectl port-forward pod/<имя пода> <portnum>:<portnum>
Запустите еще одно окно консоли, в нем выполните команду:
curl localhost:<portnum>/metrics.
В консоль будут выведены мгновенные значения метрик мониторинга
Завершите проброс портов, для этого нажмите Ctrl+C

<portnum> - номер порта указанный в аргументе запуска metrics-bind-address компонента App Hub Application Controller, (AHAC)

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

Системный лог выводится в консоль контейнера приложения.

Уровень логирования задается в дистрибутиве и может быть изменен установкой параметра logging.level конфигурации.

Рекомендуется устанавливать уровень логирования info (используется по-умолчанию) или выше (warn, error). Уровни debug, trace не рекомендуется устанавливать в промышленных инсталляциях.

Сообщения в логе#

App Hub Application Controller в своем системном журнале фиксирует следующие события

Запуск сервера прикладных метрик#

2024-04-27T13:46:39Z INFO controller-runtime.metrics Starting metrics server
2024-04-27T13:46:39Z INFO controller-runtime.metrics Serving metrics server {"bindAddress": ":8080", "secure": false}

Запуск сервера health-check#

2024-04-27T13:46:39Z INFO starting server {"kind": "health probe", "addr": "[::]:8081"}

Поиск и удаление релизов, Application которых был удалён до запуска контроллера#

2024-05-16 13:51:09.017119 INF Запуск удаления артефактов удалённых приложений
2024-05-16 13:51:09.119836 INF Удаление отсутствующего релиза apps.synapse.sber.business-lounge.demo-cloud-esb-artemis-kafka
2024-05-16 13:51:09.119923 INF Найден релиз business-lounge.demo-cloud-esb-artemis-kafka, удаляем

Получение Application и запуск задачи разворачивания релиза#

2024-05-17 08:49:22.802041 INF Получено событие Reconcile: test/1c-integration4-1.0.2
2024-05-17 08:49:22.813092 INF Получено приложение test/1c-integration4-1.0.2 (UID:a21e1b06-3e38-4b8a-a508-4b0574aa14ec)
2024-05-17 08:49:22.840673 INF Задание создано успешно: esb-install-job-1c-integration4-1.0.2-lv4wv
2024-05-17 08:49:22.852751 INF Обработка приложения test/1c-integration4-1.0.2 завершена за 50.72319ms

Запуск мониторинга состояния задания обработки релиза Application#

2024-05-17 08:49:22.852814 INF Мониторим статус job esb-install-job-1c-integration4-1.0.2-lv4wv...
2024-05-17 08:49:33.353017 INF Статус выполнения job esb-install-job-1c-integration4-1.0.2-lv4wv: failed

События прикладного журнала#

Прикладной журнал фиксируется в файлах /var/logs/ahac/application.log в формате JSON.

В прикладном журнале фиксируются события системного журнала:

Каждая запись о событии в журнале содержит:

Имя поля

Требование к заполнению

Обязательность

level

Уровень записи журнала

1

time

Время фиксации события в pod. Заполняется автоматически

1

message

Тело события журнала

1

error

Информация об ошибке (для уровня записи error)

0

Пример записи в прикладной лог#

{
    "level": "info",
    "time": "2024-05-16 12:59:29.785845",
    "message": "Мониторим статус job esb-uninstall-job-demo-1c-sap-008-1.0.01-9v5pc..."
}
{
    "level": "info",
    "time": "2024-05-16 12:59:29.785862",
    "message": "Найден релиз capp-test-1-3-1.0.0.test, удаляем"
}
{
    "level": "error",
    "error": "Application.apps.synapse.sber \"demo-1c-sap-008-1.0.01\" not found",
    "time": "2024-05-16 12:59:29.785924",
    "message": "не удалось найти Application: test/demo-1c-sap-008-1.0.01"
}

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

Компонент App Hub Application Controller выставляет HTTP-endpoint (/metrics), на котором публикует метрики мониторинга в формате Prometheus:

Полный список прикладных метрик приведен в таблице:

№

Метрика

Описание

Показатель/Тип

Измерение

1

Количество job, выполнивших определенную операцию

Статистика по job в разрезе операций - отображает количество job, выполнивших определенную операцию (установка/удаление/обновление Application)

ahac_job_launch/counter

application=<application>"
namespace="<Проект установки Job>"
operation=<статус>

2

Количество job, выполнивших определенную операцию с определенным статусом

Статистика по job в разрезе операций и статусов - отображает количество job, выполнивших определенную операцию (установка/обновление/удаление Application) с определенным статусом (успешно/неуспешно)

ahac_reconcile_operation/counter

application=<application>"
namespace="<Проект установки Application>"
operation=<операция обработки Application>
status=<статус>

3

Количество активных обработчиков событий реконсиляции

Количество активных конкурентных обработчиков событий реконсиляции

controller_runtime_active_workers/gauge

controller=<application>"

4

Максимальное количество конкурентно обрабатываемых событий реконсиляции

Максимальное количество событий реконсиляции, которые могут быть конкурентно обработаны контроллером

controller_runtime_max_concurrent_reconciles/gauge

controller=<application>"

5

Общее количество ошибок обработки Application

Общее количество ошибок обработки Application у контроллера

controller_runtime_reconcile_errors_total/gauge

controller=<application>"

6

Время обработки событий реконсиляции

Отображает время обработки событий реконсиляции в секундах

controller_runtime_reconcile_time_seconds_bucket/histogram

controller=<application>"
le=<[0.5, 5, 10]>

7

Общее количество добавлений в очередь

Общее количество добавлений в очередь обработки контроллера

workqueue_adds_total/counter

name=<application>"

8

Размер рабочей очереди событий реконсиляции

Отображает текущий размер очереди событий реконсиляции, обрабатываемых контроллером

workqueue_depth/gauge

name=<application>"

9

Наиболее продолжительное время работы обработчика события рабочей очереди

Отображает время работы обработчика события реконсиляции, исполнявшегося наиболее продолжительное время (в секундах)

workqueue_longest_running_processor_seconds/gauge

name=<application>"

10

Время нахождения элемента в очереди

Отображает, как долго элемент остается в рабочей очереди перед тем, как будет обработан

workqueue_queue_duration_seconds/gauge

name=<application>"

11

Время нахождения событий реконсиляции в рабочей очереди запросов

Отображает, как долго события реконсиляции находятся в рабочей очереди, прежде чем будут обработаны контроллером

workqueue_queue_duration_seconds_bucket/histogram

name=<application>"
le=<[0.5, 5, 10]>

12

Количество HTTP запросов

Количество HTTP-запросов, разделенных по статусу, методу и хосту

rest_client_requests_total/counter

code=<код статуса>"
method=<метод запроса>
host=<host запроса>

13

Общее количество повторных попыток

Общее количество повторных попыток, обработанных очередью

workqueue_retries_total/counter

name=<application>"

14

Продолжительность незавершенных операций обработки

Отображает продолжительность незавершенных операций обработки, большие значения - индикатор наличия зависших потоков

workqueue_unfinished_work_seconds/counter

name=<application>"

15

Обработка элемента из рабочей очереди

Отображает, сколько времени занимает обработка элемента из очереди в секундах

workqueue_work_duration_seconds_bucket/histogram

name=<application>"
le=<[0.5, 5, 10]>

16

Количество запущенных job

Отображает общее количество запущенных job

ahac_job_launch_total/counter

17

Количество ошибочных сертификатов

Отображает количество ошибочных сертификатов

certwatcher_read_certificate_errors_total/counter

18

Количество прочитанных сертификатов

Отображает количество прочитанных сертификатов

certwatcher_read_certificate_total/counter

19

Общее количество обработанных событий изменения Application

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

controller_runtime_reconcile_total/counter

controller=<application>"
result=<[error, requeue, requeue_after, success]>

20

Этап жизненного цикла интеграции

Отображает текущий этап жц интеграции

ahac_app_info/gauge

name=<имя application>"
namespace="<Проект установки Application>"
status="<статус обработки Application>"
status="<статус>"
version="<версия Application>"

21

Общее количество событий обработки Application

Общее количество событий обработки Application у контроллера

ahac_reconciliation_count_total/counter

namespace="<Проект установки Application>"
status="<статус обработки Application>"

Список основных Go runtime метрик приведен в таблице:

№

Метрика

Описание

Показатель/Тип

Измерение

1

Продолжительность паузы сборки мусора

Суммарная продолжительность паузы циклов сборки мусора

go_gc_duration_seconds/summary

quantile [0, 0.25, 0.5, 0.75, 1]

2

Количество Goroutines

Количество существующих в настоящее время Goroutines

go_goroutines/gauge

3

Информация

Информация о среде Go

go_info/gauge

version="<номер версии>"

4

Выделено байтов

Количество выделенных и все еще используемых байтов

go_memstats_alloc_bytes/gauge

5

Общее количество выделенных байтов

Общее количество выделенных байтов, даже если они были освобождены

go_memstats_alloc_bytes_total/counter

6

Число байтов хеш-таблицы

Число байтов, используемых хеш-таблицей сегмента профилирования

go_memstats_buck_hash_sys_bytes/gauge

7

Высвобождения

Общее количество высвобождений

go_memstats_frees_total/counter

8

Количество байтов системы сбора мусора

Количество байтов, используемых для метаданных системы сбора мусора

go_memstats_gc_sys_bytes/gauge

9

Количество выделенных байтов heap

Количество байтов heap, выделенных и все еще используемых

go_memstats_heap_alloc_bytes/gauge

10

Количество ожидающих байтов heap

Количество байтов heap, ожидающих использования

go_memstats_heap_idle_bytes/gauge

11

Количество используемых байтов heap

Количество байтов heap, которые используются

go_memstats_heap_inuse_bytes/gauge

12

Количество объектов

Количество выделенных объектов

go_memstats_heap_objects/gauge

13

Количество возвращенных байтов heap

Количество байтов heap, возвращенных ОС

go_memstats_heap_released_bytes/gauge

14

Количество байтов heap

Количество байтов heap, полученных от системы

go_memstats_heap_sys_bytes/gauge

15

Время последней сборки мусора

Количество секунд с 1970 года до последней сборки мусора

go_memstats_last_gc_time_seconds/gauge

16

Количество операций поиска

Общее количество операций поиска указателя

go_memstats_lookups_total/counter

17

Количество выделений памяти

Общее количество выделений памяти (malloc)

go_memstats_mallocs_total/counter

18

Количество используемых байтов mcache

Количество байтов, используемых структурами mcache

go_memstats_mcache_inuse_bytes/gauge

19

Количество полученных байтов mcache

Количество байтов, используемых для структур mcache, полученных из системы

go_memstats_mcache_sys_bytes/gauge

20

Количество используемых байтов mspan

Количество байтов, используемых структурами mspan

go_memstats_mspan_inuse_bytes/gauge

21

Количество полученных байтов mspan

Количество байтов, используемых для структур mspan, полученных из системы

go_memstats_mspan_sys_bytes/gauge

22

Следующая сборка мусора

Количество байтов heap, когда будет происходить следующая сборка мусора

go_memstats_next_gc_bytes/gauge

23

Другие системные распределения

Количество байтов, используемых для других системных распределений

go_memstats_other_sys_bytes/gauge

24

Количество байтов стека

Количество байтов, используемых распределителем стека

go_memstats_stack_inuse_bytes/gauge

25

Количество байтов системы для распределителя стека

Количество байтов, полученных от системы для распределителя стека

go_memstats_stack_sys_bytes/gauge

26

Количество байтов системы

Количество байтов, полученных от системы

go_memstats_sys_bytes/gauge

27

Количество потоков

Количество созданных потоков ОС

go_threads/gauge

28

Версия компонента

Версия выводится в измерении

ahac_version/counter

version=<номер версии>

29

Общее процессорное время

Общее пользовательское и системное процессорное время, в секундах

process_cpu_seconds_total/counter

30

Максимальное количество файлов

Максимальное количество открытых дескрипторов файлов

process_max_fds/gauge

31

Количество файлов

Количество открытых дескрипторов файлов

process_open_fds/gauge

32

Резидентная память

Размер резидентной памяти в байтах

process_resident_memory_bytes/gauge

33

Время начала процесса

Время начала процесса с unix-эпохи в секундах

process_start_time_seconds/gauge

34

Виртуальная память

Размер виртуальной памяти в байтах

process_virtual_memory_bytes/gauge

35

Доступная виртуальная память

Максимальный объем доступной виртуальной памяти в байтах

process_virtual_memory_max_bytes/gauge

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

Проблема

Влияние

Причина

Решение

Не стартует pod приложения

Блокирует развертывание приложений

Недостаточно ресурсов

Увеличьте limits/requests для приложения

Не стартует pod приложения

Блокирует развертывание приложений

Нет доступного узла для запуска

Зарегистрируйте обращение в поддержку инфраструктуры

Не стартует pod приложения

Блокирует развертывание приложений

Ошибка в конфигурации

Выгрузите лог, проведите анализ, скорректируйте конфигурацию

Частый рестарт контейнера приложения

Сбои при развертывании приложений

Медленная загрузка приложения

Увеличьте задержку и/или интервал опроса Liveness пробы

Частый рестарт контейнера приложения

Сбои при развертывании приложений

Недостаточно ресурсов

Увеличьте limits/requests для приложения

Application не обрабатывается, поле статус не обновляется

Блокирует развертывание приложений

Отсутствует метка synapse.sber/cpref

Проверьте, есть ли в описании namespace, в котором установлен Application, метка, указанная в настройках как индикатор прослушиваемого пространства имён - настройка handlingNamespaceLabelSelector в конфигурации AHAC. Для проверки выполните команду: kubectl get ns

Application не обрабатывается, поле статус не обновляется

Блокирует развертывание приложений

App Hub Application Controller (AHAC) не запущен

Выполните команду: kubectl get deploy <имя артефакта развёртывания> -n для проверки

Application не обрабатывается, поле статус не обновляется

Блокирует развертывание приложений

Поле статус в Application не обновляется

Выполните команду kubectl logs -f -p <имя пода> -n , если информации недостаточно

Application не обрабатывается, поле статус не обновляется

Блокирует развертывание приложений

Job обработки Application не запустилась

Проверьте события (Events) Job командой: kubectl describe <имя Job из логов AHAC>

Поле status статуса Application имеет значение failed и поле message содержит информацию об ошибке

Блокирует развертывание приложений

Ошибка установки интеграции

Изучите поля message и lastLogs в Application, если логов в Application нет, просмотрите логи Job, указанной в status.jobName

Поле status статуса Application имеет значение failed и поле message содержит информацию об ошибке

Сбои при развертывании приложений

Ошибка Not found 404 при попытке загрузить чарт

Проверьте, есть ли helm чарт интеграции в OCI-Registry

Поле status статуса Application имеет значение failed и поле message содержит информацию об ошибке

Сбои при развертывании приложений

Ошибка Not available 403 в OCI-Registry при попытке загрузить чарт

Проверьте доступность реджестри и наличие ServiceEntry в namespace AHAC

Поле status статуса Application имеет значение failed и поле message содержит информацию об ошибке

Сбои при развертывании приложений

Ошибка Unauthorized 401 при попытке загрузить чарт

Убедитесь, что созданы и правильно настроены Secret image-pull-secret и Secret repositories в namespace AHAC, image-pull-secret привязан к ServiceAccount, используемому AHAC

Поле status статуса Application имеет значение failed и поле message содержит информацию об ошибке

Сбои при развертывании приложений

Ошибка валидации по схеме

Проверьте параметры конфигурации у компонентов в Application в поле values. Параметры могут не удовлетворять требованиям схемы используемых версий чартов устанавливаемых компонентов. В status.message Application отражено, какие именно параметры не соответствуют схеме

Поле status статуса Application имеет значение failed и поле message содержит информацию об ошибке

Сбои при развертывании приложений

Недостаточно прав для работы с требуемым ресурсом

Убедитесь, что для ServiceAccount Application Installer установлены требуемые права Role и RoleBinding, при необходимости скорректируйте