actions

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

Action может состоять из одной или нескольких subjob.

Последовательность выполняемых subjob может быть задана одним из двух способов:

  • статически — с помощью свойства scripts;

  • динамически — с помощью свойства scripts_template.

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

  • config — статическое формирование списка параметров;

  • config_template — динамическое формирование списка параметров.

Для реализации более сложных сценариев конфигурирования action можно использовать свойство wizard_template.

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

Пример
---
- type: cluster
  name: control
  version: 1
  description: "Monitoring and Control Software"

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

allow_for_action_host_group

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

actions:
  install:
    display_name: "Install"
    scripts:
      - name: install_cluster
        script_type: ansible
        script: ansible/site.yaml
    allow_for_action_host_group: true

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

allow_in_maintenance_mode

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

allow_to_terminate

Action может содержать опциональное логическое свойство allow_to_terminate, управляющее возможностью принудительной остановки action и входящих в него job (задач). Значение по умолчанию — false. Если свойство allow_to_terminate принимает значение true, пользователь может прервать выполнение action. При этом:

  • При прерывании job завершается выполнение запущенной на текущий момент subjob (подзадачи), которая прерывает выполнение Ansible playbook, что приводит к завершению job.

  • При прерывании subjob (иконка skip default dark skip default light) прерывается выполнение Ansible playbook с запуском следующего subjob без завершения job.

Во всех остальных случаях остановка action запрещена.

Свойство allow_to_terminate применяется ко всем subjob, из которых состоит action. При прерывании одной из таких subjob выполнение action продолжается со следующей subjob. Таким образом, указание свойства allow_to_terminate для action эквивалентно указанию данного свойства для всех его subjob.

config

Свойство config определяет статический список параметров конфигурации. При запуске action в веб-интерфейсе ADCM значения указанных параметров будут запрошены у пользователя перед началом выполнения action.

Чтобы использовать в Ansible playbook введенные пользователем параметры, необходимо обращаться к ним по полному пути.

Для примера рассмотрим следующую конфигурацию:

actions:
  install:
    display_name: "Install"
    scripts:
      - name: install_cluster
        script_type: ansible
        script: ansible/site.yaml
    config:
      - name: restart_after_install
        type: boolean
      - name: sudo_password
        type: password

Чтобы Ansible playbook мог использовать введенные пользователем параметры, к ним можно обратиться в контексте inventory следующим образом:

"{{ job.config.restart_after_install }}"
"{{ job.config.sudo_password }}"

где job.config — путь до указанных параметров.

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

config_template

Action может содержать опциональное свойство config_template, которое указывает на файл в формате Jinja.

Свойство config_template предназначено для работы с динамическими конфигурационными параметрами. В этом случае под "динамическим" понимается параметр, способный отображаться (либо скрываться) в зависимости от определенных условий — другими словами, от топологии кластера (например, от того, добавлен ли тот или иной сервис в кластер). Во время получения метаданных об action (с помощью GET-запроса в API) рендерится файл в формате Jinja (шаблон Jinja2). При рендеринге шаблона формируется контекст, соответствующий inventory-файлу, за исключением изменений конфиг-групп, а также переменных и фактов, которые формирует Ansible во время выполнения playbook.

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

---
  actions:
    start:
      display_name: "Start"
      config_template:
        file:
          path: scripts_jinja/cluster/restart.j2
        engine:
          type: jinja2
      scripts_template:
        file:
          path: scripts_jinja/cluster/manage_install.j2
        engine:
          type: jinja2
      states:
        available:
          - installed

Файл 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
{% endif %}

Формат описания шаблонов (свойство <config|hc|scripts|wizard>_template) включает в себя следующие параметры:

  • file — файл, который используется в качестве шаблона и содержит следующие атрибуты:

    • path — путь к файлу с расширением .j2 или .py.

    • entrypoint — название функции callable() без указания пакета или модуля, которую необходимо вызвать. Используется, если engine принимает значение python.

  • engine — движок для обработки файла. Возможные значения: jinja2, python.

При описании шаблона 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"
}

display_name

Свойство display_name определяет короткое имя action, которое будет видно пользователю в веб‑интерфейсе ADCM.

hc_acl

Action может содержать опциональное свойство hc_acl. Это свойство задействуется при запуске action в веб-интерфейсе ADCM так, что перед стартом action у пользователя запрашивается новое распределение компонентов на хостах (host-component mapping).

