Руководство по установке#
В руководстве приведены инструкции по установке компонента App Hub Application Controller, (AHAC).
Термины и определения#
Термин/Аббревиатура |
Определение |
|---|---|
ИФТ |
Интеграционно-функциональное тестирование |
Граничный прокси / IGEG / egressgateway |
Компонент Граничный прокси продукта Platform V Synapse Service Mesh |
SYOP |
Программный компонент Synapse Operator (SYOP) из состава программного продукта Platform V Synapse Service Mesh (код SSM) |
Системные требования#
Настройки безопасности окружения и перечень платформенных (дополнительных внешних) продуктов, используемых для установки, настройки и контроля в конечной информационной системе (далее — ИС), выбираются клиентом при разработке конечной ИС, исходя из характера обрабатываемой в ней информации и иных требований информационной безопасности (далее — ИБ), предъявляемых к ней.
Системное программное обеспечение#
Ниже представлены категории системного программного обеспечения (далее — ПО), которые обязательны или опциональны для установки, настройки, контроля и функционирования компонента. В каждой категории перечислены все поддерживаемые продукты сторонних правообладателей. Отдельно обозначены варианты, которые рекомендует АО «СберТех» (маркировка «Рекомендовано» в столбце «Продукт, функциональная совместимость с которым подтверждена»). Клиенту необходимо выбрать один из продуктов в каждой категории, исходя из условий использования конечной ИС.
Категория ПО |
Обязательность установки (Да/Нет) |
Наименование ПО |
Версия |
Продукт, функциональная совместимость с которым подтверждена |
Описание |
|---|---|---|---|---|---|
Среда контейнеризации |
Да |
1.25.3 |
Рекомендовано. Правообладателем АО «СберТех» также рекомендована среда контейнеризации – Platform V DropApp, см. раздел «Платформенные зависимости» |
Платформа контейнеризации для запуска компонентов сервиса |
|
Консольная утилита управления |
Да |
kubectl |
1.22.4 |
Рекомендовано |
Инструмент для управления экземплярами |
Средство контейнеризации |
Да |
1.13.1 |
Рекомендовано |
Инструмент для автоматизации работы с контейнерами |
|
Инструмент развертывания контейнеризированных приложений |
Да |
Helm |
3.14.0 |
Рекомендовано |
Инструмент развертывания контейнеризированных приложений |
Инструмент сборки, тестирования, развертывания контейнеризированных приложений |
Нет |
2.357 |
Сервер автоматизации, используемый для внедрения непрерывной интеграции и непрерывной доставки (CI/CD) для проектов программного обеспечения |
||
Сервис централизованного хранения репозиториев артефактов (хранилище артефактов) |
Да |
3.42.0 |
Рекомендовано |
Интегрированная платформа для проксирования, хранения и управления зависимостями Java (Maven), образами, а также распространения ПО |
|
Сервис централизованного хранения репозиториев исходного кода |
Да |
Bitbucket |
7.6.7 |
Опционально |
Хранение конфигураций при автоматизированной установке |
Оператор по установке приложений |
Нет |
Platform V Synapse Service Mesh (SSM) 1.0 и выше (synapse operator (SYOP)) |
1.0 |
Опционально |
Программный компонент предназначен для установки Helm Charts других компонентов, входящих в состав SYOP |
Примечание:
*
Да — категория ПО обязательна для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данной категории ПО).
Нет — категория ПО необязательна для функционирования сервиса (это означает, что сервис может выполнять свои основные функции без установки данной категории ПО).
**
Рекомендовано — рекомендованный правообладателем АО «СберТех» продукт.
Опционально — альтернативный по отношению к рекомендованному правообладателем АО «СберТех» продукт.
Платформенные зависимости#
Для настройки, контроля и функционирования компонента реализована интеграция с программными продуктами, правообладателем которых является АО «СберТех»:
Наименование продукта |
Код |
Версия продукта |
Код и наименование компонента |
Обязательность установки (Да/Нет) |
Описание |
Аналог других производителей |
|---|---|---|---|---|---|---|
Platform V SberLinux OS Server |
SLO |
8.7 |
INST Операционная система |
Да |
ОС контейнеров для запуска модулей компонента |
ОС Альт 8 СП |
Platform V DropApp |
K8S |
1.1 и выше |
K8SC K8S Core |
Да |
Дистрибутив Kubernetes со встроенными механизмами мультитенантности и бессерверным исполнением |
Kubernetes, Red Hat OpenShift Container Platform |
Platform V Synapse Service Mesh |
SSM |
4.2 и выше |
IGEG Граничный прокси |
Нет |
Сервис для обеспечения управляемого сетевого взаимодействия сервисов |
Istio proxy 1.12 |
Примечание:
***
Да — компонент или продукт необходим для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данного компонента).
Нет — необязательный для функционирования сервиса компонент или продукт (это означает, что сервис может выполнять свои основные функции без установки данного компонента).
**** Рекомендуется установка программного продукта, правообладателем которого является АО
«СберТех», при этом не исключена возможность (допускается правообладателем) использования аналога
других производителей. Аналоги, в отношении которых продукт успешно прошел испытания и подтвердил
свою работоспособность, указаны в разделе «Системное программное обеспечение».
Аппаратные требования#
В рамках требований указан минимальный размер. Целевой размер определяется по результатам НТ отдельно под каждый интеграционный сценарий.
Для установки компонента требуется следующая конфигурация аппаратного обеспечения:
Тип среды |
Тип стенда |
Количество |
CPU (кол-во ядер) |
ОЗУ (ГБ) |
Внутренние диски (ГБ) |
Горизонтальное масштабирование |
|---|---|---|---|---|---|---|
DEV |
Конфигурация в среде контейнеризации (в рамках одного POD’а) |
1 |
200m |
256Mi |
- |
да |
НТ |
Конфигурация в среде контейнеризации (в рамках одного POD’а) |
1 |
500m |
500Mi |
- |
да |
ПСИ |
Конфигурация в среде контейнеризации (в рамках одного POD’а) |
1 |
300m |
512Mi |
- |
да |
ПРОМ |
Конфигурация в среде контейнеризации (в рамках одного POD’а) |
1 |
500m |
512Mi |
- |
да |
Выбор способа установки#
На данный момент поддерживаются следующие варианты установки:
Ручная установка.
Установка с SYOP (Synapse Operator).
Подготовка окружения#
Для установки компонента App Hub Application Controller, (AHAC) в составе прикладного дистрибутива должно быть выполнено следующее:
Развернут и настроен кластер Kubernetes версии, указанной в списке системного программного обеспечения, выше;
В кластере создан проект (namespace), в котором будет разворачиваться компонент App Hub Application Controller, (AHAC);
В проект добавлен Secret для загрузки Docker-образов из целевого Docker-репозитория;
В дефолтный Service Account проекта подключен секрет из п. 3;
Если необходимы дополнительные параметры авторизации в Docker-репозитории, в проект добавлен Secret с этими параметрами. Secret может включать в себя такие параметры, как URL репозитория, токены доступа, настройки прокси и другие параметры, необходимые для работы с репозиторием.
В проекте создана учетная запись с правами на загрузку артефактов;
Получена ссылка на целевой Docker-репозиторий;
Базовый образ для сборки Docker-образа загружен в целевой Docker-репозиторий;
Для ручной установки:
На рабочем месте должен быть установлен клиент Kubernetes (kubectl) версии, указанной в списке системного программного обеспечения, выше;
На рабочем месте должен быть установлен Helm версии, указанной в списке системного программного обеспечения, выше;
Для создания Docker-образа на рабочем месте должен быть установлен Docker версии, указанной в списке системного программного обеспечения, выше;
Для установки с использованием Synapse Operator (SYOP), SYOP должен быть развернут и настроен в соответствии с документацией компонента Synapse Operator (SYOP).
Перечень программных продуктов, используемых при установке:
Наименование |
Функции |
|---|---|
kubectl |
Подключение к проекту Kubernetes, загрузка артефактов конфигурации в проект Kubernetes в консольном режиме |
Docker |
Создание и размещение Docker-образа |
Helm |
Развертывание компонентов приложения в ручном режиме |
DevOps tools |
Развертывание компонентов приложения в автоматизированном режиме |
Установка#
Важно! Ручная корректировка конфигурационных файлов в процессе установки не требуется.
Состав дистрибутива#
Элемент дистрибутива |
Описание |
|---|---|
/package/docker/ahac/Dockerfile |
Файл инструкций для сборки образа компонента App Hub Application Controller, (AHAC) в Docker |
/package/bh/manager |
Исполняемый (бинарный) файл приложения компонента App Hub Application Controller, (AHAC) |
/package/bh/helm_installer |
Исполняемый (бинарный) файл приложения компонента Helm Installer, (AHHI) |
/package/ReleaseNotes.json |
Метаинформация по дистрибутиву, формируемая сборщиком дистрибутива |
/package/conf/ |
Конфигурация дистрибутива, включая определение стендозависимых параметров и helm чарт |
Ручная установка компонента App Hub Application Controller, (AHAC)#
Перед началом установки убедитесь, что выполнена подготовка окружения.
Для ручной установки компонента выполните следующие действия:
Настройте контекст#
Порядок действий по настройке приведен в таблице ниже.
Шаг |
Действия |
Описание |
|---|---|---|
Создайте запись о пользователе в kubeconfig |
- Если подключение выполняется с использованием встроенных в Kubernetes учетных записей (Service Account), то выполните команду: |
токен_пользователя для подключения получите у администраторов кластера |
Создайте запись о кластере в kubeconfig |
- Если подключение к кластеру выполняется напрямую, то выполните команду: |
Параметры подключения получите у администраторов кластера. |
Создайте контекст в kubeconfig |
- Создайте контекст, под которым будет происходить подключение к кластеру |
Соберите и опубликуйте Docker-образ компонента App Hub Application Controller, (AHAC) из дистрибутива#
Порядок действий приведен в таблице ниже.
Шаг |
Действия |
Описание |
|---|---|---|
Распакуйте дистрибутив |
Загрузите owned-дистрибутив. |
|
Соберите Docker-образ |
Перейдите в терминале в директорию package дистрибутива owned |
Параметры подключения получите у администраторов Docker-репозитория. |
Опубликуйте Docker-образ |
Авторизуйтесь в Docker-репозитории командой: |
Соберите и опубликуйте Docker-образ компонента App Hub Application Controller, (AHHI) из дистрибутива#
Порядок действий приведен в таблице ниже.
Шаг |
Действия |
Описание |
|---|---|---|
Распакуйте дистрибутив |
Загрузите owned-дистрибутив. |
|
Соберите Docker-образ |
Перейдите в терминале в директорию package дистрибутива owned |
Параметры подключения получите у администраторов Docker-репозитория. |
Опубликуйте Docker-образ |
Авторизуйтесь в Docker-репозитории командой: |
Описание параметров чарта для установки#
values.yaml
registry: test_registry # имя репозитория, где хранятся образы контейнеров
registry_path: /test # путь к образу контейнера в репозитории
sha256: sha256:test # хеш-значение образа контейнера, используемого для определения его версии
registry_path_installer: /test_installer # путь к образу установщика (Installer) в репозитории
sha256_installer: sha256:test # хеш-значение образа установщика, используемого для проверки его целостности
# конфигурация образа для istio esgess, обязательны при istio.egress.enabled: true
registry_path_istio: #путь к образу istio в репозитории
sha256_istio: #хеш-значение образа istio, используемого для определения его версии
pullPolicy: Always #политика для обновления образов контейнеров
imagePullSecrets: [] #секреты для доступа к репозиторию
nameOverride: "" #переопределение имени приложения
fullnameOverride: "" #переопределение полного имени приложения
global: #глобальные настройки для установки.
meshId: #уникальный идентификатор установки App Mesh
containerOrchestrationSystem: k8s #система оркестрации контейнеров (k8s - kubernetes | ose - OpenShift)
service: #настройки для сервиса
port: 8081
type: ClusterIP #тип сервиса, например, ClusterIP, NodePort или LoadBalancer
registryAuth: #настройки для аутентификации в репозитории
# Секрет для installer
name: "pull-secret" #имя секрета для доступа к репозиторию
create: false #указывает, нужно ли создавать новый секрет для доступа к репозиторию
secret: #содержит данные .dockerconfigjson для авторизации в репозитории
.dockerconfigjson: ""
repository: #определяет параметры для Helm репозитория
name: "" #имя репозитория,
create: false #указывает, нужно ли создавать секрет для доступа к Helm репозиторий
secret: #содержит данные для доступа к репозиторию, такие как repository.yaml
repository.yaml: ""
synapseMetricsAnnotations: #определяет аннотации для сбора метрик Synapse-metrics
metrics.synapse.sber.path: /metrics #путь к метрикам Synapse.
metrics.synapse.sber.port: "8080" #порт, на котором будут работать метрики Synapse.
metrics.synapse.sber.scrape: "true" #указывает, нужно ли собирать метрики Synapse
installerServiceAccount: #определяет параметры ServiceAccount для сервиса Installer
create: true #указывает, нужно ли создавать ServiceAccount для Installer
name: "" #имя ServiceAccount для Installer, если значение не задано, то используется значение по умолчанию {{- default (printf "%s-installer" (include "ahac.fullname" .)) }}, если задана crate: false то значение по умолчанию: esb-installer-sa
serviceAccount: #параметры для ServiceAccount AHAC
create: true #указывает, нужно ли создавать ServiceAccount для AHAC
automount: true #указывает, нужно ли автоматически монтировать API-токен для ServiceAccount.
annotations: {} #аннотации, которые будут добавлены к ServiceAccount AHAC.
name: "" #имя ServiceAccount, если значение не задано, то используется значение по умолчанию {{- default (include "ahac.fullname" .) }}, если задана crate: false то значение по умолчанию: default
podAnnotations: #определяет аннотации для подов
sidecar.istio.io/inject: "true"
podLabels: #определяет метки для подов
sidecar.istio.io/inject: "true"
igegkubeApi: true #при значении настройки true, артефакты istio(DestinationRule,ServiceEntry и тд..) не создаются. Используется общий Egress проекта
#IGEG (egressgateway)
istio:
jwtPolicy: third-party-jwt #политика для проверки JWT-токенов
controlPlane: istio-se-system #имя Control plane Istio.
service: istiod-istio-se-system #имя сервиса Istio
accessPort: 4443 #виртуальный порт, используемый внутри маршрутизации Istio
egress:
enabled: true #использование egress. false выключает создание артефактов Istio и монтирование istio-proxy в контейнеры
registry:
hosts: #имена хостов репозиториев helm-чартов
- registry.host
- local.host
ports: #список портов, которые используются для доступа к репозиториям
- name: https
number: 443
protocol: TLS
resolution: DNS #используется для определения метода разрешения имен хостов Istio
kubeAPI:
address: { IP_ADDRESS } #ip-адрес API Kubernetes
host: kubernetes.default.svc.cluster.local #хост API Kubernetes.
port: 443 #порт API Kubernetes.
resolution: STATIC #режим разрешения API Kubernetes
protocol: TLS #протокол API Kubernetes
podSecurityContext: {} #параметры безопасности для подов
securityContext: {} #параметры безопасности для контейнеров
resources: {} #параметры ресурсов для контейнеров
config:
handlingNamespaceLabelSelector: #метка для выбора пространств имен для обработки Application. По умолчанию равно 'synapse.sber/cpref={{ .Values.global.meshId }}'
sidecarTerminationTimeout: 5s #определяет время ожидания завершения sidecar-контейнеров в Job Installer. По умолчанию значение sidecarTerminationTimeout равно "5s"
maxConcurrentReconciles: 1 #максимальное количество одновременных операций обработки Application. По умолчанию значение равно 1
gorutineCleanerLimit: 10 #максимальное количество одновременных операций очистки неактуальных релизов при перезапуске контроллера AHAC.
cacheSyncPeriod: 1s #время синхронизации кэша манифестов Application и Secret
skipDigestValidation: false #проверка контрольных сумм образов helm-чартов Application
recIdDisabled: false #отключение добавления аннотации для перезапуска подов, по умолчанию false
istioEnabledInInstaller: true #добавление istio-proxy в контейнер Installer
installJob: #параметры Installer Job
expectedWorkTime: "300s" #ожидаемое время работы Job, по умолчанию 300s
retryCount: 3 #количество попыток установки, по умолчанию 3
ttl: #настройки TTL для установки, включая Success, Failure и Default.
success: 1s #время жизни Job после успешного завершения установки
failure: 1h #время жизни Job после завершения установки с ошибкой
default: 1m #время жизни Job по умолчанию, до успешного или ошибочного статуса
authorizationSecretName: "" #имя секрета авторизации в репозитории helm-чартов
namespaceToStoreReleaseInfo: "application" #пространство имен для хранения информации о релизе, по умолчанию значение равно application
logging:
level: info #уровень логирования, по умолчанию info
console: #настройки консольного логирования
enabled: true #включение логирования в консоль. По умолчанию значение Enabled равно true
datetimeFormat: "2006-01-02 15:04:05.000000" #формат даты и времени для консольного логирования. По умолчанию значение DateTimeFormat равно "2006-01-02 15:04:05.000000"
file: #настройки логирования в файл.
enabled: false #включение логирования в файл
path: "/var/logs/ahac/application.log" #путь к файлу для логирования
dateTimeFormat: "2006-01-02 15:04:05.000000" #формат даты и времени для логирования.
mode: 0o644 #режим доступа к файлу
rotate: #настройки ротации логов
enabled: true #включение ротации файла логов. По умолчанию значение Enabled равно false
compress: false #сжатие файла лога при ротации
maxSize: "30MB" #максимальный размер файла лога перед ротацией. По умолчанию значение MaxSize равно 30MB
keepNumber: 3 #максимальное количество файлов архива лога. По умолчанию значение KeepNumber равно 3
keepAge: 2s #максимальный возраст файла лога перед ротацией
installers: #параметры для установщиков
helm:
args: #аргументы для Installer
- -l
- trace
resources: #ресурсы для Installer
requests:
memory: "250M"
cpu: "150m"
limits:
memory: "500M"
cpu: "400m"
labels: {} #метки для Job Installer
annotations: {} #аннотации Job Installer
image: test_image #образ Installer, формируется из настроек {{ $.Values.registry }}{{ $.Values.registry_path_installer }}@{{ $.Values.sha256_ahhi}}
role:
rules: #роли для Installer для переопределения значений по умолчанию
- verbs:
- create
- delete
- get
apiGroups:
- ""
resources:
- "*"
securityContexts: #настройки безопасности для контейнеров, включая RunAsUser, RunAsGroup и SeccompProfile
podSecurityContext:
fsGroup: 10001
seccompProfile:
type: RuntimeDefault
securityContext:
runAsUser: 10001
runAsGroup: 10001
seccompProfile:
type: RuntimeDefault
Установите компонент App Hub Application Controller, (AHAC) в целевой проект#
Порядок действий приведен в таблице ниже.
Шаг |
Действия |
Описание |
|---|---|---|
Распакуйте дистрибутив |
Загрузите owned-дистрибутив. |
|
Установите рабочий каталог |
откройте терминал, перейдите в каталог package (далее все ссылки приведены относительно этого каталога). |
|
Настройте стендозависимые параметры |
Скорректируйте файл |
Значения параметров получите у администратора кластера |
Выполните установку Custom Resource Definition |
Выполните установку Custom Resource Definition командой |
|
Выполните установку компонента App Hub Application Controller, (AHAC) |
Выполните установку компонента командой |
Установка компонента App Hub Application Controller (AHAC) с использованием Synapse Operator (SYOP)#
Описание установки с использованием Synapse Operator (SYOP) смотрите в документации компонента Synapse Operator (SYOP) в «Руководстве по системному администрированию», раздел Руководство по установке компонента AHAC.
Обновление#
Порядок действий приведен в таблице ниже.
Шаг |
Действия |
Описание |
|---|---|---|
Распакуйте дистрибутив |
Загрузите owned-дистрибутив. |
|
Установите рабочий каталог |
Откройте терминал, перейдите в каталог package (далее все ссылки приведены относительно этого каталога). |
|
Настройте стендозависимые параметры |
Скорректируйте файл |
Значения параметров получите у администратора кластера |
Выполните обновление Custom Resource Definition |
Выполните обновление Custom Resource Definition командой |
|
Выполните обновление компонента App Hub Application Controller, (AHAC) |
Выполните обновление компонента командой |
Откат#
Для отката на предыдущую версию AHAC необходимо выполнить команду
helm rollback имя_релиза
Удаление#
Для удаления компонента App Hub Application Controller, (AHAC) необходимо произвести удаление артефактов установленной версии командой:
helm uninstall имя_релиза
Проверка работоспособности#
Для быстрой проверки работоспособности запущенного приложения компонента App Hub Application Controller, (AHAC):
В интерфейсе Kubernetes, в терминале в Pod компонента App Hub Application Controller, (AHAC)
выполните команду curl localhost:<portnum>/readyz. В ответ должен быть получен код 200 и статус
OK, что подтверждает, что экземпляр компонента App Hub Application Controller, (AHAC) запустился и
готов к работе.
Чтобы выполнить эту же проверку с использованием kubectl:
В консоли выполните команду
kubectl --insecure-skip-tls-verify port-forward pod/<имя Pod> <portnum>:<portnum>. Kubectl перенаправит порт Pod компонента App Hub Application Controller, (AHAC) на соответствующий порт рабочего места.Запустите еще одно окно консоли, в нем выполнить команду:
curl localhost:<portnum>/readyz. В ответ должен быть получен код 200 и статус OK, что подтверждает, что экземпляр компонента App Hub Application Controller, (AHAC) запустился и готов к работе.Завершите проброс портов, для этого нажмите Ctrl+C. Перенаправление порта на рабочее место будет отменено.
Часто встречающиеся проблемы и пути их устранения#
Проблема |
Причина |
Решение |
|---|---|---|
Ошибка при подключении к проекту |
Пользователю не предоставлен доступ в проект |
Запросите доступ к проекту |
Ошибка при подключении к проекту |
Нет физического доступа к кластеру |
Зарегистрируйте обращение в поддержку для восстановления доступа |
Ошибка при загрузке артефактов |
У пользователя, под которым производится загрузка, отсутствуют необходимые права |
Проверьте и скорректируйте настройку прав доступа пользователю |
Ошибка при Pull Docker-образа из репозитория |
Отсутствуют права на Pull образа из репозитория |
Запросите права |
Ошибка при Pull Docker-образа из репозитория |
Недоступен репозиторий |
Зарегистрируйте обращение в поддержку для восстановления доступа |
Ошибка при Pull Docker-образа из репозитория |
Неверная ссылка на image в Deployment компонента App Hub Application Controller, (AHAC) |
Проверьте ссылку при необходимости скорректировать Deployment |
Чек-лист валидации установки#
Проверка |
Действия |
Результат |
|---|---|---|
Docker-образ опубликован в Docker-registry |
Найти Docker-образ по пути REGISTRY_URL/ + IMAGE_PATH/ + ARTIFACT_ID: + VERSION/ (см. пункт по сборке дистрибутива) |
Docker-образ найден по указанному пути |
Все артефакты загружены в проект |
По списку артефактов найти их в проекте Kubernetes командой |
Команда для каждого артефакта вернула его параметры |