Работа с дистрибутивом конфигураций на базе HELM#

Helm структурирует пакетные приложения в чарты (helm charts). В чартах содержится предустановленные ресурсы приложения вместе со всеми версиями, которые помещены в один пакет.

Чарты Helm - это пакеты Helm, состоящие из файлов, шаблонов YAML, которые преобразуются в манифесты Kubernetes.

Чарт — предварительно настроенный шаблон ресурсов Kubernetes.
Релиз — чарт, развернутый с помощью Helm в кластере Kubernetes.

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

charts/ - каталог для управляемых зависимостей чарта;
templates/- написанные на языке Go файлы шаблонов, объединенные со значениями конфигураций файлов values.yaml (именно они предназначены для генерации манифестов Kubernetes);
Chart.yaml - метаданные о чартах, такие как: версия, имена, ключевые слова для поиска и т.п.;
values-*.yaml - настройки чарта по умолчанию.

Структура каталога Helm в репозиториях#

В связи с тем, что желаемый результат внедрения helm - привести к общему знаменателю несколько проектов, а также, свести к минимуму различия в конфигурациях при работе с кластерами kubernetes, требуется разделить данные, которыми можно оперировать, на следующие категории:

Межкомпонентные данные- могут быть использованы в нескольких компонентах продукта без изменений и детализаций по каждому из них. Например:
- endpoints сервисов (пары );
- общие образы (docker) для компонентов, служебных сервисов (пути до хранилища образов).
Данные компонента - общие данные, используемые сервисами компонента. Например:
- значения атрибутов и включение/отключение опций тонких настроек сервисов и служб;
- доступ до службы с указанием УЗ/путей до сертификатов и ключей.
Характеристики модулей компонента. Включают в себя технические характеристики (такие, как ключи для доступа подов к пространствам, метки подов для наиболее быстрого доступа к ним, лимиты и ресурсы, точки монтирования и т.п.). Два варианта:
- Стендозависимые. Данные будут смигрированы в репозиторий конфигурации функциональных приложений после запуска миграции. Например: значения атрибутов и включение/отключение опций тонких настроек сервисов и служб, которые нельзя вынести в общий файл (файлы values--).
- Общие данные модуля/компонента, формирующие основные ресурсы и связи между модулями компонента в кластере (Platform V DropApp). Эти данные не меняются в зависимости от окружения и типа инсталляции, не будут смигрированы в репозиторий конфигураций функциональных приложений. Например метки контейнеров, количество реплик, аннотации, сервисы, gateways и т.п. (файлы restricted--).

Структура папки с конфигурациями helm в проекте будет выглядеть следующим образом:

helm
|____application
| |____<component>    ## имя компонента, например abyss
| | |____charts ## чарты
| | | |____<component>-<business>    ## наименование каталога - <<имя компонента>-<имя бизнес-модуля>> в этом компоненте
| | | | |____values-<component>-<business>.yaml    ##  стендозависимые данные бизнес-модуля. Данный файл будет смигрирован в репозиторий конфигурации функциональных приложений после запуска миграции
| | | | |____restricted-<component>-<business>.yaml   ## стендоНЕзависимые общие данные бизнес-модуля(не изменяются от стенда к стенду). Не будет смигрирован в репозиторий конфигурации функциональных приложений
| | | | |____Chart.lock   ## метаданные зависимых чартов/библиотек
| | | | |____Chart.yaml   ## метаданные чартов текущего репозитория
| | | | |____files    ## каталог с файлами конфигов и пр.
| | | | | |____env    ## каталог с файлами переменных окружения
| | | | | |____|_...
| | | | | |____configs   ## каталог с конфигурацией сервисов
| | | | | |____|_...
| | | | |____templates   ## шаблоны/библиотеки Helm
| | | | | |____|_...
| | | |____<component>-ingress   ## наименование каталога - <<имя компонента>-ingress> в этом компоненте 
| | | | |____values-<component>-ingress.yaml    ## стендозависимые данные компонента, касающиеся параметров Ingress. Данный файл будет смигрирован в репозиторий конфигурации функциональных приложений после запуска миграции
| | | | |____restricted-<component>-ingress.yaml   ## стендоНЕзависимые общие данные, касающиеся параметров Ingress (не изменяются от стенда к стенду). Не будет смигрирован в репозиторий конфигурации функциональных приложений
| | | | |____Chart.lock   ## метаданные зависимых чартов/библиотек
| | | | |____Chart.yaml   ## метаданные чартов текущего репозитория 
| | | | |____files   ## каталог с файлами конфигов и пр. 
| | | | | |____env.   ## каталог с файлами переменных окружения 
| | | | | |____|_...
| | | | | |____configs   ## каталог с конфигурацией сервисов
| | | | | |____|_...
| | | | |____templates   ## шаблоны/библиотеки Helm 
| | | | | |____|_...
| | | |____<component>-egress   ## наименование каталога - <<имя компонента>-egress>
| | | | |____values-<component>-egress.yaml   ## стендозависимые данные компонента, касающиеся параметров Egress. Данный файл будет смигрирован в репозиторий конфигурации функциональных приложений после запуска миграции
| | | | |____restricted-<component>-egress.yaml   ## стендоНЕзависимые общие данные, касающиеся параметров Egress(не изменяются от стенда к стенду). Не будет смигрирован в репозиторий конфигурации функциональных приложений
| | | | |____Chart.lock   ## метаданные зависимых чартов/библиотек
| | | | |____Chart.yaml   ## метаданные чартов текущего репозитория 
| | | | |____files   ## каталог с файлами конфигов и пр. 
| | | | | |____env    ## каталог с файлами переменных окружения
| | | | | |____|_...
| | | | | |____configs   ## каталог с конфигурацией сервисов 
| | | | | |____|_...
| | | | |____templates   ## шаблоны/библиотеки Helm 
| | | | | |____|_...
| | |____values-app.yaml   ## данные компонента
|____values-env.yaml   ## межкомпонентные данные

Файл values-env.yaml представляет собой файл с общими данными для все компонент.
- После миграции в репозиторий конфигураций функциональных приложений в файл вносятся изменения стендозависимых параметров, а также актуальные изменения, относящиеся к релизу.
Основная директория, относящаяся к приложению - application.
- В директории находятся чарты приложения с конфигурационными файлами restricted-*.yaml и values-*.yaml..
- Файлы restricted-*.yaml содержат в себе стендонезависисые данные (не изменяются от стенда к стенду). В их основе лежат конструкции, реализующие создание основных объектов Kubernetes, тонкие настройки, которые не должны быть доступны для изменений;
- В репозиторий конфигураций функциональных приложений мигрируют только файлы values-*.yaml..
Общие данные компонента содержатся в файле values-app.yaml.

Путь до параметров в плоской структуре:#

.Values.global.helm.appOpts.abyss.common.vault.kubernetes.authentication - ссылка на значение для helm, указанное в одном из файлов values.

Для того, чтобы правильно интерпретировать параметры, следует обратить внимание на следующие особенности:

.Values - это указатель для helm, который направляет его в файл values-* за поиском нужного значения;
Параметры могут быть представлены в плоской структуре, например строка с ссылкой на параметр global.helm.appOpts.abyss.common.vault.kubernetes.authentication будет иметь следующий вид:

global:
  helm:
    appOpts:
      abyss:
        common:
          vault:
            kubernetes:
              authentication: <значение параметра>

Если в ссылке на параметр после ключевого слова Values. идет блок с именем global, то параметр относится к общим файлам - values-env.yaml или values-app.yaml;
Значения ссылочного типа требуется оборачивать в кавычки и фигурные скобки {{ }}, например:

  discovery:
    type: '{{ .Values.global.helm.appOpts.abyss.common.discovery.type }}'

Работа с окружением, переопределение параметров после миграции данных в репозиторий конфигураций функциональных приложений#

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

Через репозиторий конфигураций функциональных приложений;
Через common-repo и использования функциональности секторов.

Переопределение параметров в репозитории конфигураций функциональных приложений#

После выполнения playbook MIGRATION_FP_CONF (подробнее в разделе Миграция конфигураций) и миграции данных из Cloudera (подробнее в разделе Миграция Abyss в Platform V DropApp) в репозитории функционального приложения в отдельных файлах внутри каталога environment есть возможность переопределения любых параметров из values-*.yaml или определения пользовательских переменных, на которые можно ссылаться в файлах values-*.yaml.

В каталоге environment допускается дополнительная вложенность.

Если установка релиза осуществляется в одноплечевой кластер, каталог environment должен включать в себя следующие файлы:

env-values-common.yaml - общие настройки для обоих плеч;
env-values-primary.yaml - настройки, специфичные для primary-плеча.

Если установка релиза осуществляется в георезервированный кластер, каталог environment должен включать в себя следующие файлы:

env-values-common.yaml - общие настройки для обоих плеч;
env-values-primary.yaml - настройки, специфичные для primary-плеча;
env-values-secondary.yaml - настройки, специфичные для secondary-плеча.

Имена файлов начинаются с префикса `env-values-*, остальная часть названия файлов может отличаться.

Рассмотрим примеры переопределения имеющихся и создания новых параметров в файлах для георезервированного кластера:

Переопределение параметров global.helm.appOpts.abyss.audit.enabled и global.helm.appOpts.abyss.common.zone_id, специфичных для плеч:

Часть параметров переопределяем из файла дистрибутива с общими параметрами приложения values-app.yaml:

global:
  helm:
    appOpts:
      abyss:
        ### Параметры сервиса authentication
        authentication:
          ### Тип аутентификации для подключения к OIDC провайдеру, возможные значения: SECRET, SECRET_AND_JWK common.auth.type
          type: SECRET_AND_JWK
          ### Пароль, используется для проверки подписи токена
          secret: ''
        ### Параметры сервиса authorization
        authorization:
          ### Хост, на котором расположен сервис авторизации (свойство common.pvm-security.host)
          host: abyss-authorization-{{ template "lib-chart-pvm.namespace-sha1-hash.tpl" $ }}
          ### Максимальное количество переподключений к сервису авторизации (свойство common.pvm-security.max-retries)
          max_retries: '2'
          ### Порт, на котором будет запущен сервис авторизации
          port: '8181'
          ### Ключ для шифрования API (свойство service.pvm.encoder.secret)
          encoder_secret: ''
        audit:
          enabled: 'false'
        common:
          ### Идентификатор зоны на которую настроен сервис. Возможные значения: PRIMARY, SECONDARY
          zone_id: PRIMARY

Флаг отправки событий аудита в Kafka global.helm.appOpts.abyss.audit.enabled выставляем в true для обоих плеч, поэтому данный параметр переопределяем в файле env-values-common.yaml:

global:
  helm:
    appOpts:
      abyss:
        audit:
          enabled: 'true'

Идентификатор зоны, в которой работает сервис, должен различаться на разных плечах. Параметр global.helm.appOpts.abyss.common.zone_id в файле values-app.yaml из примера выше уже указан как «PRIMARY». Его значение необходимо переопределить для файла с параметрами для второго плеча, поэтому параметр global.helm.appOpts.abyss.common.zone_id указываем в файле env-values-secondary.yaml:

global:
  helm:
    appOpts:
      abyss:
        common:
          zone_id: SECONDARY

Определение пользовательских переменных. Например, в файле env-values-common.yaml определяем новую переменную stand_root_dir:

global:
  helm:
    appOpts:
      abyss:
        stand_root_dir: st2

На которую будем ссылаться в чарте abyss-archive в файле values-abyss-archive.yaml следующим образом:

abyss-archive:
  helm:
    appOpts:
      hdfs:
        spark_event_logging_dir: "hdfs:///{{ tpl (.Values.global.helm.appOpts.abyss.stand_root_dir) $ }}/archive/sparkLogs" ## Новая переменная .Values.global.helm.appOpts.abyss.stand_root_dir теперь является частью значения параметра .Values.helm.appOpts.hdfs.spark_event_logging_dir чарта abyss-archive
        temporary_path: "/{{ tpl (.Values.global.helm.appOpts.abyss.stand_root_dir) $ }}/archive/temporary"                 ## Новая переменная .Values.global.helm.appOpts.abyss.stand_root_dir теперь является частью значения параметра .Values.helm.appOpts.hdfs.temporary_path чарта abyss-archive
        yarn_staging_dir: "/{{ tpl (.Values.global.helm.appOpts.abyss.stand_root_dir) $ }}/archive/sparkStaging"            ## Новая переменная .Values.global.helm.appOpts.abyss.stand_root_dir теперь является частью значения параметра .Values.helm.appOpts.hdfs.yarn_staging_dir чарта abyss-archive

Переопределение конфигураций во вложенной конфигурации. Например, в каталоге environment создаем директорию /sdp-st и добавляем файл env-values-hdfs-conf.yaml с переопределением конфигурации:

├── README.md
└── dev                                                                        // CONFIG_DIR - директория конфигураций из common-репозитория
    └── conf 
        ├── helm                                                               // корневая директория с helm
        │   ├── environment                                                    // директория окружения
        │   │   └── sdp-st                                                     // директория для файлов конфигураций общих на кластер
        │   │       ├── env-values-hdfs-conf.yaml                              // файл с переопределенной конфигурацией

Часть файла env-values-hdfs-conf.yaml:

abyss-common:
  helm:
    configMaps:
      hdfs-conf:
        data:
          core-site.xml: |
              <configuration>
                <property>
                  <name>fs.azure.user.agent.prefix</name>
                  <value>User-Agent: APN/1.0 Hortonworks/1.0 HDP/3.5.5.1-1</value>
                </property>
                <property>
                  <name>fs.defaultFS</name>
                  <value>hdfs://sdp-segment-st</value>
                  <final>true</final>
                </property>
                <property>
                  <name>fs.gs.application.name.suffix</name>
                  <value> (GPN:Hortonworks; version 1.0) HDP/3.5.5.1-1</value>
                </property>
                <property>
                  <name>fs.gs.path.encoding</name>
                  <value>uri-path</value>
                </property>
                <property>
                  <name>fs.gs.working.dir</name>
                  <value>/</value>
                </property>
                <property>
                  <name>fs.s3a.fast.upload</name>
                  <value>true</value>
                </property>
                <property>
                  <name>fs.s3a.fast.upload.buffer</name>
                  <value>disk</value>
                </property>
                <property>
                  <name>fs.s3a.multipart.size</name>
                  <value>67108864</value>
                </property>
                <property>
                  <name>fs.s3a.user.agent.prefix</name>
                  <value>User-Agent: APN/1.0 Hortonworks/1.0 HDP/3.5.5.1-1</value>
                </property>
                <property>
                  <name>fs.trash.interval</name>
                  <value>360</value>
                </property>
                <property>
                  <name>ha.failover-controller.active-standby-elector.zk.op.retries</name>
                  <value>120</value>
                </property>
    ...

С перечисленными выше примерами структура файлов конфигураций в репозитории будет выглядеть следующим образом:

├── README.md
└── dev                                                                        // CONFIG_DIR - директория конфигураций из common-репозитория
    └── conf 
        ├── helm                                                               // корневая директория с helm
        │   ├── environment                                                    // директория окружения
        │   │   └── sdp-st                                                     // директория для файлов конфигураций общих на кластер
        │   │       ├── env-values-hdfs-conf.yaml                              // файл с переопределенной конфигурацией
        │   │   └── env-values-common.yaml                                     // файл с общими параметрами для окружения
        │   │   └── env-values-primary.yaml                                    // файл с параметрами первого плеча окружения
        │   │   └── env-values-secondary.yaml                                  // файл с параметрами второго плеча окружения
        │   ├── application                                                     
        │   │   └── abyss
        │   │       ├── charts                                                 // чарты по модулям компонента
        │   │       │   ├── abyss-archive                                      // модуль archive service 
        │   │       │   │   └── values-abyss-archive.yaml                      // основной конфигурацийонный файл archive service 
        ...
        │   │       └── values-app.yaml                                        // общие межмодульные параметры компонента 
        │   └── values-env.yaml                                                // файл с основными endpoints, корректируемый под требуемый контур установки
        └── version.conf                                                       

Для того, чтобы данные изменения в файлах применились при установке в кластер, необходимо в COMMON-репозитории в файлах subsystems.json дополнить параметр customValuesMasks каждой устанавливаемой подсистемы, то есть:

  ...
  "ABYSS-API-PRIMARY": {
    "sector": ["abyss"],
    "customValuesMasks": "*/**/restricted*.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/abyss/*/**/values-*.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-common.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-abyssdevelop_st3_primary.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/sdp-st/*", // добавлен путь до каталога environment/ с нужными файлами для установки back в primary-плечо 
    "openshiftCluster": "https://api.dap.cluster1:6443",
    "openshiftSATokenCred": "token-cluster1",
    "openshiftAppsDomain": "apps.cluster1domain",
    "openshiftWebConsole": "https://console.apps.cluster1domain/k8s/cluster1/projects",
    "openshiftProjectName": "da-stand1-abyss-01"

  },
  "ABYSS-API-SECONDARY": {
    "sector": ["abyss"],
    "customValuesMasks": "*/**/restricted*.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/abyss/*/**/values-*.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-common.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-abyssdevelop_st3_secondary.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/sdp-st/*", // добавлен путь до каталога environment/ с нужными файлами для установки back в secondary-плечо 
    "openshiftCluster": "https://api.dap.cluster2:6443",
    "openshiftSATokenCred": "token-cluster2",
    "openshiftAppsDomain": "apps.cluster2domain",
    "openshiftWebConsole": "https://console.apps.cluster2domain/k8s/cluster/projects",
    "openshiftProjectName": "da-stand2-abyss-01"
  },
  "ABYSS-UI-PRIMARY": {
    "sector": ["abyss-ui"],
    "customValuesMasks": "*/**/restricted*.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/abyss/*/**/values-*.yaml,*/**/values-abyss-ui.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-common.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-abyssdevelop_st3_primary.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/only-ui-install.yaml", // добавлен путь до каталога environment/ с нужными файлами для установки ui в primary-плечо 
    "openshiftCluster": "https://api.dap.cluster1:6443",
    "openshiftSATokenCred": "token-cluster1",
    "openshiftAppsDomain": "apps.cluster1domain",
    "openshiftWebConsole": "https://console.apps.cluster1domain/k8s/cluster/projects",
    "openshiftProjectName": "da-stand3-abyss-ui-01"
  },
  "ABYSS-UI-SECONDARY": {
    "sector": ["abyss-ui"],
    "customValuesMasks": "*/**/restricted*.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/abyss/*/**/values-*.yaml,*/**/values-abyss-ui.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-common.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/environment/env-values-abyssdevelop_st3_secondary.yaml,*/**/{{ lookup('env', 'CONFIG_DIR') }}/**/only-ui-install.yaml", // добавлен путь до каталога environment/ с нужными файлами для установки ui в secondary-плечо 
    "openshiftCluster": "https://api.dap.cluster2:6443",
    "openshiftSATokenCred": "token-cluster2",
    "openshiftAppsDomain": "apps.cluster2domain",
    "openshiftWebConsole": "https://console.apps.cluster2domain/k8s/cluster/projects",
    "openshiftProjectName": "da-stand4-abyss-ui-01"
  }
  ...

В секции UI-приложения необходимо указывать файл only-ui-install.yaml последним в списке customValuesMasks. Этот файл находится в дистрибутиве и не мигрируется в репозиторий функциональных приложений.

Переопределение параметров в common-репозитории#

Обратите внимание на инструкцию в разделе Описание функциональности секторов с использованием extra-директорий.

Есть возможность определить общие настройки для нескольких кластеров или всех плеч одного кластера через создание отдельных extra-директорий в common-репозитории. В них необходимо создать вложенную папку /helm, в которых добавляем файл values-.yml ( - заменяем на нужное имя).

Обратите внимание! Расширение файлов обязательно *.yml

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

Пример:

|____dev
| |____ansible
| |____extra_abyss_all            ## Общие настройки всех кластеров
| | |____ansible
| | | |____common.conf.yml
| | |____helm
| | | |____values-custom-all.yml
| |____extra_abyss_st_01          ## Общие настройки кластера st_01
| | |____ansible
| | | |____common.conf.yml
| | |____helm
| | | |____values-custom.yml
| |____extra_abyss_st_02          ## Общие настройки кластера st_02
| | |____ansible
| | | |____common.conf.yml
| | |____helm
| | | |____values-custom.yml
| |____environment.json
| |____multiclusters.json
| |____subsystems.json
| |____version.conf

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

Обратите внимание! данная возможность НЕ РЕКОМЕНДОВАНА к использованию, так как автоматизация миграций данных common-репозитория не предусмотрена DOT.

Пример переопределения endpoints сервисов, заданных в файле values-env.yaml, который после миграции данных в репозиторий конфигураций функционального приложения файл располагается в каталоге /helm:

В файлах меняем значение параметров, соблюдая yaml-структуру файла values-env (аналогично описанию принципов переопределения значений в репозитории функциональных приложений):

global:
  endpoints:
    egress:
      postgres:
        enabled: true
        service:
          - "tcp://st-pangolin-01.**test.domain***.***:5433"
          - "tcp://st-pangolin-02.**test.domain***.***:5433"
          - "tcp://st-pangolin-03.**test.domain***.***:5433"
        mesh:
          internalPort: "5101,5501,5601"
          destPort: "5201,5701,5901"
          protocol: "tls"

  ...
  "ABYSS-API-PRIMARY": {
    "sector": ["abyss"],
    "app_name": ["abyss"],
    "fpi_name": "abyss",
    "groupId": "sbt_PROD.CI9****151_abyss.lgdb",
    "artifactId": "lgdb-dapp-cfg",
    "classifier": "distrib",
    "packaging": "zip",
    "versionFilter": "D-6",
    "customValuesMasks": "*/**/restricted*.yaml,*/**/values-*.yaml,*/**/values-env.yaml,*/extra_abyss_all/helm/values-custom-all.yml,*/extra_abyss_st_01/helm/values-custom.yml" ## добавить путь до extra_abyss_all/helm/values-custom-all.yml и extra_abyss_st_01/helm/values-custom.yml
  },
  "ABYSS-API-SECONDARY": {
    "sector": ["abyss"],
    "app_name": ["abyss"],
    "fpi_name": "abyss",
    "groupId": "sbt_PROD.CI9****151_abyss.lgdb",
    "artifactId": "lgdb-dapp-cfg",
    "classifier": "distrib",
    "packaging": "zip",
    "versionFilter": "D-6",
    "customValuesMasks": "*/**/restricted*.yaml,*/**/values-*.yaml,*/**/values-env.yaml,*/extra_abyss_all/helm/values-custom-all.yml,*/extra_abyss_st_02/helm/values-custom.yml" ## добавить путь до extra_abyss_all/helm/values-custom-all.yml и extra_abyss_st_02/helm/values-custom.yml
  },
  ...