actions:
  expand:
    display_name: "Expand"
    scripts:
      - name: expand_topology
        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.

host_action

Action может содержать опциональное логическое свойство host_action, предназначенное для определения области применения action — на уровне отдельного хоста. Значение по умолчанию — false. Если свойство host_action принимает значение true, action отображается в выпадающем списке действий на странице Clusters → <Cluster name> → Hosts → <Host name> → Host-Components. В этом случае action выполняется для выбранного хоста, и автоматически создается таргет-группа, содержащая только данный хост.

Целесообразно объявлять action (host_action: true) только в контексте компонента, так как такие action позволяют управлять конкретным компонентом на конкретном хосте.

actions:
  install:
    display_name: "Install"
    scripts:
      - name: install_host
        script_type: ansible
        script: action.yaml
    host_action: true

masking

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

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

ВАЖНО
Свойство masking несовместимо со свойством states, которое описано ниже.
---
actions:
  install:
    display_name: "Install Monitor Server"
    masking:
      # Action will be shown if both conditions under state and multi_state are met.
      state:
        available:
          # If the state equals to any of these, then the 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 any of these multistates are present, the 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_state_value"
      multi_state:
        set:
          - "multi_state3"
        unset:
          - "multi_state4"
    on_success:
      state: "new_state_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"

name

Свойство name определяет внутреннее имя action, которое уникально для каждого прототипа.

scripts

Action может содержать опциональное свойство scripts, предназначенное для статического формирования subjob. Порядок выполнения subjob соответствует последовательности их перечисления в свойстве scripts. Если один из скриптов завершается с ошибкой, то процесс выполнения subjob прерывается, а объект переводится в состояние, соответствующее значению on_fail.

Каждый subjob в генерируемой последовательности определяется набором свойств, приведенных ниже.

actions:
  install:
    display_name: "Install"
    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

scripts_template

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

После запуска action рендерится файл в формате Jinja (шаблон Jinja2) для формирования последовательности subjob. При рендеринге шаблона формируется контекст, соответствующий inventory-файлу, за исключением изменений конфиг-групп, а также переменных и фактов, которые формирует Ansible во время выполнения playbook (включая дополнительные детали action, в том числе то, что было введено и выбрано пользователем при конфигурировании action).

Формат описания соответствует унифицированному формату <config|hc|scripts|wizard>_template.

Свойство scripts_template является взаимоисключающим со свойством scripts (статическим формированием subjob).

actions:
  add_remove_components:
    display_name: "Add/remove components"
    scripts_template:
      file:
        path: scripts_template/manage_component_scripts.j2
      engine:
        type: jinja2

Файл manage_component_scripts.j2:

{%- if (groups['zookeeper.SERVER.add'] | length) > 0 %}
- name: zookeeper
  display_name: "Zookeeper"
  script_type: ansible
  script: ansible/playbooks/cluster/zookeeper_install.yaml
  params:
    ansible_tags: repo_add, install, configure, configure_main_info, start, bootstrap
{%- endif %}
{%- if (groups['zookeeper.SERVER.remove'] | length) > 0 %}
- name: zookeeper
  display_name: "Zookeeper"
  script_type: ansible
  script: ansible/playbooks/cluster/zookeeper_remove.yaml
  params:
    ansible_tags: stop, remove
{%- endif %}
- name: zookeeper
  display_name: "Zookeeper"
  script_type: ansible
  script: ansible/playbooks/cluster/zookeeper_install.yaml
  params:
    ansible_tags: configure

При описании шаблона 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"
}

states

Action может содержать опциональное свойство states, предназначенное для управления доступностью action и переходами состояний объекта в процессе его выполнения. Свойство задает перечень состояний, при которых action может быть запущен, а также состояния объекта после успешного или неудачного завершения action.

Свойство states определяет следующие состояния:

  • available — список состояний объекта, для которых доступен action;

  • on_success — состояние, в которое объект переводится при успешном завершении action;

  • on_fail — состояние, в которое объект переводится при завершении action с ошибкой.

Состояния on_success и on_fail опциональны. При их отсутствии состояние объекта не будет изменено после успешного либо неудачного завершения action.

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

  • created — первичное состояние, в котором объекты находятся сразу после создания;

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

ui_options

Блок ui_options позволяет настроить отображение и выполнение action в веб-интерфейсе ADCM. При наведении курсора на action в веб-интерфейсе появится всплывающее сообщение, указанное в поле disclaimer:

actions:
  install:
    display_name: "Install"
    scripts:
      - name: install_run
        script_type: ansible
        script: ansible/site.yaml
    ui_options:
       disclaimer: "Enter your disclaimer"

wizard_template

Action может содержать опциональное свойство wizard_template, которое представляет собой шаблон процесса (flow), формируемого в результате его рендеринга.

В отличие от свойства config, wizard_template позволяет:

  • разделить конфигурирование action на несколько логических этапов в виде модальных окон;

  • передавать контекст рендеринга шаблона между этапами;

  • сохранять состояния уже заполненных пользователем шагов.

Свойство wizard_template является взаимоисключающим со следующими свойствами:

  • config, предназначенным для работы со статическими конфигурационными параметрами;

  • config_template, предназначенным для работы с динамическими конфигурационными параметрами;

  • hc_acl, предназначенным для работы с host-component mapping.

Заданное свойство отображается в веб-интерфейсе ADCM в виде Wizard, который является этапом подготовки action до его запуска.

Процесс (flow) представляет собой последовательность из следующих элементов:

  • Этапы (stage) — контейнеры логически связанных шагов.

  • Шаги (step) — минимальные неделимые элементы процесса (process), выполняемого пользователем.

    ПРИМЕЧАНИЕ
    Процесс (process) возникает в результате нажатия пользователем на action в списке действий, доступных для работы с объектом.

Типы шагов:

  • Configuration — заполняемая пользователем конфигурация. Конфигурация динамически формируется во время рендеринга шаблона, указанного в свойстве config_template, при получении информации о шаге.

  • Operation — job, представляющая собой набор subjob, который запускается в результате выполнения шага. Набор subjob динамически формируется во время рендеринга шаблона, указанного в свойстве scripts_template, при выполнении конкретного шага. Пример описания шага типа operation приведен в файле manage_install.j2 (шаг check_kerberos этапа manage_kerberos_stage).

  • Mapping — правило распределения компонентов на хостах (host-component mapping). Шаблон правила и форма со значениями по умолчанию динамически формируются во время рендеринга шаблона, указанного в свойстве mapping_template, при получении информации о шаге.

    ВАЖНО
    В отличие от обычных action, при использовании Wizard автоматическое применение распределения компонентов на хостах к целевому кластеру не выполняется. В этом случае разработчику бандла необходимо самостоятельно сохранить распределение, заданное пользователем, вызвав hc_apply вне контекста процесса Wizard, то есть в рамках основной job соответствующего action.

Описание визуального представления Wizard в веб-интерфейсе ADCM приведено в статье Wizard.

Шаги типа operation предоставляют следующие возможности:

  • валидация значений конфигурационных параметров action, введенных пользователем;

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

Каждый этап включает в себя следующие параметры:

  • name — уникальное название этапа;

  • display_name — название этапа, которое отображается в веб-интерфейсе ADCM для пользователя;

  • steps — последовательность шагов.

При описании шага используются следующие атрибуты:

  • Общие атрибуты:

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

    • display_name — название шага Wizard, которое предназначено для использования в качестве названия шага модального окна.

    • description (опционально) — текстовое описание шага, раскрывающее его суть для пользователя.

  • Атрибут для шага типа configuration: config_template — шаблон для работы с динамическими конфигурационными параметрами.

  • Атрибуты для шага типа operation:

    • ui_options — атрибуты, специфичные для веб-интерфейса ADCM, в частности, button_name — название кнопки.

    • scripts_template — шаблон для динамического формирования последовательности subjob.

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

  • Атрибут для шага типа mapping: hc_template — шаблон для формирования правила распределения компонентов на хостах. Шаблон может включать:

    • component и service — название компонента и сервиса соответствующего объекта.

    • operation — тип выполняемой операции. Возможные значения:

      • add — расширение набора хостов.

      • remove — сокращение набора хостов.

Формат описания соответствует унифицированному формату <config|hc|scripts|wizard>_template.

На основе полученной информации об action (при наличии wizard_template) создается процесс (process).

  actions:
    install:
      display_name: "Install"
      allow_to_terminate: true
      scripts_template:
        file:
          path: scripts_jinja/cluster/manage_install.j2
        engine:
          type: jinja2
      wizard_template:
        file:
          path: wizard_jinja/manage_install.j2
        engine:
          type: jinja2
      states:
        available:
          - created
          - faulty_installed

Создание процесса, кроме всего прочего, включает в себя рендеринг файла, указанного в wizard_template, в результате чего формируется процесс (flow). При рендеринге шаблона формируется контекст, соответствующий inventory-файлу, за исключением изменений конфиг-групп, а также переменных и фактов, которые формирует Ansible во время выполнения playbook.

Файл wizard_jinja/manage_install.j2:

- name: manage_ssl_stage
  display_name: "Manage SSL"
  steps:
    - name: configure_ssl
      display_name: "Configure SSL"
      description: "SSL is required for secure connection"
      config_template:
        file:
          path: configs_jinja/manage_ssl.j2
        engine:
          type: jinja2
- name: manage_kerberos_stage
  display_name: "Manage Kerberos"
  steps:
    - name: configure_kerberos
      display_name: "Kerberos configuration"
      config_template:
        file:
          path: configs_jinja/manage_kerberos.j2
        engine:
          type: jinja2
    - name: check_kerberos
      display_name: "Check configuration"
      ui_options:
        button_name: Check
      scripts_template:
        file:
          path: scripts_jinja/cluster/save_config.j2
        engine:
          type: jinja2
{% if services.hdfs is defined and services.hdfs.state == 'created' %}
- name: hdfs_stage
  display_name: "Manage HDFS"
  steps:
    - name: configure_hdfs
      display_name: "Configure HDFS"
      config_template:
        file:
          path: configs_jinja/manage_hdfs.j2
        engine:
          type: jinja2
    - name: mapping
      display_name: "Fill host-component mapping"
      description: "Specify which hosts the service will be located on"
      hc_template:
        file:
          path: hc_jinja/manage_hdfs_hc_step.j2
        engine:
          type: jinja2
    - name: validate
      display_name: "Validate host-component mapping"
      ui_options:
        button_name: Validate
      scripts_template:
        file:
          path: scripts_jinja/validate_mapping.j2
        engine:
          type: jinja2
{% endif %}
{% if services.hdfs is defined and services.hdfs.state == 'created' %}
- name: hbase_stage
  display_name: "Manage HBase"
  steps:
    - name: validate
      display_name: "Validate host-component mapping"
      ui_options:
        button_name: Validate
      scripts_template:
        file:
          path: scripts_jinja/validate_mapping.j2
        engine:
          type: jinja2
{% endif %}
- name: save_stage
  display_name: "Save configuration"
  steps:
    - name: save_configuration
      display_name: "Check configuration"
      ui_options:
        button_name: Check
      scripts_template:
        file:
          path: scripts_python/cluster/check.py
          entrypoint: generate_scripts
        engine:
          type: python

Файл manage_ssl.j2:

- name: ssl_config
  display_name: "Enable SSL"
  type: group
{% if vars.cluster.config.ssl_config.enable_ssl %}
  activatable: true
{% else %}
  activatable: false
{% endif %}
  subs:
    - name: keystore_path
      display_name: "Keystore path"
      type: string
      default: "{{ cluster.config.ssl_default_config.keystore_path }}"
    - name: keystore_password
      display_name: "Keystore password"
      type: password

Файл manage_kerberos.j2:

- name: kerberos_config
  display_name: "Enable Kerberos"
  type: group
{% if vars.cluster.config.kerberos_config.enable_kerberos %}
  activatable: true
{% else %}
  activatable: false
{% endif %}
  subs:
    - name: keystore_password
      display_name: "Keystore password"
      type: password
      default: "{{ action.process.stages.manage_ssl_stage.configure_ssl.config.ssl_config.keystore_password }}"

Файл save_config.j2:

{% set ssl_key = "ssl_default_config/keystore_password" %}
- name: validate
  display_name: "Precheck"
  script_type: ansible
  script: some/playbook.yaml
  params:
    ansible_tags:
      - check
- name: state_2
  display_name: "State 2"
  script_type: internal
  script: config_apply
  params:
    changes:
      - object:
          type: cluster
        parameters:
{% if action.process.stages.manage_ssl_stage.configure_ssl.config.ssl_config.enable_ssl %}
          - key: "{{ ssl_key }}"
            value: "{{ action.process.stages.manage_ssl_stage.configure_ssl.config.ssl_config }}"
{% endif %}
{% if action.process.stages.manage_kerberos_wizard.config.kerberos_config.enable_kerberos %}
          - key: "kerberos_default_config/keystore_password"
            value: "{{ action.process.stages.manage_kerberos_stage.configure_kerberos.config.kerberos_config.keystore_password }}"
{% endif %}

Файл manage_hdfs_hc_step.j2:

{% raw %}
- service: hdfs
  component: namenode
  operation: add
- service: hdfs
  component: datanode
  operation: add
{% endraw %}

Файл manage_hdfs.j2:

- name: dfs_data_dir
  display_name: "DFS data dir"
  type: string
  default: {{ vars.services.hdfs.config.data_dir }}

Файл check.py:

def create_script_template(display_name, name, params, script, script_type):
    """Template for creating action dictionaries with consistent structure."""
    return {
        'display_name': display_name,
        'name': name,
        'params': params,
        'script': script,
        'script_type': script_type
    }

def generate_scripts(context: dict):
    cluster = context['cluster']
    action = context['action']
    script1 = create_script_template(
        display_name='Check',
        name='validate',
        params={'ansible_tags': ['check']},
        script='some/playbook.yaml',
        script_type='ansible'
    )

    script2_params = [{
        'object': {'type': 'cluster'},
        'parameters': [{
            'key': 'ssl_config',
            'value': action['process']['stages']['manage_ssl_stage']['configure_ssl']['config']['ssl_config']
        }]
    }]

    script2 = create_script_template(
        display_name='State 2',
        name='state_2',
        params=script2_params,
        script='config_apply',
        script_type='internal'
    )

    return [script1, script2]

  ### Return
  [{'display_name': 'Check',
  'name': 'validate',
  'params': {'ansible_tags': ['check']},
  'script': 'some/playbook.yaml',
  'script_type': 'ansible'},
   {'display_name': 'State 2',
  'name': 'state_2',
  'params': [{'object': {'type': 'cluster'},
              'parameters': [{'key': 'ssl_config', 'value': 'some_value'}]}],
  'script': 'config_apply',
  'script_type': 'internal'}]

Файл validate_mapping.j2:

- name: validate
  display_name: "Precheck"
  script_type: ansible
  script: some/playbook.yaml
  params:
    process:
      current_stage: {{ action.process.current.stage }}

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

ПРИМЕЧАНИЕ
  • При формировании контекста добавляются переменные из предыдущего шага, которые хранятся в словаре action.process.

  • Изменения, относящиеся к конкретному шагу, должны указываться в action.process.stages.<stage>.groups и использоваться только в рамках выполнения данного шага. Если в рамках процесса выполняются последовательные операции добавления и удаления одного и того же компонента на одном и том же хосте, такие операции не включаются в groups, поскольку они взаимно компенсируют друг друга. При этом соответствующие операции сохраняются в action.process.stages.<stage>.groups соответствующих шагов процесса.

"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": null  # 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",
   ]
   "hdfs.namenode.add": [
      "ke-test-hadoop-25.ru-central1.internal",
   ]
  "hdfs.datanode.add": [
      "ke-test-hadoop-25.ru-central1.internal",
   ]
},
"action": {
    "owner_group": "zookeeper",
    "name": "install",
    "process": {
        "current": {
            "step": "validate",
            "stage": "hbase_stage",
        },
        "stages": {
            "manage_ssl_stage": {
                "configure_ssl": {
                    "config": {
                        "ssl_config": {
                            "keystore_path": "/etc/security/ssl",
                            "keystore_password": "ANSIBLE_VAULT:...."
                        }
                    }
                }
            },
            "manage_kerberos_stage": {
                "configure_kerberos": {
                    "config": {
                        "kerberos_config": {
                            "keystore_password": "ANSIBLE_VAULT:...."
                        }
                    }
                }
            },
            "hdfs_stage": {
                "mapping": {
                    "groups": {
                        "hdfs.namenode.add": [
                            "ke-test-hadoop-25.ru-central1.internal",
                        ]
                        "hdfs.datanode.add": [
                            "ke-test-hadoop-25.ru-central1.internal",
                        ]
                    }
                }
            }
        }
    }
}

Свойства элементов scripts и scripts_template

Для описания subjob в scripts и scripts_template используются следующие свойства:

  • display_name

  • name

  • on_fail

  • params

  • script

  • script_type

display_name

Свойство display_name определяет имя subjob, которое отображается пользователю в веб-интерфейсе ADCM.

name

Свойство name определяет внутреннее имя subjob, уникальное в рамках данного action.

on_fail

Свойство on_fail определяет состояние, в которое объект переводится при завершении subjob с ошибкой.

params

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

Среди поддерживаемых параметров можно выделить ansible_tags. Параметр служит прямым эквивалентом аргумента --tags, который передается при запуске команды ansible‑playbook.

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

script

Свойство script может принимать одно из следующих значений в зависимости от значения свойства script_type:

  • путь к файлу скрипта, если свойство script_type принимает значение ansible. В приведенном выше примере действия install свойство script указывает путь к Ansible playbook, который находится в директории <bundle_root>/ansible/site.yaml. Вы можете использовать точку (.), чтобы указать путь к файлу скрипта. В этом случае поиск файла скрипта будет осуществляться в директории, которая содержит файл config.yaml:

    script: ./site.yaml
  • одна из встроенных функций ADCM, если свойство script_type принимает значение internal:

    • bundle_revert — эта функция возвращает состояние кластера, предшествующее моменту обновления. Состояние кластера включает его конфигурацию, набор всех сервисов, хостов и компонентов кластера, а также host-component mapping.

    • bundle_switch — эта функция обновляет все прототипы до новых версий. Она используется только для действия upgrade и не может использоваться для других action.

    • hc_apply — эта функция полезна, когда action включает hc_acl и возникает необходимость зафиксировать изменения host-component mapping независимо от результата завершения действия или после завершения определенного шага (subjob). Функция hc_apply фиксирует изменения host-component mapping в соответствии с полученными от пользователя данными. Используйте опциональный параметр params для фиксации частичных изменений. Другими словами, с помощью параметра params вы можете указать правило аналогично hc_acl (имена сервиса и компонента, а также операцию add или remove), которое зафиксирует часть host-component mapping, ассоциированную с указанным правилом.

      - name: apply hc
        script_type: internal
        script: hc_apply
        params:
          rules:
            - service: redis
              component: server
              action: add
            - service: redis
              component: server
              action: remove
    • config_apply — эта функция полезна, когда action включает wizard_template и возникает необходимость сохранить изменения значений конфигурационных параметров, например на основе данных, полученных от пользователя. Правило фиксации значений конфигурационных параметров и объектов необходимо указать с помощью параметра params, в котором описываются объект и в соответствии с типом объекта имена сервиса и компонента, а также множество пар ключ/значение.

      ПРИМЕЧАНИЕ
      Функция config_apply доступна начиная с версии ADCM 2.8.0.
      - name: save
        display_name: "Save configuration on target objects"
        script_type: internal
        script: config_apply
        params:
          changes:
            - object:
                type: cluster
              parameters:
                - key: "ssl_default_config/keystore_password"
                  value: "my_secret_value"
            - object:
                type: service
                service_name: "hive"
              parameters:
                - key: "core-site_xml/keystore_password"
                  value: "my_secret_value"
            - object:
                type: component
                service_name: "hive"
                component_name: "server"
              parameters:
                - key: "core-site_xml/keystore_password"
                  value: "my_value"
      - name: state_2
        display_name: "State 2"
        script_type: internal
        script: config_apply
        params:
          changes:
            - object:
                type: cluster
              parameters:
                - key: "{{ ssl_key }}"
                  value: "{{ action.process.stages.manage_ssl_stage.configure_ssl.config.ssl_config }}"
            - object:
                type: service
                service_name: "{{ roles_generic_args.service_name }}"
              parameters:
                - key: "{{ ssl_key }}"
                  value: "{{ action.process.stages.manage_ssl_stage.configure_ssl.config.ssl_config }}"
            - object:
                type: component
                service_name: "{{ roles_generic_args.service_name }}"
                component_name: "{{ roles_generic_args.component_name }}"
              parameters:
                - key: "{{ ssl_key }}"
                  value: "{{ action.process.stages.manage_ssl_stage.configure_ssl.config.ssl_config }}"
    • service_manage — функция, которая позволяет добавлять сервисы в кластер во время выполнения action. Поддерживается для action, объявленных на уровне кластера, сервиса или компонента, включая action, реализованных в виде Wizard. Не поддерживается при выполнении операции обновления (upgrade), а также для action, объявленных на уровне хостпровайдера, хоста и ADCM. Action, объявленные на уровне ADCM, доступны на странице Settings.

      ПРИМЕЧАНИЕ
      Функция service_manage доступна начиная с версии ADCM 3.0.0.

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

      • operation — тип операции. В текущей реализации поддерживается только значение add.

      • services — список сервисов для добавления в кластер. Каждый сервис описывается следующими атрибутами:

        • name — имя сервиса (обязательно).

        • parameters — список конфигурационных параметров сервиса в формате ключ/значение (опционально).

        • mapping — список правил host-component mapping (опционально). Каждое правило содержит:

          • component — имя компонента;

          • hosts — список хостов.

      - name: add services
        script_type: internal
        script: service_manage
        params:
          operation: add
          services:
            - name: adqmdb
              parameters:
                - key: "Cluster_configuration/replication_factor"
                  value: 2
              mapping:
                - component: adqmdb
                  hosts: ["host-1", "host-2"]
            - name: prometheus_monitoring
    • before_upgrade_clean — эта функция предназначена для уменьшения размера inventory-файла, что позволяет ускорить выполнение Ansible playbook.

      ВАЖНО
      Использовать функцию before_upgrade_clean следует только в том случае, если не предполагается последующий вызов функции bundle_revert. Контекст параметра before_upgrade необходим для восстановления состояния кластера до обновления.

      Функция очищает параметр before_upgrade у объектов ADCM, входящих в контекст выполнения action, сбрасывая его к значению по умолчанию ({"state": null}). В результате в inventory-файле последующей subjob параметр before_upgrade не содержит состояния кластера, сформированного до обновления. В зависимости от уровня action функция затрагивает следующие объекты:

      • кластер — кластер, его дочерние сервисы и их компоненты;

      • сервис — сервис и его компоненты;

      • компонент — компонент;

      • хостпровайдер — хостпровайдер и его хосты;

      • хост — хост.

      ПРИМЕЧАНИЕ
      Если для action задано свойство allow_for_action_host_group: true или host_action: true, то обработке подлежит только тот объект, на уровне которого объявлен action.

      Функция before_upgrade_clean доступна для обычных action и action, реализованных в виде Wizard, а также при выполнении операции обновления (upgrade). Функция может использоваться как при статическом (scripts), так и при динамическом (scripts_template) формировании subjob.

      upgrade:
        scripts:
          - name: upgrade_hdfs
            script_type: ansible
            script: ansible/site.yaml
            params:
              ansible_tags: install
              jinja2_native: true
          #......
          - name: delete_previous_state_metadata
            script_type: internal
            script: before_upgrade_clean

script_type

Свойство script_type определяет тип запускаемого скрипта. Возможные значения: ansible, internal.

Специальные action

Следующие специальные action могут быть запущены в веб-интерфейсе ADCM и на указанных конечных точках (endpoint):

  • adcm_turn_on_maintenance_mode

  • adcm_turn_off_maintenance_mode

  • adcm_host_turn_on_maintenance_mode

  • adcm_host_turn_off_maintenance_mode

  • adcm_delete_service

Пример описания специального action:

  actions:
    adcm_turn_on_maintenance_mode

Специальные действия должны быть описаны в соответствующих прототипах. В таблице ниже приведены специальные действия, доступные в ADCM, с указанием типа прототипа и описания.

Название действия Тип прототипа Описание

adcm_turn_on_maintenance_mode

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

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

adcm_turn_off_maintenance_mode

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

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

adcm_host_turn_on_maintenance_mode

Кластер

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

adcm_host_turn_off_maintenance_mode

Кластер

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

adcm_delete_service

Сервис

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

Специальные action, которые описаны в прототипе кластера (adcm_host_turn_on_maintenance_mode и adcm_host_turn_off_maintenance_mode), должны быть также объявлены для хоста (host_action: true).

ВАЖНО
Специальные action не поддерживаются для свойств config, hc_acl и ui_options.
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней