Продуктовый бандл
В данной статье показан пример создания продуктового бандла для установки и развертывания кластера.
Чтобы создать продуктовый бандл, выполните следующие действия:
-
Создайте рабочий каталог бандла. В нем должны располагаться следующие файлы:
-
конфигурационный файл config.yaml или config.yml;
-
Ansible playbook, используемые для описания и запуска действий;
-
дополнительные файлы (библиотеки, служебная информация и т.д.).
-
Пример структуры каталога бандла:
<product_bundle_name>/ ├── ansible/ -- директория для Ansible, включающая Ansible playbook и роли; при организации структуры внутренних каталогов рекомендуется руководствоваться лучшими практиками ├── config.yaml -- конфигурационный файл └── ... -- дополнительные вспомогательные файлы и модули
-
Создайте конфигурационный файл config.yaml, который является обязательной частью продуктового бандла и используется ADCM при создании и управлении объектами.
-
В конфигурационный файл добавьте блок описания кластера. Для этого укажите:
-
обязательные свойства:
-
name— внутреннее имя кластера, используемое для обращения к нему; -
type— тип объекта (в данном случае для кластера указывается значениеcluster); -
version— версия кластера; -
venv— версия Ansible, которая будет использоваться при запуске действий (action) кластера; -
contract_version— версия контракта бандла;ПРИМЕЧАНИЕСвойствоcontract_versionдоступно начиная с версии ADCM 2.10.0.
-
-
опциональные свойства:
-
display_name— имя прототипа кластера, отображаемое в веб-интерфейсе ADCM; -
description— описание прототипа кластера; -
edition— издание кластера; допустимо любое строковое значение, например,communityилиenterprise; -
license— путь к файлу лицензионного соглашения, которое пользователь обязан принять при создании кластера (полный текст соглашения отображается на странице бандла); -
adcm_min_version— минимальная поддерживаемая версия ADCM для работы с бандлом; -
flag_autogeneration— свойство, предназначенное для управления автоматическим созданием встроенных флагов при изменении конфигурации кластера, сервисов и компонентов.ПРИМЕЧАНИЕДругие опциональные свойства, которые могут быть определены в блоке описания кластера, приведены в статье Обзор прототипов.Пример блока описания кластера:
- name: ADPG type: cluster description: Arenadata PostgreSQL version: &version 16.3_arenadata5.4_b1-1 edition: community license: adcm_cluster_eula/RUS_EULA_CE.txt adcm_min_version: 2.6.0 flag_autogeneration: enable_outdated_config: False venv: &venv_cluster "2.9"
-
-
-
Чтобы обеспечить возможность управления конфигурацией кластера, в описание кластера добавьте блок
config. К указанным параметрам конфигурации кластера можно обращаться из Ansible playbook (параметры добавляются в inventory-файл в{{ vars.cluster.config }}). Для получения подробной информации о структуре inventory-файла обратитесь к статье Структура inventory-файла Ansible.ПРИМЕЧАНИЕДополнительные сведения о свойствах, доступных при описании конфигурации кластера, можно найти в статье config.Пример блока описания конфигурационных параметров кластера:
config: - name: __main_info type: file default: adpg/info/cluster.html - name: repos display_name: "Centos 7 repositories" type: group subs: - name: use_adpg_repo display_name: Set up ADPG repo type: boolean default: true - name: adpg_core_repo display_name: ADPG CORE repo url type: string default: "https://downloads.arenadata.io/ADPG-CORE\ /16.3_arenadata5/centos/7/community/$basearch/" description: ADPG CORE repository - name: adpg_repo display_name: ADPG repo url description: "ADPG repository" type: string default: "https://downloads.arenadata.io/ADPG\ /16_arenadata4/centos/7/community/$basearch/"где
__main_info— специализированный служебный конфигурационный параметр, в качестве которого может использоваться HTML-файл. Содержимое файла отображается в секции Info на вкладке Overview страницы кластера. -
Чтобы выполнять различные действия над кластером, в описание кластера добавьте блок
actions. Указанные действия будут доступны в веб-интерфейсе ADCM на странице Clusters.ПРИМЕЧАНИЕДля получения подробной информации о свойствах, доступных при описании действий, обратитесь к статье actions.actions: Precheck: type: task scripts_jinja: jinja/scripts_jinja/cluster/precheck.j2 states: available: - created - ready to upgrade Install: &install_cluster allow_to_terminate: true type: task scripts: - name: Precheck ADPG Control agents script_type: ansible script: adpg/adpgc_agents.yaml params: actions: - precheck adcm_precheck_fail_when: true states: available: - created config: &auto_reboot auto_reboot: type: boolean default: true required: true display_name: Reboot cluster servers after installation description: | You will need to restart the cluster server manually after the installation is completed in order to apply some settings if you refuse automatic reloading.ПРИМЕЧАНИЕУказанный Ansible playbook может использовать inventory-группы, которые генерируются в соответствии с топологией созданного пользователем кластера. Для получения подробной информации о группах inventory-файла обратитесь к статье Inventory-группы Ansible.Файл adpgc_agents.yaml--- - name: Run config hosts: CLUSTER:!host_unreachable gather_facts: false roles: - role: config - name: ADPGC_AGENTS hosts: adpgc_agents:!host_unreachable gather_facts: true tasks: - name: Run adpg control agents include_role: name: adpgc_agents tags: always - name: Run statuschecker adpgc-agent when: adcm.config.global.adcm_url | default('') | length > 0 include_role: name: statuschecker vars: checker_type: services service_name: "adpgc-agent.service" component_id: "{{ services.adpgc_agents.adpgc_agent.component_id }}" host_id: '{{ adcm_hostid }}' token: '{{ env.status_api_token }}' tags: always - name: Run statuschecker adbm-agent when: - adcm.config.global.adcm_url | default('') | length > 0 - groups['adpgc_agents.adbm_agent'] is defined include_role: name: statuschecker vars: checker_type: services service_name: "adbm-agent.service" component_id: "{{ services.adpgc_agents.adbm_agent.component_id }}" host_id: '{{ adcm_hostid }}' token: '{{ env.status_api_token }}' tags: always -
Чтобы описать обновление кластера с одной версии бандла на другую, в описание кластера добавьте блок
upgrade. Указанное обновление будет доступно в веб-интерфейсе ADCM в столбце Actions на странице Clusters. Для этого в блокеupgradeукажите следующие свойства:-
name— внутренний идентификатор операции обновления. -
description— текстовое описание операции обновления. -
display_name— название операции обновления, отображаемое в веб-интерфейсе ADCM. -
versions— допустимые версии для обновления кластера. -
scripts(опционально) — последовательность запускаемых Ansible playbook, отображаемых на странице Jobs. -
from_edition— список изданий кластера, для которых разрешено обновление. -
states— состояния кластера:-
available— список допустимых состояний кластера для проведения операции обновления. -
on_success— состояние, в которое переходит кластер после успешного завершения операции обновления. -
on_fail— состояние, в которое переходит кластер при аварийном завершении операции обновления.ПРИМЕЧАНИЕДля получения подробной информации об операции обновления обратитесь к статье upgrade.Также существует возможность указать несколько альтернативных сценариев обновления кластера. Ниже приведен пример для кластера ADB:
upgrade: - name: 6.29.1_arenadata1_b1 (community) description: | The cluster will be prepared for upgrade. During the upgrade process, the cluster will be stopped and started after the installation is completed. To start the upgrade, run the Update cluster action. from_edition: ['community'] versions: min: 6.0.0 max_strict: 6.29.1_arenadata1 scripts: - name: Pre-upgrade check script: adb/bundle_pre_check.yaml script_type: ansible on_fail: running - name: 6.29.1_arenadata1_b1 (community) description: Bundle functional upgrade from current edition from_edition: ['community'] versions: min: 6.29.1_arenadata1 max_strict: *versionФайл bundle_pre_check.yaml--- - name: Run upgrade precheck gather_facts: false hosts: CLUSTER:!host_unreachable roles: - role: config vars: config_run: - base - name: Proceed old pg hba gather_facts: true hosts: adb.master:!host_unreachable tasks: - name: Process old pg_hba include_role: name: adb_edit_pg_hba vars: adb_edit_pg_hba_action: upgrade_pghba when: "'pg_hba_customs' not in services.adb.config"
-
-
-
Кластер может включать в себя сервисы. Чтобы реализовать собственный сервис, добавьте:
-
блок описания сервисов, входящих в состав кластера, по аналогии с описанием самого кластера;
-
блоки (непосредственно в описании каждого сервиса по аналогии с описанием действий и конфигурации кластера):
-
config— для управления конфигурацией сервисов; -
actions— для выполнения действий над сервисами.ПРИМЕЧАНИЕ-
Конфигурация конкретного сервиса доступна через переменную
{{ vars.services.<service name>.config }}. В этом примере сервис ADPG использует{{ vars.services.adpg.config }}. -
Обратите внимание, что для свойства
typeнеобходимо указать значениеservice.
Пример блока описания сервиса:
- name: adpg display_name: ADPG type: service required: true description: "Arenadata Postgres" version: *version venv: *venv_cluster actions: Install: &install_service_adpg display_name: Install allow_to_terminate: true type: task scripts_jinja: jinja/scripts_jinja/services/adpg/install.j2 config_jinja: jinja/configs_jinja/common/auto_reboot.j2 states: available: - created - name: datadir display_name: Data directory description: >- Directories used to store data on hosts type: string required: true writable: [created] default: "/pg_data1" ansible_options: unsafe: True config: - name: __main_info type: file default: adpg/info/adpg.html - name: datadir display_name: Data directory description: >- Directories used to store data on hosts type: string required: true writable: [created] default: "/pg_data1" ansible_options: unsafe: True - name: sysctl_params_map display_name: Sysctl parameters [key:value] description: > Linux kernel parameters for ADPG. type: map required: false default: {}ПРИМЕЧАНИЕК конфигурации конкретного сервиса можно обратиться через переменную{{ vars.services.<service name>.config }}. В данном примере для сервиса ADPG используется{{ vars.services.adpg.config }}. -
-
-
-
Сервис без компонентов является фиктивным и не распределяется по хостам. Чтобы предоставить пользователю возможность разместить сервис на хостах, добавьте как минимум один компонент. Для этого:
-
добавьте блоки описания компонентов, входящих в состав сервиса, по аналогии с описанием самого сервиса;
-
непосредственно в описании каждого компонента определите блоки:
-
config— для определения его конфигурационных параметров и обеспечения централизованного управления конфигурацией, по аналогии с конфигурацией сервиса; -
actions— для выполнения действий над компонентом по аналогии с описанием действий сервиса.components: adpg: constraint: [1] constraint: [1,+] display_name: ADPG
-
-
Ниже представлен финальный вариант конфигурационного файла config.yaml:
- name: ADPG
type: cluster
description: Arenadata PostgreSQL
version: &version 16.3_arenadata5.4_b1-1
edition: community
license: adcm_cluster_eula/RUS_EULA_CE.txt
adcm_min_version: 2.6.0
flag_autogeneration:
enable_outdated_config: False
venv: &venv_cluster "2.9"
upgrade:
- name: 16.3_arenadata5.4_b1 (community) minor upgrade
description: |
The cluster will be prepared for upgrade. During the upgrade process,
the cluster will be stopped and started after the installation
is completed. To start the upgrade, run the Update cluster action.
scripts:
- name: Convert jinja configs adcm
script_type: ansible
script: adpg/convert_jinja_configs_adcm.yaml
- name: bundle upgrade
script_type: internal
script: bundle_switch
- name: Convert legacy configs
script_type: ansible
script: adpg/convert_legacy_configs.yaml
- name: Save previous ADPG configuration
script_type: ansible
script: adpg/save_previous_adpg_config.yaml
masking:
state:
available:
- installed
- ready to upgrade
on_success:
state: ready to upgrade
multi_state:
set:
- ready for minor upgrade CE
from_edition: [community]
versions:
min: '16.3_arenadata1'
max_strict: 16.3_arenadata5.4
actions:
Precheck:
type: task
scripts_jinja: jinja/scripts_jinja/cluster/precheck.j2
states:
available:
- created
- ready to upgrade
Install: &install_cluster
allow_to_terminate: true
type: task
scripts:
- name: Precheck ADPG Control agents
script_type: ansible
script: adpg/adpgc_agents.yaml
params:
actions:
- precheck
adcm_precheck_fail_when: true
states:
available:
- created
config: &auto_reboot
auto_reboot:
type: boolean
default: true
required: true
display_name: Reboot cluster servers after installation
description: |
You will need to restart the cluster server manually
after the installation is completed in order to apply
some settings if you refuse automatic reloading.
config:
- name: __main_info
type: file
default: adpg/info/cluster.html
- name: repos
display_name: "Centos 7 repositories"
type: group
subs:
- name: use_adpg_repo
display_name: Set up ADPG repo
type: boolean
default: true
- name: adpg_core_repo
display_name: ADPG CORE repo url
type: string
default: "https://downloads.arenadata.io/ADPG-CORE\
/16.3_arenadata5/centos/7/community/$basearch/"
description: ADPG CORE repository
- name: adpg_repo
display_name: ADPG repo url
description: "ADPG repository"
type: string
default: "https://downloads.arenadata.io/ADPG\
/16_arenadata4/centos/7/community/$basearch/"
- name: adpg
display_name: ADPG
type: service
required: true
description: "Arenadata Postgres"
version: *version
venv: *venv_cluster
actions:
Install: &install_service_adpg
display_name: Install
allow_to_terminate: true
type: task
scripts_jinja: jinja/scripts_jinja/services/adpg/install.j2
config_jinja: jinja/configs_jinja/common/auto_reboot.j2
states:
available:
- created
- name: datadir
display_name: Data directory
description: >-
Directories used to store data on hosts
type: string
required: true
writable: [created]
default: "/pg_data1"
ansible_options:
unsafe: True
config:
- name: __main_info
type: file
default: adpg/info/adpg.html
- name: datadir
display_name: Data directory
description: >-
Directories used to store data on hosts
type: string
required: true
writable: [created]
default: "/pg_data1"
ansible_options:
unsafe: True
- name: sysctl_params_map
display_name: Sysctl parameters [key:value]
description: >
Linux kernel parameters for ADPG.
type: map
required: false
default: {}
components:
adpg:
constraint: [1]
constraint: [1,+]
display_name: ADPG
- name: prometheus_monitoring
display_name: Monitoring
type: service
version: &monitoring_version 1.3.1
venv: "2.9"
components:
prometheus:
constraint: [0,1]
display_name: Prometheus Server
config:
- name: version
type: string
default: '2.39.2'
read_only: any
grafana:
constraint: [0,1]
display_name: Grafana
requires:
- component: prometheus
config:
- name: version
type: string
default: '9.5.8'
read_only: any