config

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

Конфигурационные параметры могут быть объединены в группы. Количество вложенных групп неограниченно.

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

  • Primary configuration

  • Ansible settings

  • Configuration group

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

Доступ разработчиков бандлов к конфигурации обеспечивается посредством inventory‑файлов.

---
- 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 не является обязательным, пользователь может оставить его значение пустым.

Также допускается размещение параметра на верхнем уровне:

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

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

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

type

Да

См. ниже

 — 

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

display_name

Нет

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

 — 

Название, отображающееся в веб-интерфейсе

description

Нет

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

 — 

Описание параметра

default

Нет

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

 — 

Значение по умолчанию

required

Нет

yes/no

Да

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

read_only

Нет

См. ниже

Нет

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

writable

Нет

См. ниже

Да

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

ui_options

Нет

См. ниже

Нет

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

group_customization

Нет

yes/no

Нет

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

pattern

Нет

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

 — 

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

ansible-options

Нет

См. ниже

Нет

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

Подробная информация о свойствах параметров конфигурации приведена ниже.

read_only

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

Ниже приведены примеры описания свойства quorum, доступного только для чтения:

  • если сервис находится в состоянии installed либо running:

config:
  quorum:
    type: integer
    read_only: [installed, running]
  • если состояние сервиса отличается от состояния created:

config:
  quorum:
    type: integer
    writable: [created]
  • при любом состоянии сервиса:

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

writable

Свойство writable позволяет снять защиту от записи.

ui_options

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

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

  • advanced (свойство доступно пользователю при включении переключателя Advanced в веб-интерфейсе)

    Чтобы отметить параметры как advanced (для расширенной настройки), в блоке ui_options укажите advanced: true. Параметры с данной опцией отображаются в веб-интерфейсе при активации одноименного переключателя.

    float:
      type: float
      default: 1.0
      required: no
      ui_options:
        advanced: true
  • invisible (свойство полностью скрыто от пользователя)

    Чтобы скрыть конфигурацию в веб‑интерфейсе, в блоке ui_options укажите invisible: true. Данная опция не влияет на доступность данных о конфигурации через API и не отключает логику read_only/writable. Она относится исключительно к настройке веб-интерфейса.

    int:
      type: integer
      default: 1
      required: no
      ui_options:
        invisible: true

group_customization

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

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

pattern

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

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

  • Любой символ Unicode, не входящий в список специальных метасимволов, описанных ниже, сопоставляется сам с собой.

  • Допустимы только стандартные символы экранирования, такие как \n, \r, \t. Учтите, что обратная косая черта (\) подлежит экранированию в соответствии с синтаксисом JSON.

Символ Описание

.

Соответствует любому отдельному символу, кроме новой строки

^

Соответствует началу текстовой строки

$

Соответствует концу текстовой строки

(…​)

Группирует серию регулярных выражений в одно регулярное выражение

|

Указывает на чередование и соответствует логическому оператору OR

[abc]

Соответствует любому символу из перечисленных

[a-z]

Соответствует любому символу из набора символов

[^abc]

Соответствует любому символу, кроме перечисленных

[^a-z]

Соответствует любому символу, не входящему в набор символов

+

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

*

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

?

Указывает на то, что предыдущий символ или выражение могут входить в строку ноль или один раз

+?, *?, ??

"Ленивые" (lazy) эквиваленты "жадных" (greedy) квантификаторов. "Ленивый" поиск, при котором предыдущий символ или выражение может встретиться в данной позиции:

  • один или более раз;

  • ноль или более раз;

  • ноль или один раз.

(?!x), (?=x)

Отрицательная и позитивная опережающая проверка (lookahead)

{x}

Поиск x вхождений предыдущего выражения

{x,y}

Поиск не менее x и не более y вхождений предыдущего выражения

{x,}

Поиск x или более вхождений предыдущего выражения

{x,}?

"Ленивый" поиск x или более вхождений предыдущего символа или выражения

{x,y}?

"Ленивый" поиск не менее x и не более y вхождений предыдущего символа или выражения

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

Ниже представлены три возможных подхода к решению этой проблемы.

  1. Остановите обновление объекта, если значение конфигурационного параметра не соответствует правилу валидации.

  2. При необходимости мигрируйте значение конфигурационного параметра.

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

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

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

Свойство 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

Пример конфигурационного параметра типа boolean
Пример конфигурационного параметра типа boolean
config:
  - name: AUTH_ROLES_SYNC_AT_LOGIN
    description: "If we should replace ALL the user's roles each login, or only on registration"
    type: boolean
    default: True

file

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

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

Пример конфигурационного параметра типа file
Пример конфигурационного параметра типа file

Данный тип подходит для безопасного хранения приватных SSH‑ключей, необходимых для работы Ansible.

config:
  - name: conf_properties_template_sentinel
    display_name: sentinel.conf
    type: file
    default: ansible/roles/airflow2/templates/sentinel.conf.j2
    ui_options:
      advanced: True

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

config:
  ansible_private_key_file:
    type: file
    default: ./ssh.key

float

Число с плавающей точкой (floating-point number). Значение по умолчанию — 0.0.

Пример конфигурационного параметра типа float
Пример конфигурационного параметра типа float

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

config:
  - name: yarn.resourcemanager.monitor.capacity.preemption.total_preemption_per_round
    description: "Maximum percentage of resources preempted in a single round. By controlling this value one can throttle the pace at which containers are reclaimed from the cluster. After computing the total desired preemption, the policy scales it back within this limit"
    type: float
    default: 0.1
    ui_options:
      advanced: True

group

Тип, который позволяет объединять конфигурационные параметры в группы. Группа может быть активируемой. Это значит, что вы можете включить либо отключить эту группу через веб-интерфейс. Когда группа отключена (active = false), пользователю не нужно заполнять связанные с ней значения в веб‑интерфейсе. Значения этой группы в файле Ansible inventory также будут нулевыми.

Пример конфигурационного параметра типа group
Пример конфигурационного параметра типа group
ПРИМЕЧАНИЕ
Начиная с версии ADCM 2.9.0 одна группа может быть включена в другую группу. Количество вложенных групп не ограничено.
---
---
- type: cluster
  name: Kafka
  version: 1

  config:
     - name: grafana
       type: group
       activatable: true
       active: false
       subs:
          - name: endpoint
            type: string
          - name: port
            type: integer
          - name: database
            type: group
            activatable: true
            active: false
            subs:
               - name: user_name
                 type: string
               - name: user_password
                 type: password

integer

Целое число (integer number). Значение по умолчанию — 0.

Пример конфигурационного параметра типа integer
Пример конфигурационного параметра типа integer

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

config:
  - name: yarn.cluster.max-application-priority
    description: "Defines maximum application priority in a cluster. If an application is submitted with a priority higher than this value, it will be reset to this maximum value"
    type: integer
    default: 0
    ui_options:
      advanced: True

json

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

Пример конфигурационного параметра типа json
Пример конфигурационного параметра типа json
config:
  - name: notebook.interpreters.trino.options
    type: json
    default:
      url: ""
      auth_type: "basic"
      kerberos_principal: ""
      kerberos_service_name: "HTTP"
      kerberos_force_preemptive: True
      kerberos_delegate: True
      ssl_cert_ca_verify: False
    read_only: any

list

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

Пример конфигурационного параметра типа list
Пример конфигурационного параметра типа list
Диалоговое окно для добавления конфигурационного параметра типа list
Диалоговое окно для добавления конфигурационного параметра типа list
config:
  - name: sources
    display_name: "Sources"
    description: "Set a list of sources which will be written into flink-env.sh"
    required: False
    type: list
    default:
      - "/usr/lib/bigtop-utils/bigtop-detect-javahome"

map

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

Пример конфигурационного параметра типа map
Пример конфигурационного параметра типа map
Диалоговое окно для добавления конфигурационного параметра типа map
Диалоговое окно для добавления конфигурационного параметра типа map
config:
  - name: flink_env_custom
    display_name: "Custom flink_env.sh"
    description: "Add value to environment variables."
    type: map
    required: False
    ui_options:
      advanced: True
    group_customization: true

option

Словарный тип вида ключ/значение (key/value dictionary). Ключи отображаются в веб-интерфейсе, а соответствующие им значения хранятся в базе данных.

Пример конфигурационного параметра типа option
Пример конфигурационного параметра типа option
config:
  - name: taskmanager.network.bind-policy
    description: "The automatic address binding policy used by the TaskManager"
    type: option
    option: {"name": name, "ip": ip}

password

ВАЖНО
Если пользователь установил значение по умолчанию для параметра конфигурации типов password, secretfile и secretmap, то при обновлении бандла миграция значений по умолчанию выполняться не будет.

Аналогичен типу string. Помимо того, что в веб-интерфейсе отображается в виде поля для ввода паролей (с маскированием символов), значение хранится в базе данных в зашифрованном виде.

Пример конфигурационного параметра типа password
Пример конфигурационного параметра типа password
config:
  - name: AUTH_LDAP_BIND_PASSWORD
    description: "The password of the bind user"
    type: password

secretfile

Файл в файловой системе, в котором хранится содержимое параметра конфигурации в незашифрованном виде. При обращении к переменной из скрипта Ansible она возвращает полный путь к файлу. В отличие от типа file, в веб-интерфейсе отображается в маскированном виде, а значение хранится в базе данных в зашифрованном виде.

Пример конфигурационного параметра типа secretfile
Пример конфигурационного параметра типа secretfile
config:
  - name: adcc_private_key_file
    display_name: Server private key
    description: Insert your own private key. Put the contents of the *.key file here.
    type: secretfile
    required: false

secretmap

Динамический словарь пар ключ/значение произвольной величины. Ключи и значения должны быть строками. В отличие от типа map, значения пар маскируются и хранятся в базе данных в зашифрованном виде.

  - name: chproxy_users_creds
    display_name: "Users/password map"
    description: "Map with 'username: password'. For example: 'my_user: password1'"
    required: False
    type: secretmap

selection_group

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

ВАЖНО
Для указанного типа дочерние параметры конфигурации первого уровня могут быть только типа group.
config:
  - name: catalog.manager
    type: selection_group
    default: static
    subs:
      - name: static
        type: group
        subs:
          - name: "catalog.config-dir"
            type: list
            default: ["/etc/catalog/"]
      - name: dynamic
        type: group
        subs:
          - name: "catalog.store"
            type: string
            default: "file"

string

Произвольная строка. Размер строки не ограничен. Значение по умолчанию — пустая строка ("").

Пример конфигурационного параметра типа string
Пример конфигурационного параметра типа string
config:
  - name: AUTH_LDAP_SERVER
    description: "The LDAP server URI"
    type: string

structure

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

Пример конфигурационного параметра типа structure
Пример конфигурационного параметра типа structure

При каждом обновлении конфигурации новые данные сравниваются со спецификацией. Если входные данные не соответствуют спецификации, ADCM выдает ошибку.

Элемент root является корневым и должен располагаться первым в спецификации конфигурации.

Корневой элемент конфигурации, который должен быть первым описан в спецификации, носит название root. Для дальнейшего описания атрибутов используется элемент match, который выполняет функцию типа данных. Возможные значения:

  • dict

  • list

В зависимости от значения match описываются атрибуты следующего уровня:

  • items — для значения dict;

  • item — для значения list.

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

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

match

string

Да

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

item

string

Да, для значения list

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

items

key/value pairs

Да, для значения dict

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

required_items

list

Нет

Список обязательных элементов объекта. Применяется при присвоении match значения dict

invisible_items

list

Нет

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

default_item

string

Нет

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

Тип Описание

string

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

boolean

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

integer

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

Пример конфигурации:

config:
  - name: cluster_config
    display_name: Cluster Configuration
    type: structure
    yspec: cluster_conf.yml
    required: False

Файл спецификации cluster_conf.yml:

---
    root:
      match: dict
      items:
        cluster: cluster

    cluster:
      match: list
      item: cluster_list

    cluster_list:
      match: dict
      items:
        cluster_name: string
        shards: shards
      required_items:
        - cluster_name

    shards:
      match: list
      item: shard_list

    shard_list:
      match: dict
      items:
        weight: integer
        shard_id: string
        internal_replication: bool
        replicas: replicas
      required_items:
        - weight
        - internal_replication
      invisible_items:
        - shard_id

    replicas:
      match: list
      item: replica_list

    replica_list:
      match: dict
      items:
        host: string
        replica_id: string
      required_items:
        - host
      invisible_items:
        - replica_id

    string:
      match: string

    integer:
      match: int

    bool:
      match: bool

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

yspec: ./schema.yaml

text

Аналогичен типу string, но веб-интерфейсе отображается в виде многострочного текстового поля.

Пример конфигурационного параметра типа text
Пример конфигурационного параметра типа text
config:
  - name: custom_xml
    display_name: "Advanced custom XML"
    description: |
      Custom core server settings for ClickHouse specified in the XML format.
      The parameters must comply with the XML rules applied in the Clickhouse configuration files.
      The entered configuration is displayed as is.
      The number of indents from the beginning of the line is carried over unchanged.
    type: text
    default: |
       <clickhouse>
       </clickhouse>
    required: False
    ansible_options:
      unsafe: True

variant

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

Пример конфигурационного параметра типа variant
Пример конфигурационного параметра типа variant
config:
  - name: yarn.classpath.include-user-jar
    display_name: "yarn.classpath.include-user-jar"
    description: "Defines whether user-jars are included in the system class path as well as their positioning in the path."
    type: variant
    source:
      type: inline
      strict: true
      value:
        - DISABLED
        - FIRST
        - LAST
        - ORDER
    default: ORDER

Чтобы получить список вариантов, вы можете воспользоваться встроенными функциями 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:
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней