Bundle DSL

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

Свернуть контент Развернуть контент

Содержание

На этой странице содержится информация о прототипах и домен-специфическом языке (DSL), которые используются в конфигурационных файлах для создания бандлов ADCM. Конфигурационный (конфиг-) файл создаётся в формате YAML.

ПРИМЕЧАНИЕ

Конфиг-файл должен называться config.yaml либо config.yml. Бандл может содержать несколько файлов config.yaml. Имя конфиг-файла является зарезервированным, другие файлы не следует называть этим именем.

Объекты ADCM создаются на основе прототипов. Прототип — это описание одного объекта ADCM.

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

name

name — это короткое имя, предназначенное для использования в скриптах Ansible.

type

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

cluster
service
provider (обозначает хостпровайдера)
host

version

version — это версия прототипа.

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

---
- type: cluster
  name: control
  version: 1

Прототип может содержать опциональные параметры:

actions

Будем называть действием (action) некую сущность, с помощью которой можно описать действие над объектом ADCM. Такое действие в конечном счёте представляет собой запуск Ansible playbook с определёнными параметрами при определённых условиях.

Вы можете описать специальные action для вызова через UI и на указанных endpoints. Вы можете выбрать из четырёх специальных action:

adcm_turn_on_maintenance_mode
adcm_turn_off_maintenance_mode
adcm_host_turn_on_maintenance_mode
adcm_host_turn_off_maintenance_mode

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

  actions:
    adcm_turn_on_maintenance_mode

Специальные action должны быть описаны в соответствующих прототипах.

Название

Тип прототипа

Описание

adcm_turn_on_maintenance_mode

Сервис/компонент

Переводит объект в режим обслуживания с помощью соответствующего элемента UI

adcm_turn_off_maintenance_mode

Сервис/компонент

Выводит объект из режима обслуживания с помощью соответствующего элемента UI

adcm_host_turn_on_maintenance_mode

Кластер

Переводит хост кластера в режим обслуживания с помощью соответствующего элемента UI

adcm_host_turn_off_maintenance_mode

Кластер

Выводит хост кластера из режима обслуживания с помощью соответствующего элемента UI

adcm_delete_service

Сервис

Удаляет сервис с помощью соответствующего элемента UI

Специальные action, которые описаны в прототипе кластера (adcm_host_turn_on_maintenance_mode, adcm_host_turn_off_maintenance_mode), должны быть также action хоста (значение параметра host_action должно быть true). Специальные action не поддерживаются для config, hc_acl и ui_options.

Пример

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

---
- type: cluster
  name: control
  version: 1
  description: "Monitoring and Control Software"

  actions:
    install:
      display_name: "Install Monitor Server"
      description: |
         By click on this button you install monitoring and controlling server ...
      type: job
      script_type: ansible
      script: ansible/site.yaml
      allow_to_terminate: true
      params:
        ansible_tags: install
        jinja2_native: true
      states:
        available:
          - created
        on_success: installed
        on_fail: created
      config:
        quorum:
          type: integer
      log_files:
        - check

Действие install из примера выше имеет тип job, а его параметр script указывает путь к Ansible playbook, который находится в директории <bundle_root>/ansible/site.yaml.

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

script: ./site.yaml

name

name — это короткое имя, которое уникально для данного прототипа.

display_name

display_name — это короткое имя, которое увидит пользователь.

type

Action содержит параметр type. Этот параметр определяет состояния job и task.

job является типом action, запускающего выполнение одного скрипта. Job описывается следующими параметрами:

script
script_type
params

task является типом action, состоящего из последовательности job. Последовательность job, которые будут выполняться, задаётся параметром scripts. Последовательность job выполняется в порядке перечисления в scripts. Если какой-то из скриптов не завершается успешно, то общее выполнение останавливается и объект переводится в состояние, согласующееся со значением on_fail.

actions:
  install:
    type: task
    scripts:
      -
          name: prepare
          display_name: Prepare to install
          script_type: ansible
          script: ansible/prepare.yaml
          on_fail: created
      -
          name: install
          display_name: Actual install
          script_type: ansible
          script: ansible/install.yaml
          on_fail: prepare
    states:
      available:
        - created
        - prepare
      on_success: installed

script

script — это параметр, который принимает значение в зависимости от значения script_type.

Если script_type = ansible, то параметр script означает путь к файлу скрипта.

Если script_type = internal, то параметр script может принимать значение одной из трёх функций ADCM:

bundle_revert — эта функция возвращает состояние кластера, предшествующее моменту обновления. Состояние кластера включает его конфигурацию, набор всех сервисов, хостов и компонентов кластера, а также host component mapping.
hc_apply — эта функция полезна, когда action включает hc_acl. В этом случае функция hc_apply указывает момент, когда host component mapping, полученный от hc_acl, должен быть применен при операциях расширения или сокращения кластера.
bundle_switch — эта функция обновляет все прототипы до новых версий. Функция может использоваться только для upgrade и не может быть использована для обычных action.

script является обязательным параметром, если type = job.

script_type

script_type — это параметр, который означает тип скрипта: ansible либо internal.

script_type является обязательным параметром, если type = job.

scripts

scripts — это параметр, определяющий последовательность job, которая будет выполнена.

scripts является обязательным параметром, если type = task.

params

Вы также можете передать любой дополнительный параметр для вызова Ansible. Такие параметры будут использоваться в вызовах ansible-playbook.

Специальным случаем является параметр ansible_tags. Этот параметр соответствует аргументу --tags для вызова ansible-playbook.

Вы также можете передать параметр jinja2_native. Этот параметр будет записан в файл ansible.cfg. Это позволяет сохранить типы переменных во время операций с шаблонами.

states

Action может содержать опциональный параметр states. Этот параметр определяет следующие состояния:

available — список состояний объекта, для которых доступен action;
on_success — состояние, в которое объект будет переведён в случае успеха action;
on_fail — состояние, в которое объект будет переведён в случае неуспеха action.

Состояния on_success и on_fail опциональны. Если они отсутствуют, то состояние объекта не будет изменено после успеха либо неуспеха action.

Параметр states также имеет два зарезервированных значения:

created — первичное состояние, в котором объекты находятся сразу после создания;
upgrading — состояние, в которое можно перевести кластер. В этом состоянии пользователю недоступны такие действия, как удаление хоста или сервиса из кластера.

masking

masking — альтернативный способ описания доступности actions как в UI, так и в API, с помощью которого можно описать набор основных (states) и расширенных (multi_state) состояний.

Используйте masking, если хотите описать доступность actions с использованием расширенных состояний, которые указываются в параметре multi_state.

ВАЖНО

DSL masking не совместим с DSL states, который описан выше.

---
actions:
  install:
  display_name: "Install Monitor Server"
  type: job
  masking:
      # Action will be shown if both condition under state and multi_state are met.
      state:
          available:
              # If the state equal to any of this, then condition is true
              - "state_value1"
              - "state_value2"
          unavailable:
              # If you place unavailable, then no available should be there
              - "state_value1"
              - "state_value2"
      multi_state:
          available:
              # If we have any of this multistate, then condition is true
              - "multi_state_1"
              - "multi_state_2"
          unavailable:
              # If you place unavailable, then no available should be there
              - "multi_state_3"
              - "multi_state_4"
  on_fail:
      state: "new_sate_value"
      multi_state:
          set:
              - "multi_state3"
          unset:
              - "multi_state4"
  on_success:
      state: "new_sate_value"
      multi_state:
          set:
              - "multi_state3"
          unset:
              - "multi_state4"

Чтобы упростить описание правил, вы можете использовать скаляр any, который заменяет собой все возможные значения.

---
  masking:
  state:
      available: "any"
      unavailable: "any"
  multi_state:
      available: "any"
      unavailable: "any"

Если значение параметра masking отсутствует, то мы считаем, что action доступен для каждого state или multi_state. Таким образом, следующие варианты эквивалентны:

---
  masking:

---
  masking:
      state:

---
  masking:
      state:
          available: "any"

Следующие варианты также эквивалентны:

---
  masking:

---
  masking:
      multi_state:

---
  masking:
      multi_state:
          available: "any"

config

Action может содержать опциональный параметр config. Этот параметр определяет список значений для параметров конфигурации. Когда action запускается через UI, все эти значения будут запрашиваться у пользователя перед стартом action.

Позже вы можете вызвать эти значения в скрипте Ansible:

{{ job.config.quorum }}

Параметр config предназначен для работы со статическими конфигурационными параметрами, которые отображаются одинаково каждый раз, когда запускается action. Если вы хотите работать с динамическими конфигурационными параметрами, используйте параметр config_jinja.

config_jinja

Action может содержать опциональный параметр config_jinja. Этот параметр указывает на файл в формате jinja (ADCM использует версию 2.xx).

config_jinja предназначен для работы с динамическими конфигурационными параметрами. В этом случае динамичность понимается как возможность отображения (либо скрытия) определённого набора параметров в зависимости от условий. Перед стартом action файл в формате jinja (шаблон Jinja2) рендерится. Значения, сформированные в результате, соответствуют значениям, которые содержатся в inventory-файле.

---
actions:
  - name: Restart and Reboot
    type: job
    script_type: ansible
    script: ansible/restart.yaml
    config_jinja: config_jinja/restart.j2

Файл restart.j2:

- reboot_servers:
  type: boolean
  default: false
  display_name: Reboot servers
{%  if cluster.state == 'created' %}
- configure_etc:
  type: boolean
  default: false
  display_name: Configure /etc/hosts
{% end %}

При описании шаблона Jinja2 можно указать переменную groups. Эта переменная содержит список имен хостов без их конфигураций. Пример переменных контекста рендеринга шаблона Jinja2 приведен ниже.

"cluster": {
   "config": {
      "reliability_control": {
         "retries": 3153600,
         "delay": 10,
         "timeout": 31536000
       }
   },
   "id": 210,
   "name": "adh bu"
   "state": "installed",
   "multi_state": [],
   "before_upgrade": {…},
   "version": "3.2.4_arenadata2_b1-for_autotest",
   "edition": "enterprise",
   "imports": None  # absent if no imports
},
"services":{
   "zookeeper":{
      "id" :193,
      "state":"installed",
      "multi_state":[],
      "before_upgrade":{"state":null},
      "config": {},
      "display_name": "Zookeeper",
      "version": "1.0",
      "maintenance_mode": False,
      "SERVER":{
         "component_id": 582,
         "state":"installed",
         "multi_state":[],
         "before_upgrade":{...},
         "config":{},
         "display_name": "Zookeeper Server",
         "maintenance_mode": false
      },
   },
},
"groups": {
   "CLUSTER": [
      "ke-test-hadoop-25.ru-central1.internal",
   ]
   "zookeeper": [
      "ke-test-hadoop-25.ru-central1.internal",
   ]
   "zookeeper.SERVER": [
      "ke-test-hadoop-25.ru-central1.internal",
   ]
},
},
"action": {
   "owner_group": "zookeeper",
   "name": "install"
}

log_files

Action может содержать опциональный параметр log_files. Этот параметр определяет список log tags. Сейчас поддерживается log tag check, вместе с которым вы можете использовать модуль Ansible adcm_check.

allow_to_terminate

Action может содержать опциональный параметр allow_to_terminate. Это логический параметр. Если значение не задано явно, то значением по умолчанию будет false. Если allow_to_terminate принимает значение true, то можно остановить выполнение Ansible playbook и остановить action, иначе остановить action будет невозможно.

Параметр allow_to_terminate также применяется ко всем jobs, из которых состоит action. Когда одна из таких jobs останавливается, action продолжает выполняться с той job, которая следует за остановленной. По сути, указание allow_to_terminate для action означает указание allow_to_terminate для всех jobs этого action.

allow_in_maintenance_mode

Action может содержать опциональный параметр allow_in_maintenance_mode. Это логический параметр. Если значение не задано явно, то значением по умолчанию будет false. Если allow_in_maintenance_mode принимает значение true и allow_maintenance_mode в прототипе также принимает значение true, то можно запустить action даже в случае, если объект или один из его хостов находится в режиме обслуживания.

allow_for_action_host_group

Action может содержать опциональный параметр allow_for_action_host_group. Это логический параметр. Если значение не задано явно, то значением по умолчанию будет false. Если параметр allow_for_action_host_group принимает значение true, то можно запустить action на группе хостов.

actions:
  upgrade:
    type: job
    script_type: ansible
    script: ansible/site.yaml
    allow_for_action_host_group: true

Ограничения использования параметра allow_for_action_host_group:

Композитные action (например, действие Upgrade) не могут быть запущены на группе хостов.
Не поддерживается одновременное использование этого параметра и параметра host_action.

ui_options

Этот блок позволяет настроить отображение и выполнение action в UI. При наведении курсора на action в UI отображается всплывающее сообщение, заданное в поле disclaimer.

actions:
  install:
    type: job
    script_type: ansible
    script: ansible/site.yaml
    ui_options:
       disclaimer: "Enter your disclaimer"

host_action

Action может содержать опциональный параметр host_action. Это логический параметр. Если значение не задано прямо, то значением по умолчанию будет false. При значении true action выполняется на выбранном хосте, а также создаётся таргет-группа, которая включает единственный выбранный хост.

actions:
  install:
    type: job
    script_type: ansible
    script: action.yaml
    host_action: true

hc_acl

Action может содержать опциональный параметр hc_acl. Этот параметр задействуется при запуске action через UI так, что новая host component map запрашивается у пользователя перед стартом action.

actions:
  expand:
    type: job
    script_type: ansible
    script: ansible/site.yaml
    states:
      available: all
    hc_acl:
      -
        service: hadoop
        component: datanode
        action: add
      -
        service: hadoop
        component: server
        action: remove

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

service — название сервиса.
component — название компонента.
action — тип операции. Принимает значение add или remove.

venv

Существует возможность указать версию Ansible для actions с помощью опционального параметра venv.

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

default — запустить action в окружении Ansible 2.8;
2.9 — запустить action в окружении Ansible 2.9.

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

Изменение окружения по умолчанию для всех действий на объекте:

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

    venv: "2.9"

Вы также можете настроить venv для любых actions:

actions:
  install:
    type: job
    script_type: ansible
    script: action.yaml
    venv: "2.9"

adcm_min_version

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

allow_maintenance_mode

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

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

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. Этот параметр описывает, сколько instances этого компонента должно быть установлено в одном кластере:

[1] — должен быть установлен ровно один компонент.
[0,1] — должно быть установлено один или ноль компонентов.
[1,2] — должно быть установлено один или два компонента.
[0,+] — должно быть установлено ноль или больше компонентов (значение по умолчанию).
[1,odd] — должно быть установлено один или больше компонентов, общее количество должно быть нечётным.
[0,odd] — должно быть установлено ноль или больше компонентов; если число компонентов больше ноля, то общее количество должно быть нечётным.
[odd] — то же, что [1,odd].
[1,+] — должно быть установлено один или больше компонентов.
[+] — компонент должен быть установлен на все хосты кластера.

monitoring

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

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

  components:
    client:
      monitoring: passive

requires

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

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

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

В примере ниже рассмотрен сервис 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.

Компоненты могут содержать опциональный параметр bound_to. Такие компоненты должны располагаться на тех же хостах, что и компоненты, с которыми они связаны.

Например, компонент server сервиса pxf должен быть установлен только на всех тех хостах, где установлены компоненты segment сервиса gpdb. Это значит, что компонент server нуждается в компоненте segment и не может быть установлен отдельно.

Таким образом, bound_to является ещё одним типом ограничений (constraints) или мета-ограничений для компонента.

---
- type: service
  name: GPDB
  version: 1.0

  components:
    Segment:

- type: service
  name: PXF
  version: 2.0

  components:
    Server:
      bound_to:
        service: GPDB
        component: Segment

config

Config — это общее описание параметров конфигурации объекта. Параметры конфигурации могут быть объединены в группы.

Пример

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

---
- type: cluster
  name: control
  version: 1
  description: "Monitoring and Control Software"

  config:
    - name: repos
      type: group
      subs:
         - name: ads
           display_name: "ADS repository URL"
           type: string
           default: https://ci.arenadata.io/artifactory/list/ads-centos7-x64-ads/
           required: no

В примере выше вы можете видеть параметр ads из группы repos. Параметр ads не является обязательным. Это значит, что пользователь может оставить его пустым.

Группа не является обязательной, поэтому вы можете расположить параметр на верхнем уровне:

---
- type: cluster
  name: control
  version: 1
  description: "Monitoring and Control Software"

  config:
    - name: ads
      type: string
      default: https://ci.arenadata.io/artifactory/list/ads-centos7-x64-ads/
      required: no

Группа — просто визуальное представление в UI.

Свойства параметров конфигурации

Название Обязательность Значения По умолчанию Описание

type

Да

См. ниже

—

Тип конфигурационного параметра. Обратитесь к отдельной секции Типы параметров конфигурации ниже

display_name

Нет

Определяются пользователем

—

Читаемое название, отображающееся в UI

description

Нет

Определяются пользователем

—

Позволяет дать параметру описание

default

Нет

Определяются пользователем

—

Позволяет установить значение по умолчанию

required

Нет

yes/no

Да

Если принимает значение yes, то необходимо иметь непустое и допустимое (valid) значение для переменной

read_only

Нет

См. ниже

Нет

Делает параметр доступным только для чтения при определённых обстоятельствах

writable

Нет

См. ниже

Да

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

ui_options

Нет

См. ниже

Нет

Позволяет настроить визуальное отображение параметра в UI

group_customization

Нет

yes/no

Нет

Делает доступным изменение параметра через конфиг-группы

pattern

Нет

Определяются пользователем

—

Правило валидации для введённого значения конфигурационного параметра

ansible_options

Нет

См. ниже

Нет

Позволяет указать дополнительные настройки для параметра во время подготовки inventory-файла Ansible

Параметр ui_options позволяет настроить отображение конфигурации в UI.

Доступны следующие опции:

Скрытие

Добавьте invisible: true к вашей конфигурации, чтобы скрыть её в UI.

Эта возможность не скрывает информацию из API и не отключает логику read_only/writable. Это просто вариант настройки UI.
```
int:
  type: integer
  default: 1
  required: no
  ui_options:
    invisible: true
```
Advanced

Это новая возможность, которая позволяет вам скрывать параметры, помечая их как advanced.

Параметр, помеченный как advanced, недоступен для поиска.
```
float:
  type: float
  default: 1.0
  required: no
  ui_options:
    advanced: true
```

Параметр group_customization позволяет вам настроить параметр на уровне конфиг-группы.

---
 - name: ads
   type: string
   group_customization: true/false

Параметр read_only позволяет вам сделать любой конфигурационный параметр параметром только для чтения (то есть защищённым от изменений пользователя или API) для указанных состояний кластера/хоста/сервиса. Параметр writable снимает защиту от записи.

Параметр quorum становится параметром только для чтения, если состояние сервиса — installed либо running:

config:
  quorum:
    type: integer
    read_only: [installed, running]

Параметр quorum становится параметром только для чтения при всех состояниях сервиса, кроме created:

config:
  quorum:
    type: integer
    writable: [created]

Параметр quorum будет параметром только для чтения при всех состояниях сервиса:

config:
  quorum:
    type: integer
    default: 4
    read_only: any

С помощью параметра pattern вы можете задать правило валидации значения конфигурационного параметра в соответствии с регулярным выражением. Параметр поддерживается для конфигурационных параметров типов password, string, text и secrettext.

Значение параметра pattern должно быть строкой, которая является допустимым регулярным выражением согласно диалекту регулярных выражений ECMA 262. Правила приведены ниже:

Один символ Unicode (кроме специальных символов ниже) совпадает с самим собой.
. — соответствует любому символу, кроме символов разрыва строки.
^ — соответствует только началу строки.
$ — соответствует только концу строки.
(…) — группирует серию регулярных выражений в одно регулярное выражение.
| — соответствует регулярному выражению, которое предшествует либо следует за символом |.
[abc] — соответствует любому из символов внутри квадратных скобок.
[a-z] — соответствует диапазону символов.
[^abc] — соответствует любому символу, не указанному в списке.
[^a-z] — соответствует любому символу вне диапазона.
+ — соответствует одному или более повторениям предшествующего регулярного выражения.
* — соответствует нулю или более повторениям предшествующего регулярного выражения.
? — соответствует нулю или одному повторению предшествующего регулярного выражения.
+?, *?, ?? — квалификаторы *, + и ? являются "жадными" (greedy); они совпадают с максимально возможным количеством текста. Иногда это поведение нежелательно, и нужно совпадение с минимальным количеством символов.
(?!x), (?=x) — отрицательная и положительная предвосхищающие проверки (lookahead).
{x} — соответствует ровно x вхождениям предшествующего регулярного выражения.
{x,y} — соответствует минимум x и максимум y вхождениям предшествующего регулярного выражения.
{x,} — соответствует x или более вхождениям предшествующего регулярного выражения.
{x,y}?, {x,}? — "нежадные" (non-greedy) версии вышеуказанных выражений.

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

Когда вы добавляте параметр pattern, рассмотрите процедуру обновления текущего бандла для существующего кластера:

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

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

config:
- name: example
  type: password
  display_name: "Example password"
  description: "Use uppercase and lowercase letters, as well as numbers"
  default: "qwerty56"
  pattern: "[a-z][A-Z][0-9]*?"

Параметр ansible_options позволяет указать опции для настройки конфигурационного параметра при подготовке inventory-файла Ansible.

Поддерживаемая опция для настройки — unsafe, которая помечает значение переменной как "небезопасное", позволяя предотвратить подстановку небезопасных символов в соответствии с функциональностью Ansible.

---
 - name: adb
   type: string
   display_name: "Name of default database"
   default: {%adb
   ansible_options:
     unsafe: True

Типы параметров конфигурации

boolean — логический параметр: принимает значение True или False.
file — содержимое этого параметра хранится в файле из файловой системы. Когда вы обращаетесь к переменной из скрипта Ansible, она возвращает полный путь к файлу.

Если значение по умолчанию задано, то это должен быть путь к файлу относительно корневой директории бандла.

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

Это может использоваться при хранении SSH private keys для скрипта Ansible:
```
- type: host
  name: ssh
  version: 1

  config:
    ansible_private_key_file:
      type: file
      default: host/ssh.key
```
Вы можете использовать точку, чтобы указать путь к файлу по умолчанию. В этом случае поиск файла по умолчанию будет осуществляться в той же директории, где находится файл config.yaml:
```
config:
  ansible_private_key_file:
    type: file
    default: ./ssh.key
```
float — плавающее число (float number). Если значение по умолчанию не задано сразу, то значением по умолчанию будет 0.0. Вы можете использовать опциональне параметры min и max для ограничения значений:
```
config:
  average_load:
    type: float
    default: 1.0
    min: 0.5
    max: 3.5
```
integer — целое число (integer number). Если значение по умолчанию не задано прямо, то значением по умолчанию будет 0. Вы можете использовать опциональные параметры min и max для ограничения значений:
```
config:
  memory_size:
    type: integer
    default: 16
    min: 2
    max: 64
```

json — этот тип хранит произвольные данные в формате JSON. Структура JSON не сохраняется и может быть модифицирована при каждом обновлении конфигурации:

config:
  population:
    type: json
    default:
      -
        country: Russia
        cities:
          -
             name: Moscow
             population: 9
      -
        country: USA
        cities:
          -
             name: LA
             population: 5

list — динамический массив произвольной величины. Элементы массива должны быть строками. Любой элемент может быть добавлен, удалён или изменён при каждом обновлении конфигурации:
```
config:
  mount_points:
    type: list
    default:
      - /dev/rdisk0s1
      - /dev/rdisk0s2
      - /dev/rdisk0s3
```
map — динамический словарь пар ключ/значение произвольной величины. Ключи и значения должны быть строками. Любой ключ или значение могут быть добавлены, удалены или изменены при каждом обновлении конфигурации:
```
config:
  person:
    type: map
    default:
      name: Joe
      age: "24"
      sex: m
```
option — словарный тип вида ключ/значение (key/value dictionary). Ключи отображаются в UI, в то время как значения хранятся в DB:
```
config:
  protocol:
    type: option
    option: {http: 80, https: 443}
    default: 80
```
password — то же, что тип string, но отображается в UI в виде поля для ввода паролей.
secretfile — скрывает параметр и его значение в UI.
secretmap — скрывает значение, которое принимает параметр, в UI.
string — произвольная строка. Размер строки не ограничен. Если значение по умолчанию не задано явно, то значением по умолчанию будет пустая строка "".

structure — тип, предназначенный для описания многоуровневых конфигураций. Число уровней не ограничено. Описание конфигураций осуществляется в соответствии со спецификацией, разобранной ниже. При каждом обновлении конфигурации новые данные сравниваются со спецификацией. Если входные данные не соответствуют спецификации, ADCM выдаёт ошибку.

Корневой элемент конфигурации, который должен быть первым описан в спецификации, носит название root. Для дальнейшего описания атрибутов используется элемент match, который можно отождествить с типом данных. Возможные значения match на этом уровне включают dict и list. В зависимости от значения match добавляются атрибуты следующего уровня — items (для dict) либо item (для list). Затем перечисляется состав элементов, входящих в item либо в items.

Доступные атрибуты перечислены ниже.

Название Тип Обязательность Описание

match

string

Да

Правило, согласно которому выполняются проверки других правил

item

string

Да, для типа list

Правило, согласно которому проверяется каждый объект в случае типа list

items

key/value pairs

Да, для типа dict

Правило, согласно которому проверяется каждый объект в случае типа dict

required_items

list

Нет

Список обязательных элементов объекта. Только для типа dict

invisible_items

list

Нет

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

default_item

string

Нет

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

Доступные значения match (типы элементов) перечислены в таблице ниже.

Тип Описание

string

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

boolean

Простой тип. Предназначен для булевых операций

integer

Простой тип. Предназначен для целых чисел

float

Простой тип. Предназначен для чисел с плавающей запятой

list

Рекурсивный тип. Сначала проверяет сам себя согласно item, затем применяет правила ко всем своим элементам

dict

Рекурсивный тип. Сначала проверяет сам себя, затем применяет правила к своим элементам согласно default_item и required_items

Ниже приведен пример конфигурации.

config:
  - name: country_codes:
    type: structure
    yspec: codes/schema.yaml
    default:
      - country: Greece
        code: 30
      - country: France
        code: 33
      - country: Spain
        code: 34
        regions:
          - Andalusia
          - Andalusia
          - Cantabria
          - Catalonia
          - Valencia

Файл спецификации schema.yaml:

---
root:
  match: list
  item: country_code

country_code:
  match: dict
  items:
    country: some_string
    code: some_integer
    regions: list_of_string
    comment: some_string
    uid: some_string
  required_items:
    - code
    - country
  invisible_items:
    - uid

list_of_string:
  match: list
  item: some_string

some_string:
  match: string

some_integer:
  match: int

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

yspec: ./schema.yaml

text — то же, что string, но отображается в UI в виде многострочного текста.
variant — тип, для которого пользователь может выбрать одно значение из списка опций в UI. Источники данных при этом могут быть различны. Вы можете получить список вариантов от другого параметра конфигурации (типом такого параметра конфигурации должен быть list):
```
config:
  - name: mount
    type: variant
    source:
      type: config
      name: mount_points

  - name: mount_points
    type: list
    default:
      - /dev/rdisk0s1
      - /dev/rdisk0s2
      - /dev/rdisk0s3
    read_only: any
    ui_options:
      invisible: true
```
Вы также можете получить список вариантов из встроенных функций ADCM, таких как cluster_hosts, возвращающей список всех хостов в текущем кластере:
```
config:
  - name: cluster_host
    type: variant
    source:
      type: builtin
      name: host_in_cluster
```
Встроенные функции ADCM:
- host_in_cluster — возвращает список всех хостов в текущем кластере.
- host_not_in_clusters — возвращает список всех хостов, которые не включены в какой-либо кластер.
- service_in_cluster — возвращает список всех сервисов, установленных в текущем кластере.
- service_to_add — возвращает список всех сервисов, не установленных в текущем кластере.
- host — получает аргументы в виде predicate и args: predicate является названием внутренней функции хоста; args содержит аргументы этой функции. Все внутренние функции возвращают список хостов (может быть пустым):
  config: - name: vhost type: variant source: type: builtin name: host args: predicate: and args: - predicate: in_service args: service: UBER - predicate: or args: - predicate: in_component args: service: UBER component: UBER_SERVER - predicate: in_cluster args:
  Список внутренних функций хоста:
- in_cluster — возвращает список всех хостов в текущем кластере;
- in_service — возвращает список всех хостов в указанном сервисе;
- not_in_service — возвращает список всех хостов вне указанного сервиса;
- in_component — возвращает список всех хостов в указанном компоненте;
- not_in_component — возвращает список всех хостов вне указанного компонента;
- in_hc — возвращает список всех хостов в host component map этого кластера;
- not_in_hc — возвращает список всех хостов вне host component map этого кластера;
- and — возвращает объединение множеств всех аргументов;
- or — возвращает пересечение множеств всех аргументов.
  
  Вы можете указать список прямо в бандле:
  config: - name: city type: variant source: type: inline strict: False value: - Moscow - Voronez - Ufa default: Samara
  Вы также можете указать опциональный аргумент strict для источника данных. Если strict принимает значение False, то пользователь может не только выбрать значение из списка, но ввести собственные значения в UI.
group — тип, который позволяет объединять конфигурационные параметры в группы. Группа может быть активируемой. Это значит, что вы можете включить либо отключить эту группу через UI. Когда группа отключена (active = false), вам не нужно заполнять связанные с ней значения в UI. Значения этой группы в файле Ansible inventory также будут нулевыми.
```
---
- type: cluster
  name: Kafka
  version: 1

  config:
     - name: grafana
       type: group
       activatable: true
       active: false
       subs:
          - name: endpoint
            type: string
          - name: port
            type: integer
```

config_group_customization

Каждый прототип кластера может содержать опциональный параметр config_group_customization. Этот параметр позволяет пользователю настроить все параметры для кластера (сервиса, компонента) на некоторой группе хостов. По умолчанию этот функционал отключён. Значение по умолчанию — false.

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

config_group_customization: true

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

description

description — это развёрнутое описание вашего прототипа.

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

display_name

display_name — это короткое имя, которое увидит пользователь.

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

edition

Каждый прототип кластера или хостпровайдера может содержать опциональный параметр edition, который соответствует типу бандла (продуктовый либо инфраструктурный).

Значение по умолчанию — community. Значение edition можно использовать для upgrade.

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

export

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

Пример

Если вы хотите экспортировать какие-либо части вашего конфиг-файла для других кластеров, вы можете использовать export. Используя export, вы можете указать любое количество вхождений config первого уровня. Вы можете экспортировать конфигурацию в кластер, а также в сервис:

---
- 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

flag_autogeneration

ПРИМЕЧАНИЕ

Часть функциональности этого атрибута была представлена с помощью параметра allow_flags до выпуска релиза 2.2.0. Параметр allow_flags больше не поддерживается.

Этот атрибут создан для автоматической генерации встроенных флагов. Атрибут может быть определён на любом прототипе. Атрибут также может быть включён и выключен на любом прототипе. Если flag_autogeneration определён как на родительском, так и на дочернем объекте, то более высокий приоритет у атрибута дочернего объекта.

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

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

import

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

Пример

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

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

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

Когда вы связываете кластер с другим кластером или сервисом, используя UI, вы можете использовать экспортированные параметры config в ваших скриптах Ansible следующим образом:

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

Опциональные параметры import

required — опциональный параметр import. Если required принимает значение true, то кластер или сервис сгенерируют issue и заблокируют любое действие, пока импорт не станет корректно связан с кластером или сервисом. Значение по умолчанию — false.
default — другой опциональный параметр import. Параметр default должен быть массивом названий из конфиг-группы этого кластера или сервиса. Если этот кластер либо сервис не связан с какой-либо секцией import для экспортируемого кластера либо сервиса, то файл Ansible inventory будет заполнен значениями из указанной конфиг-группы.

Рекомендуется называть группы по умолчанию так же, как называются экспортируемые группы.
multibind — ещё один опциональный параметр import. Если он принимает значение true, то вы можете связать несколько instances кластера либо сервиса с тем же кластером либо сервисом. В файле Ansible inventory значения импорта представлены в виде массива. Значение по умолчанию — false.

license

Каждый прототип кластера, сервиса или хостпровайдера может содержать опциональный параметр license, соответствующий типу бандла. Значение параметра 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

ПРИМЕЧАНИЕ

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

license: ./license.txt

monitoring

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

required

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

requires

Каждый прототип сервиса может содержать опциональный параметр requires.

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

По умолчанию сервис не зависит от какого-либо другого сервиса или компонента. Если же для сервиса указан другой сервис, от которого он зависит, то при добавлении этого сервиса без зависимого сервиса в ADCM генерируется issue. Таким образом зависимость сервиса от другого сервиса проверяется на этапе его добавления. Зависимость сервиса от компонента проверяется на этапе сохранения маппинга хостов и компонентов (host-component mapping).

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

upgrade

Обновление (upgrade) — это операция, доступная из определённого состояния объекта (кластера либо хостпровайдера), которая обновляет метаинформацию об этом объекте и переводит его в другое состояние. Существует два типа обновлений:

Переключение прототипов текущего бандла на прототипы нового бандла.
Выполнение некоторого action, возможно, состоящего из нескольких subaction (включая переключения прототипов).

Пример

Прототип кластера либо хоста может содержать параметр upgrade. Этот параметр описывает, как выполнить обновление с одной версии бандла на другую. Прототип может содержать несколько upgrade, которые описывают обновления с разных версий.

---
- type: cluster
  name: control
  version: 2.4
  description: "Monitoring and Control Software"

  upgrade:
     -
        name: Upgrade 1
        versions:
           min: 0.4
           max: 2.0
        description: New cool upgrade
        states:
           available: any
           on_success: upgradable
     -
        name: Upgrade 2
        versions:
           min: 1.0
           max_strict: 3.0
        scripts:
          - name: pre check
            display_name: Some pre-check before upgrade prototypes
            script_type: ansible
            script: ansible/pre-check.yaml
          - name: bundle upgrade
            display_name: Upgrade bundle
            script_type: internal
            script: bundle_switch
          - name: post tasks
            display_name: Some operation after prototype upgrades
            script_type: ansible
            script: ansible/post-task.yaml
        from_edition: community
        states:
           available:
	     - installed
           on_success: upgradable

versions

upgrade должен содержать параметр versions. versions — это интервал версий, которые подходят для обновления.

upgrade:
   -
      name: Upgrade
      versions:
         min: 0.4
         max: 2.0
      states:
         available: any
         on_success: upgradable

ПРИМЕЧАНИЕ

min и max используют нестрогое сравнение (границы включают версию кластера или хоста). Если вам нужно строгое сравнение, используйте min_strict или max_strict вместо min/max.

name

upgrade должен содержать параметр name. name — это название объекта.

display_name

upgrade должен содержать параметр display_name. display_name — это название объекта, которое увидит пользователь в UI.

description

upgrade может содержать опциональный параметр description. description позволяет вам дать описание для обновления.

states

upgrade должен содержать параметр states. states определяет следующие состояния:

available — перечисляет состояния кластера, позволяющие обновление. Специальное значение any может использоваться для обновления, доступного в любом состоянии.
on_success — состояние кластера после обновления.

upgrade:
   -
      name: Upgrade 1
      versions:
         min: 0.4
         max: 2.0
      description: New cool upgrade
      states:
         available: [created, installed]
         on_success: upgradable

from_edition

upgrade может содержать опциональный параметр from_edition. from_edition — это список editions, которые позволяют обновление.

Специальное значение any может использоваться для указания permission при апгрейде бандлов с любого edition. Значение по умолчанию — community.

upgrade:
   -
      name: Upgrade 1
      versions:
         min: 0.4
         max: 2.0
      description: New cool upgrade
      states:
         available: [created, installed]
         on_success: upgradable
      from_edition:
         - community
         - enterprise

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