Руководство по установке#

В руководстве приведены инструкции по установке компонента Synapse Ansible Provider (SYAP).

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

Системные требования#

Для выполнения установки программного компонента (SYAP) должны быть выполнены следующие условия:

1. Развернут и настроен кластер Kubernetes версии 1.19 или выше в соответствии с требованиями, предъявляемыми к Платформе;

2. В кластере создан проект («Namespace»), в котором установлена контрольная панель (POLM);

3. Кластер Kubernetes использует etcd в качестве основного хранилища всех данных, установка, обновление и откат данной базы данных предоставляет сама платформа Kubernetes;

4. Подключен и настроен компонент SMDL (в случае автоматизированной установки);

5. В проекте создана учетная запись с правами на загрузку артефактов;

6. В проекте имеются свободные ресурсы по limits и requests не менее, чем зарезервировано в конфигурационных артефактах;

7. В проект добавлен секрет для загрузки Docker-образов из целевого Docker-репозитория;

8. В кластере создан проект (namespace), где будут реализован компонент SYAP;

9. В рамках реализованного проекта созданы необходимые роли (kind:Role/kind: ClusterRole) и привязки к ролям (kind: RoleBinding/kind: ClusterRoleBinding), в рамках ролевой модели компонента SYAP;

10. В рамках кластера реализованы необходимые ресурсы kind: CustomResourceDefinitions;

11. Для установки через консоль на рабочем месте должен быть установлен клиент Kubectl (CLI - command-line interface).

Для установки модуля компонента SYAP в среде контейнеризации Kubernetes – рекомендуется устанавливать приложения в рамках одного Pod. Приложения компонента не требуют дополнительной настройки окружения. Все настройки идут на уровне кластера в рамках среды контейнеризации.

Для возможности ручной установки, убедиться, что в рамках персонального компьютера установлен Helm версии не ниже 3.0.

Настройки безопасности окружения и перечень платформенных (дополнительных внешних) продуктов, используемых для установки, настройки и контроля в конечной информационной системе (далее — ИС), выбираются клиентом при разработке конечной ИС, исходя из характера обрабатываемой в ней информации и иных требований информационной безопасности (далее — ИБ), предъявляемых к ней. Рекомендуемые настройки безопасности окружения приведены в разделе «Подготовка окружения» данного документа.

Системное программное обеспечение#

Ниже представлены категории системного программного обеспечения (далее — ПО), которые обязательны или опциональны для установки, настройки, контроля и функционирования компонента. В каждой категории перечислены все поддерживаемые продукты сторонних правообладателей. Отдельно обозначены варианты, которые рекомендует АО «СберТех» (маркировка «Рекомендовано» в столбце «Продукт, функциональная совместимость с которым подтверждена»). Клиенту необходимо выбрать один из продуктов в каждой категории, исходя из условий использования конечной ИС.

Примечание:

*

• Да — категория ПО обязательна для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данной категории ПО)

• Нет — категория ПО необязательна для функционирования сервиса (это означает, что сервис может выполнять свои основные функции без установки данной категории ПО)

**

• Рекомендовано — рекомендованный правообладателем АО «СберТех» продукт

• Опционально — альтернативный по отношению к рекомендованному правообладателем АО «СберТех» продукт

Платформенные зависимости#

Для настройки, контроля и функционирования компонента реализована интеграция с программными продуктами, правообладателем которых является АО «СберТех»:

Для настройки, контроля и функционирования компонента реализована интеграция с программными продуктами, правообладателем которых является АО «СберТех»:

***

• Да — компонент или продукт необходим для функционирования сервиса (это означает, что сервис не может выполнять свои основные функции без установки данного компонента)

• Нет — необязательный для функционирования сервиса компонент или продукт (это означает, что сервис может выполнять свои основные функции без установки данного компонента)

**** Рекомендуется установка программного продукта, правообладателем которого является АО «СберТех», при этом не исключена возможность (допускается правообладателем) использования аналога других производителей. Аналоги, в отношении которых продукт успешно прошел испытания и подтвердил свою работоспособность, указаны в разделе «Системное программное обеспечение».

Аппаратные требования#

Для установки компонента требуется следующая конфигурация аппаратного обеспечения:

Состав дистрибутива#

В рамках компонента SYAP предоставляется два архива.

Наименование артефакта в рамках поставки syap-bin-*.

Наименование артефакта в рамках поставки syap-cfg-*.

Выбор способа установки#

• Автоматизированная (целевая) установка компонента с использованием Jenkins Job из дистрибутива компонента SMDL, SynapseInstaller (более подробно о настройке и запуске можно ознакомиться в документации компонента SMDL, «Руководство оператора»);

• Ручная (опционально) установка компонента с использованием менеджера пакетов HELM.

Подготовка окружения#

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

Пререквизиты:

• Базовый образ для сборки Docker image загружен в Docker Registry.

Если базовый образ был предоставлен в виде архива, то загрузить его в ваш реестр образов можно следующими командами:

1. Загрузка образа из архива в локальный реестр образов:

   docker load -i <архив_с_образом>
   

2. Если требуется изменить tag загруженного из архива образа:

   docker tag <старый_tag> <новый_tag>
   

3. Загрузка образа в реестр образов:

   docker push <tag>
   

В рамках предоставляемого дистрибутива реализованы все необходимые ресурсы для успешного функционирования компонента SYAP, кроме административных ресурсов кластера описанных в данном разделе.

1. Ресурсы в рамках ролевой модели (kind: Role/kind: ClusterRole/kind: RoleBinding/kind: ClusterRoleBinding/kind: ServiceAccount)

2. Ресурсы в рамках используемых конфигураций (kind: CustomResourceDefinitions)

Установку ресурсов выполнить через CLI Kubectl

Перед запуском заполните параметры, где будет установлен компонент SYAP, следующей командой:

SYAP_NAMESPACE=<имя namespace>

Установка CRD

Конфигурации присутствуют в рамках дистрибутива с конфигурациями развертывания (syap-cfg - ./conf/helm/application/syap-base).

Установка ClusterRole

Команда:

kubectl apply -n $SYAP_NAMESPACE -f - <<EOF

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: provider-ansible
rules:
  - verbs:
      - get
      - list
      - watch
      - update
      - patch
    apiGroups:
      - ansible.crossplane.io
    resources:
      - ansibleruns
      - providerconfigs
      - providerconfigusages
  - verbs:
      - update
    apiGroups:
      - ansible.crossplane.io
    resources:
      - ansibleruns/finalizers
      - ansibleruns/status
      - providerconfigs/finalizers
      - providerconfigs/status
  - verbs:
      - create
      - delete
    apiGroups:
      - ansible.crossplane.io
    resources:
      - providerconfigusages
  - verbs:
      - watch
      - list
      - get
      - update
      - patch
      - create
    apiGroups:
      - ''
    resources:
      - secrets
  - verbs:
      - list
      - get
      - update
      - create
      - delete
    apiGroups:
      - ''
    resources:
      - services
  - verbs:
      - create
      - patch
    apiGroups:
      - ''
    resources:
      - events
  - verbs:
      - list
      - get
      - update
      - create
      - delete
    apiGroups:
      - networking.istio.io
    resources:
      - virtualservices
      - destinationrules
      - serviceentries
      - gateways

Установка ClusterRoleBinding

Команда:

kubectl apply -n $SYAP_NAMESPACE -f - <<EOF

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: provider-ansible
subjects:
  - kind: ServiceAccount
    name: {{ .Values.serviceaccountname }}
    namespace: {{ .Release.Namespace }}
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: {{ .Values.clusterrolename}}

EOF

Ручная подготовка окружения#

Автоматизированная подготовка окружения#

Для сборки образа рекомендуем использовать инструмент автоматической сборки образа, компонента SMDL, ClientUnpacker (более подробно о настройке и запуске можно ознакомиться в документации компонента SMDL, «Руководство оператора»), результатом исполнения будет собранный образ приложений.

Для компонента SYAP необходимо провести дополнительные шаги для корректного формирования конфигураций по установке.

При первом запуске Jenkins Job ClientUnpacker необходимо проверить файл JSON teamProducts.json (указанный файл формируется при установке SMDL, полный путь к файлу ${имя репозитория}/resources/custom/additionalFiles/teamProducts.json):

{
  "name": "Synapse Ansible Provider",
  "code": "SYAP",
  "parts": [
    {
      "docker": [
        {
          "baseImageLink": "base_image",
          "version": "$VERSION",
          "deploymentUnit": "provider-controller"
        }
      ],
      "artifactId": "syap-bin"
    },
    {
      "artifactId": "syap-cfg",
      "imageLinkMapping": [
        {
          "regex": "\\{\\{ \\.Values\\.registry \\}\\}\\{\\{ \\.Values\\.registry_path \\}\\}provider-controller@sha256:(?<hash>\\w+)"
        }
      ]
    }
  ],
  "to": {
    "ci": "ci"
  }
}

Запустить инструмент автоматической сборки продукта SSM, компонента SMDL, ClientUnpacker (более подробно о настройке и запуске можно ознакомиться в документации компонента SMDL, «Руководство оператора»), результатом исполнения будет собранные артефакты для установки приложения (на email сотрудника, кто запустил Jenkins Job, придет таблица со ссылками на артефакты);

Провести проверку корректной подстановки образов в конфигурации. Для этого необходимо загрузить артефакты, которые относятся к компоненту SYAP по ссылкам из таблицы.

### в рамках приложения Ansible provider располагаются общие конфигурации по установке
### путь к конфигурационному файлу «./conf/helm/application/syap/templates/deployment.yaml» (артефакт «syap-cfg-*»)
### провески поиск по ключу «image» 

      - image: your.registry/*/provider-controller@sha256:******                                          # пример корректной подстановки образа для компонента ansible provider

При возникновении сложностей с подстановкой образа, допускается произвести ручное добавление корректных образов приложения, которые формируются после запуска Jenkins Job ClientUnpacker.

Установка#

Перед началом установки убедитесь, что выполнена подготовка окружения. Убедиться что в рамках персонального компьютера установлен Helm версии не ниже 3.0.

Ручная установка сервиса#

1. Загрузить артефакт компонента SYAP с конфигурациями для установки (syap-cfg-*);

2. При необходимости провести корректировку конфигураций, располагаемых в каталоге ./conf/helm/application/syap/templates/* (например провести подстановку image приложения);

3. Перейти в рамках терминала в каталог ./conf/helm/;

4. Провести авторизацию через терминал в кластер, где планируется установка компонента SYAP (пример для Openshift oc login --token=$ТОКЕН --server=$АДРЕС_КЛАСТЕРА);

5. Пройти в Namespace (проект), где планируется установка компонента SYAP (пример для Openshift oc project provider-ansible);

6. Провести заполнение файла ./conf/helm/application/syap/values.yaml (описание параметров указана в указанном документе, раздел «Автоматическая установка сервиса»);

7. Провести установку Helm Chart syap-base - helm install syap-base;

8. Провести установку компонента SYAP - helm install syap --values values.yaml.

Автоматическая установка сервиса#

SYOP#

Для установки SYAP необходимо ознакомиться с соответствующей инструкцией в документации SYOP (документ «Руководство по системному администрированию», раздел «Руководство по установке компонента SYAP»)

SMDL#

Достаточно использовать конфигурации развертывания из дистрибутива приложения syap-cfg-*.

Заполнить стендозависимые параметры для установки компонента SYAP, пример:

### Необходимо реализовать файл values.yaml
### Расположение файла в рамках git ветки job SynapseInstaller (более подробно о настройке и запуске можно ознакомиться в документации компонента SMDL, «Руководство оператора»)
### Для компонента SYAP - synapse-config-dev-gen/${{имя кластера для установки/имя проекта для установки}} или {имя проекта для установки}}/package/conf/helm/application/syap/values.yaml

values.yaml

clusterrolename: provider-ansible # наименование kind:ClusterRole
clusterrolebinding: provider-ansible # наименование kind:ClusterRoleBinding
serviceaccountname: provider-ansible-service-account # наименование kind:ServiceAccount
registryHost: host # ссылка на Host registry
registry_path: pathToImage # путь до образа
seccompProfile: false # флаг установки параметра seccompProfile в секции securityContext у «kind: Deployment» (указанный параметр поддерживается в Kubernetes версии 1.25 и выше)
pullsecretname: default # наименование **kind: Secret** для pull образов
projectedKubeAPI: false  # флаг монтирования токена для работы с KubeAPI, если стоит значение false, то токен будет примонитирован автоматически, если true то токен будет примонтирован в рамках Deployment
affinity: true # флаг установки podAntiAffinity с конкретизацией метки (label) при установке на Node
enabledPriorityClassName: false # флаг установки параметра PriorityClassName в рамках «kind: Deployment»
priorityClassName: system-cluster-critical # значение параметра PriorityClassName в рамках «kind: Deployment» 
package: # блок настроек для контейнейров
   controller:
      replicas: 1 # количество реплик
      probes:
         liveness: # параметры livenessProbe контейнера SYAP
            initialDelaySeconds: 5
            timeoutSeconds: 5
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
         readiness: # параметры readinessProbe контейнера SYAP
            initialDelaySeconds: 5
            timeoutSeconds: 1
            periodSeconds: 30
            successThreshold: 1
            failureThreshold: 3
      resources:
         limits:
            cpu: 300m # ресурсы limits/cpu приложения SYAP
            memory: 300Mi # ресурсы limits/memory приложения SYAP
         requests:
            cpu: 200m # ресурсы requests/cpu приложения SYAP
            memory: 200Mi # ресурсы requests/memory приложения SYAP
      strategy:
         rollingParams:
            maxSurge: 25%                               # установка параметра maxSurge в рамках «kind: Deployment»
            maxUnavailable: 25%                          # установка параметра maxUnavailable в рамках «kind: Deployment»
   svpx:
      resources:
        limits:
          cpu: 300m                                    # ресурсы limits/cpu приложения SVPX в Pod компонента SYAP
          memory: 300Mi                                # ресурсы limits/memory приложения SVPX в Pod компонента SYAP
        requests:
          cpu: 300m                                    # ресурсы requests/cpu приложения SVPX в Pod компонента SYAP
          memory: 300Mi                                # ресурсы requests/memory приложения SVPX в Pod компонента SYAP
   egress:
      replicas: 1 # количество реплик IGEG (egressgateway)
      certs: # монтируемые сертификаты
         - name: syap-egress # имя монтируемого volume
           secretName: syap-egress # наименование секрета
           mountPath: sberworks-ca.crt # наименование поля в секрете и наименование файла, в которое сохранить содержимое
      probes:
         readiness: # параметры readinessProbe контейнера IGEG (egressgateway)
          failureThreshold: 30
          initialDelaySeconds: 5
          periodSeconds: 5
          successThreshold: 1
          timeoutSeconds: 1
      resources:
         limits:
            cpu: 300m                                    # ресурсы limits/cpu приложения IGEG (egressgateway)
            memory: 500Mi                                # ресурсы limits/memory приложения IGEG (egressgateway)
         requests:
            cpu: 300m                                    # ресурсы requests/cpu приложения IGEG (egressgateway)
            memory: 500Mi                                # ресурсы requests/memory приложения IGEG (egressgateway)
ansible_dir_limit: 500Mi # размер для директории /ansibleDir
ansibledir_dir_limit: 500Mi # размер для директории /.ansible
syap_config:
   debug: false # флаг включения режима логирования уровня 'debug' при старте приложения
   syncTime: 1h # интервал полной обработки всех crd SYAP
   ansibleProcessTimeout: 20m # время отводимое под Ansible процесс. При его истечении срабатывает sigterm
   istioCreateTimeout: 40 # количество секунд ожидания получения доступа к внешнему серверу после создания Istio конфигураций
   leaderElection: false # параметр leaderElection syap controller
   maxReconcileRate: 1 # параметр максимального количества потоков обработки конфигураций syap
   artifactsHistoryLimit: 10 # параметр количества хранимых артефактов после работы ansible
   metricsAddress: ':8080' # параметр порта для метрик
   apiVersionIstio: 'networking.istio.io/v1beta1' # apiVersion конфигураций Istio
   pollInterval: 1m # время между опросами индивидуального ресурса SYAP
igeg:
   enable: true # включение интеграции syap с Istio/POLM
   kubeEgressRouting: TLS  # реализация конфигураций Istio (TLS перехват трафика в рамках tls, TCP перехват трафика по tcp)
   kubeAPIIP: '*.*.*.*'    # IP-адрес сервиса KubeAPI (kubernetes.default.svc.cluster.local)    
   kubePort: 443           # Port сервиса KubeAPI (kubernetes.default.svc.cluster.local), параметр указывается при установке в Kubernetes кластер (k8s: true)
   kubeAPIResolution: STATIC      # resolution в рамках реализации конфигурации «kind: ServiceEntry» по host Kube API server
   istioControlPlane: sb-controlplane   # наименование namespace контрольной панели, к которой подключен namespace компонента SYAP
   serviceIstiod: istiod-basic    # наименование сервиса контрольной панели, компонента «istiod»
   image:   # ссылка на актуальный образ приложения IGEG
   add_credential_mount: false
k8s: true # Флаг, указывающий устанавливается ли SYAP в систему оркестрации k8s
hash: sha256:bd3244ea531185a7f64a1be6bdc5a917998c2d7eceecf313f9d946368b110865 # sha256 образа приложения SYAP

Запустить Jenkins Job, компонент SMDL, SynapseInstaller (более подробно о настройке и запуске можно ознакомиться в документации компонента SMDL, «Руководство оператора»)

Обновление#

Перед обновлением компоненты SYAP не требуется делать бэкап etcd. Конфигурации kind: AnsibleRun/kind: ProviderConfig останутся в кластере.

Для обновления SYAP в проекте требуется:

1. Загрузить артефакт компонента SYAP с конфигурациями для установки (syap-cfg-*);

2. При необходимости провести корректировку конфигураций, располагаемых в каталоге ./conf/helm/application/syap/templates/* (например провести подстановку image приложения);

3. Перейти в рамках терминала в каталог ./conf/helm/application;

4. Провести авторизацию через терминал в кластер, где планируется установка компонента SYAP (пример для Openshift oc login --token=$ТОКЕН --server=$АДРЕС_КЛАСТЕРА);

5. Пройти в Namespace (проект), где планируется установка компонента SYAP (пример для Openshift oc project provider-ansible);

6. Провести заполнение файла ./conf/helm/application/syap/values.yaml (описание параметров указана в указанном документе, раздел «Автоматическая установка сервиса»);

7. Провести обновление syap-base посредством команды обновление Helm Chart helm upgrade syap-base --values values.yaml.

8. Провести обновление SYAP посредством команды обновления Helm Chart helm upgrade syap --values values.yaml.

Удаление#

Подключиться к проекту#

• Через CLI Kubectl

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

• Через CLI Kubectl

Удалить артефакты действующей версии#

• Через CLI Kubectl

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

SYAP#

Также проверить отсутствие ошибок в рамках логов приложения (документ «Руководство по системному администрированию», раздел «Выгрузка системных логов»).

Проверка работоспособности всех интеграций производится на стороне приложений, с которыми приложения SYAP взаимодействуют, подробнее описание можно найти в документации таких приложений (IGEG, SVPX, DropAPP, POLM).

При установке SYAP посредством компонентов SMDL, SYOP фактом, подтверждающим работоспособность данных компонентов, будет являться успешная установка всех необходимых пользователю приложений в рамках SYAP.

Откат#

Перед откатом компоненты SYAP на предыдущую версию не требуется делать бэкап etcd. Конфигурации kind: AnsibleRun/kind: ProviderConfig останутся в кластере.

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

• Через CLI Kubectl

Удалить артефакты действующей версии#

• Через CLI Kubectl

Загрузить сохраненные артефакты#

• Через CLI Kubectl

Запустить восстановленную версию компонента#

• Через CLI Kubectl

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

Чек-лист валидации установки#