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/no |
Нет |
Делает доступным изменение параметра через конфиг-группы |
|
Нет |
Определяются пользователем |
— |
Правило валидации для введенного значения конфигурационного параметра |
|
Нет |
См. ниже |
Нет |
Позволяет указать дополнительные настройки для параметра во время подготовки 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
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.
| Символ | Описание |
|---|---|
. |
Соответствует любому отдельному символу, кроме новой строки |
^ |
Соответствует началу текстовой строки |
$ |
Соответствует концу текстовой строки |
(…) |
Группирует серию регулярных выражений в одно регулярное выражение |
| |
Указывает на чередование и соответствует логическому оператору |
[abc] |
Соответствует любому символу из перечисленных |
[a-z] |
Соответствует любому символу из набора символов |
[^abc] |
Соответствует любому символу, кроме перечисленных |
[^a-z] |
Соответствует любому символу, не входящему в набор символов |
+ |
Указывает на то, что предыдущий символ или выражение могут входить в строку один или более раз |
* |
Указывает на то, что предыдущий символ или выражение могут входить в строку ноль или более раз |
? |
Указывает на то, что предыдущий символ или выражение могут входить в строку ноль или один раз |
+?, *?, ?? |
"Ленивые" (lazy) эквиваленты "жадных" (greedy) квантификаторов. "Ленивый" поиск, при котором предыдущий символ или выражение может встретиться в данной позиции:
|
(?!x), (?=x) |
Отрицательная и позитивная опережающая проверка (lookahead) |
{x} |
Поиск |
{x,y} |
Поиск не менее |
{x,} |
Поиск |
{x,}? |
"Ленивый" поиск |
{x,y}? |
"Ленивый" поиск не менее |
Если при создании нового бандла было добавлено свойство pattern, то следует учитывать, что существующие значения конфигурационных параметров (в объекте до обновления) могут не соответствовать заданному правилу валидации, указанному в свойстве pattern.
Ниже представлены три возможных подхода к решению этой проблемы.
-
Остановите обновление объекта, если значение конфигурационного параметра не соответствует правилу валидации.
-
При необходимости мигрируйте значение конфигурационного параметра.
-
Установите флаг, чтобы уведомить пользователя о необходимости изменить значение конфигурационного параметра самостоятельно.
Обратите внимание, что при использовании свойства 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
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 она возвращает полный путь к файлу.
Значение по умолчанию указывается как путь к файлу относительно корневой директории бандла. Содержимое файла доступно для редактирования через веб-интерфейс, при этом файл автоматически обновляется при сохранении конфигурации.
Данный тип подходит для безопасного хранения приватных 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.
Вы можете использовать опциональные параметры 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 также будут нулевыми.
|
ПРИМЕЧАНИЕ
Начиная с версии 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.
Вы можете использовать опциональные параметры 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 не сохраняется и может быть изменена при каждом обновлении конфигурации.
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
Динамический массив произвольной величины. Элементы массива должны быть строками. Любой элемент может быть добавлен, удален или изменен при каждом обновлении конфигурации.
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
Динамический словарь пар ключ/значение произвольной величины. Ключи и значения должны быть строками. Любой ключ или значение могут быть добавлены, удалены или изменены при каждом обновлении конфигурации.
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). Ключи отображаются в веб-интерфейсе, а соответствующие им значения хранятся в базе данных.
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. Помимо того, что в веб-интерфейсе отображается в виде поля для ввода паролей (с маскированием символов), значение хранится в базе данных в зашифрованном виде.
config:
- name: AUTH_LDAP_BIND_PASSWORD
description: "The password of the bind user"
type: password
secretfile
Файл в файловой системе, в котором хранится содержимое параметра конфигурации в незашифрованном виде. При обращении к переменной из скрипта Ansible она возвращает полный путь к файлу. В отличие от типа file, в веб-интерфейсе отображается в маскированном виде, а значение хранится в базе данных в зашифрованном виде.
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
Произвольная строка. Размер строки не ограничен. Значение по умолчанию — пустая строка ("").
config:
- name: AUTH_LDAP_SERVER
description: "The LDAP server URI"
type: string
structure
Тип, предназначенный для описания многоуровневых конфигураций. Число уровней не ограничено. Описание конфигураций осуществляется в соответствии со спецификацией, разобранной ниже.
При каждом обновлении конфигурации новые данные сравниваются со спецификацией. Если входные данные не соответствуют спецификации, ADCM выдает ошибку.
Элемент root является корневым и должен располагаться первым в спецификации конфигурации.
Корневой элемент конфигурации, который должен быть первым описан в спецификации, носит название root. Для дальнейшего описания атрибутов используется элемент match, который выполняет функцию типа данных. Возможные значения:
-
dict -
list
В зависимости от значения match описываются атрибуты следующего уровня:
-
items— для значенияdict; -
item— для значенияlist.
Перечни доступных атрибутов и значений match (типов элементов) приведены в таблицах ниже.
| Название | Тип | Обязательность | Описание |
|---|---|---|---|
match |
string |
Да |
Правило, согласно которому выполняются проверки других правил |
item |
string |
Да, для значения |
Правило, согласно которому проверяется каждый объект в случае, если |
items |
key/value pairs |
Да, для значения |
Правило, согласно которому проверяется каждый объект в случае, если |
required_items |
list |
Нет |
Список обязательных элементов объекта. Применяется при присвоении |
invisible_items |
list |
Нет |
Содержит элементы, которые могут использоваться в служебных целях и не видны пользователю |
default_item |
string |
Нет |
Правило, согласно которому дополнительно проверяется созданный пользователем элемент в объекте. Применяется при присвоении |
| Тип | Описание |
|---|---|
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, но веб-интерфейсе отображается в виде многострочного текстового поля.
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.
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: