Обзор прототипов

Михаил Серов, Аделя Звягинцева

Прототип — описание одного объекта ADCM. В одном бандле может быть описано несколько прототипов, относящихся к соответствующему типу бандла.

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

  • name — внутреннее имя прототипа, которое используется в том числе в inventory-файле продуктового или инфраструктурного бандла.

  • type — тип прототипа или объекта. Возможные значения:

    • для продуктового бандла:

      • cluster

      • service

    • для инфраструктурного бандла:

      • provider

      • host

  • version — версия прототипа (кластера, сервиса или хостпровайдера). Не применяется к компонентам и хостам.

  • display_name — имя объекта, отображаемое в веб-интерфейсе (например, Hadoop). Отличие данного свойства от свойства name заключается в том, что name используется для интеграции с ADCM, обновления объектов и так далее.

  • description — развернутое описание прототипа.

Таким образом, простой прототип будет выглядеть следующим образом:

---
- type: cluster
  name: control
  version: 1
  display_name: "Controlling Software"
  description: |
     This software is intended to monitor and control
     you cluster and does it by ...

Также в зависимости от типа объекта прототип может содержать опциональные свойства, описанные ниже.

Общие свойства

Каждый прототип кластера, сервиса, компонента, хостпровайдера или хоста может включать следующие свойства:

  • actions и config

  • flag_autogeneration

  • venv

actions

Свойство actions определяет доступные для пользователя действия над объектом. Запуск action приводит к созданию набора job, предназначенных для выполнения соответствующего Ansible playbook с заданными параметрами и условиями. Подробное описание свойства приведено в статье actions.

config

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

flag_autogeneration

ПРИМЕЧАНИЕ
До выпуска релиза 2.2.0 часть функциональности этого свойства была представлена с помощью свойства allow_flags. Свойство allow_flags больше не поддерживается.

Свойство предназначено для управления (включения и выключения) автоматической генерацией встроенных флагов. Пример использования свойства для описания прототипа кластера приведен ниже.

Если свойство flag_autogeneration задано для родительского и дочернего объекта, то состояние свойства дочернего объекта будет иметь более высокий приоритет.

Свойство может быть включено и выключено в прототипе любого объекта. Это значит, что flag_autogeneration может быть выключен в конкретном сервисе несмотря на то, что свойство включено в кластере (соответственно все сервисы кластера наследуют состояние свойства).

В текущей реализации поддерживается один встроенный флаг adcm_outdated_config. Этот флаг возникает автоматически, когда изменяется конфигурация объекта. Чтобы включить автоматическое создание этого встроенного флага при изменении конфигурации объекта, укажите для свойства enable_outdated_config значение True.

---
- type: cluster
  name: adpg
  flag_autogeneration:
    enable_outdated_config: True

venv

Свойство venv определяет версию Ansible, которая будет использоваться при запуске действий (action) соответствующего прототипа.

Доступные значения:

  • default (при версии контракта 1.0) — использовать версию Ansible 2.8 при запуске действия (action);

  • 2.9 — использовать версию Ansible 2.9 при запуске действия (action);

  • 2.16 — использовать версию Ansible 2.16 при запуске действия (action) (начиная с версии ADCM 2.8.0).

Значением по умолчанию является default.

ПРИМЕЧАНИЕ
С выходом версии ADCM 2.8.0 версия Ansible 2.8 считается устаревшей и перестанет поддерживаться в третьем квартале 2026. 
  ---
  - type: cluster # service component hostprovider host
    name: control
    version: 1

    venv: "2.9"

Прототип кластера

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

Особенности работы с кластером:

  • У кластера определена процедура обновления, с помощью которой можно определить переход кластера от одной версии к другой.

  • Для кластера доступно определение конфигурации.

  • Механизм импорта предназначен для передачи между кластерами (сервисами) метаданных — особым образом помеченной конфигурации. Такой подход позволяет описывать кластеры (сервисы) с целью их повторного использования в разных кластерах (сервисах).

    ВАЖНО
    Импорт сервисов и кластеров не предполагает их физического переноса.

Прототип кластера может быть описан в бандле в единственном экземпляре.

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

adcm_min_version

Свойство adcm_min_version определяет минимальную версию ADCM, которая необходима для корректной работы бандла. Если установленная версия ADCM меньше, чем указанная в бандле версия adcm_min_version, то загрузка этого бандла приведет к ошибке.

allow_maintenance_mode

Свойство allow_maintenance_mode обеспечивает поддержку режима обслуживания для всех прототипов бандла. Значение по умолчанию — false.

Обратите внимание, что данное свойство поддерживает механизм наследования. Это означает, что при его определении на уровне прототипа кластера соответствующее значение автоматически применяется к сервисам и компонентам, входящим в состав бандла. При этом для конкретного дочернего объекта (сервиса или компонента) значение свойства может быть переопределено — в таком случае значение, заданное на уровне дочернего объекта, имеет более высокий приоритет, чем значение, унаследованное от кластера.

Также следует учитывать, что при нахождении сервиса, компонента или хоста в режиме обслуживания доступные для пользователя действия с этим объектом ограничены, поэтому данное свойство рекомендуется рассматривать совместно со свойством allow_in_maintenance_mode.

---
- type: cluster
  name: control
  version: 1
  adcm_min_version: 2019.05.01.00
  allow_maintenance_mode: true

config_group_customization

Свойство config_group_customization позволяет добавить поддержку конфигурационных параметров на уровне конфиг-группы. По умолчанию эта функциональность отключена. Значение по умолчанию — false.

ПРИМЕЧАНИЕ
Свойство может быть определено для прототипа кластера, сервисов, компонентов и хостпровайдеров. Данное свойство не применяется к прототипам хостов.

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

Свойство поддерживает механизм наследования: если оно задано на уровне кластера, соответствующее значение автоматически применяется к сервисам и компонентам данного бандла. Для конкретного сервиса или компонента значение свойства может быть переопределено — в этом случае значение, заданное на уровне дочернего объекта, имеет более высокий приоритет.

---
- type: cluster # service component
  name: control
  version: 1

config_group_customization: true

Если вы хотите изменить поведение конкретного параметра, воспользуйтесь опцией group_customization соответствующего конфигурационного параметра.

contract_version

Свойство contract_version определяет версию контракта бандла. Под контрактом понимается версионируемый конфиг-файл config.y(a)ml, который фиксирует доступные функции, особенности поведения и гарантии совместимости, необходимые для корректной работы бандла.

---
- type: cluster
  name: ado
  display_name: ADO
  description: Arenadata Orchestrator
  version: "{{ cluster_version }}"
  contract_version: 2.0
  edition: community
  license: EULA.txt
  adcm_min_version: 2.5.0
  env: 2.9
  allow_maintenance_mode: true
ПРИМЕЧАНИЕ
Если свойство contract_version не указано в config.y(a)ml, автоматически применяется значение 1.0.

Версия контракта применяется для обеспечения совместимости бандлов с ADCM и служит для следующих целей:

  • проверка установленных и загруженных бандлов до и во время обновления ADCM;

  • предотвращение обновлений ADCM, которые могут нарушить работу уже установленных бандлов;

  • предварительное уведомление пользователей о бандлах, переходящих в статус устаревших.

Версия контракта следует политике семантического версионирования (semantic versioning):

  • мажорная версия — содержит несовместимые изменения (например, удаление устаревших возможностей или механизмов выполнения);

  • минорная версия — содержит изменения поведения загрузки бандла с сохранением обратной совместимости (например, добавление наследования свойства от кластера к его сервисам).

Каждый релиз ADCM определяет:

  • список поддерживаемых версий контракта;

  • список устаревших версий контракта.

Проверка совместимости бандлов по версии контракта выполняется при запуске и обновлении ADCM. При обнаружении несовместимых бандлов операция прерывается.

edition

Свойство, соответствующее типу бандла, определяет издание объекта. Значение по умолчанию — community. С помощью свойства edition также можно определить правила, определяющие доступность операций обновления (upgrade) для кластеров и хостпровайдеров.

---
- type: cluster
  name: adh
  display_name: Arenadata Hadoop
  version: 1
  edition: enterprise

export

Экспорт — это способ указать настройки, которые кластер или сервис может передавать другим кластерам.

Если пользователь связывает кластер с другим кластером или сервисом, используя веб-интерфейс, то они появятся в inventory-файле, а значит вы сможете использовать экспортированные конфигурационные параметры в Ansible playbook следующим образом:

---
- type: service
  name: Hadoop
  version: 2.1

  config:
     core-site:
        param1:
           type: string
        param2:
           type: integer
     quorum:
        type: integer
        default: 3

  export:
      - core-site
      - quorum

import

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

Чтобы импортировать части config, экспортированных из другого кластера, используйте свойство import. Вы можете указать название и допустимые версии экспортированного кластера (или сервиса в кластере):

---
-
  type: cluster
  name: Hive
  version: 4

  import:
     Hadoop:
        versions:
           min: 1.8
           max: 2.5

Если пользователь связывает кластер с другим кластером или сервисом, используя веб-интерфейс, вы можете использовать экспортированные конфигурационные параметры в Ansible playbook следующим образом:

{{  cluster.import.Hadoop.core-site.param2  }}
{{  cluster.import.Hadoop.quorum  }}

Следует учитывать, что пользователь может не выполнять импорт требуемого кластера или сервиса, поэтому вам необходимо обрабатывать сценарии отсутствия импортируемых параметров в inventory-файле. В качестве альтернативного решения можно воспользоваться свойством импорта default либо сделать импорт обязательным, применив соответствующие настройки, приведенные в таблице ниже.

Свойство Значение по умолчанию Описание

required

false

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

default

 — 

Массив названий из конфиг-группы кластера или сервиса. Если кластер или сервис не связан с секцией import для экспортируемого кластера или сервиса, то файл Ansible inventory заполняется значениями из указанной конфиг-группы

multibind

false

Если свойство принимает значение true, то пользователь сможет импортировать несколько кластеров или сервисов в текущий кластер или сервис

license

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

Ниже приведены два примера использования:

  • для прототипа кластера:

    ---
- type: cluster
  name: adh
  display_name: Arenadata Hadoop
  version: 1
  license: misc/license.txt

  • для прототипа сервиса:

    ---
- type: service
  name: hdfs
  display_name: HDFS
  version: 1
  license: misc/license.txt

Если прототип кластера или сервиса содержит свойство license, то после загрузки бандла или перед добавлением сервиса пользователю будет предложено принять лицензионное соглашение. До принятия лицензионного соглашения все дальнейшие действия с бандлом или сервисом будут заблокированы.

---
- type: cluster
  name: adh
  display_name: Arenadata Hadoop
  version: 1
  license: misc/license.txt
ПРИМЕЧАНИЕ

Вы можете использовать точку, чтобы указать путь к файлу лицензии. В этом случае поиск файла лицензии будет осуществляться в директории, которая содержит файл config.yaml:

license: ./license.txt

upgrade

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

Прототип сервиса

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

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

Описание свойств allow_maintenance_mode, config_group_customization, export, import и license приведено в разделе Прототип кластера.

components

Сервисный прототип может содержать компоненты. Так как компонент сам считается прототипом, его описание тоже может содержать такие секции, как config и action.

components — это способ поместить сервисные компоненты на хосты в кластере.

---
- type: service
  name: server
  version: 1

  components:
    master:
      display_name: "Master Node"
      description: "This node control all data nodes (see below)"
      constraint: [1,2]
    node:
      display_name: "Data Node"
      constraint: [+]
    client:
      monitoring: passive

constraint

Каждый компонент может содержать опциональное свойство constraint. Это свойство описывает, сколько экземпляров (instance) этого компонента должно быть установлено в одном кластере:

  • [1] — должен быть установлен ровно один компонент.

  • [0,1] — должно быть установлено один или ноль компонентов.

  • [1,2] — должно быть установлено один или два компонента.

  • [0,+] — должно быть установлено ноль или больше компонентов (значение по умолчанию).

  • [1,odd] — должно быть установлено один или больше компонентов, общее количество должно быть нечетным.

  • [0,odd] — должно быть установлено ноль или больше компонентов; если число компонентов больше ноля, то общее количество должно быть нечетным.

  • [odd] — то же, что [1,odd].

  • [1,+] — должно быть установлено один или больше компонентов.

  • [+] — компонент должен быть установлен на все хосты кластера.

ПРИМЕЧАНИЕ
Использование ограничения [+] может привести к некорректной работе кластера при добавлении нового хоста в уже установленный кластер, так как компонент с данным ограничением должен быть установлен на всех хостах кластера.

monitoring

Каждый сервис или компонент может содержать опциональное свойство monitoring. Это свойство определяет, следует ли учитывать heartbeat сервиса или компонента при расчете агрегированного статуса. Значение по умолчанию — active. Чтобы исключить сервис или компонент из расчета статуса, установите значение passive.

---
- type: service
  name: server
  version: 1

  components:
    client:
      monitoring: passive

requires

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

Каждый компонент может требовать один или несколько компонентов того же или другого сервиса в кластере. Также компонент может зависеть от одного или нескольких сервисов. Если ваш компонент зависит от другого компонента, который отсутствует в host-component map, то вы не сможете добавить и ваш компонент в host-component mapping. В некоторых случаях все требующиеся компоненты должны устанавливаться одновременно. Зависимости, определенные на уровне компонентов, влияют на валидацию host-component map.

Зависимости нужно рассматривать в качестве еще одного типа ограничений (constraint) или метаограничений для компонента.

В примере ниже рассмотрен сервис Hive с тремя компонентами: HiveServer, Metastore и TezUI. Компонент HiveServer зависит от сервиса HDFS, при этом информация о компонентах сервиса HDFS не требуется. Компонент TezUI требует наличия компонента TimeLineServer сервиса YARN.

---
- type: service
  name: Hive
  version: 1.0

  components:
    HiveServer:
      requires:
        - service: HDFS
    Metastore:
      constraint: [0,1]
    TezUI:
      requires:
        - service: YARN
          component: TimeLineServer
      constraint: [0,1]

bound_to

ВАЖНО
Свойство bound_to не поддерживается начиная с версии 2.0.0.

monitoring

Каждый прототип сервиса или компонента может содержать опциональное свойство monitoring. Это свойство определяет, следует ли учитывать heartbeat сервиса или компонента при расчете агрегированного статуса. Значение по умолчанию — active. Чтобы исключить сервис или компонент из расчета статуса, установите значение passive.

required

Свойство required предназначено для указания обязательности сервиса для корректной работы кластера. Значение по умолчанию — false. Если функционирование кластера невозможно без данного сервиса, установите значение true. В этом случае отсутствие сервиса в составе кластера приведет к ошибке.

requires

Свойство requires предназначено для определения обязательных зависимостей сервиса — оно указывает, какие другие сервисы или компоненты должны быть установлены совместно с данным сервисом для его корректной работы.

По умолчанию сервис считается независимым и не требует наличия других сервисов или компонентов. Если же в requires указан сервис, от которого зависит текущий сервис, то при попытке добавить его в ADCM без необходимого зависимого сервиса будет создан issue. Таким образом, зависимости между сервисами валидируются на этапе добавления сервиса.

Зависимости сервиса от компонентов проверяются отдельно — на этапе сохранения маппинга хостов и компонентов (host-component mapping).

---
- type: service
  name: Hive
  version: 1.0
  requires:
    - service: HDFS
    - service: YARN
      component: TimeLineServer

Прототип хостпровайдера

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

Описание свойств приведено в разделе Прототип кластера.

Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней