Продуктовый бандл

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

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

  1. Создайте рабочий каталог бандла. В нем должны располагаться следующие файлы:

    • конфигурационный файл config.yaml или config.yml;

    • Ansible playbook, используемые для описания и запуска действий;

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

Пример структуры каталога бандла:

<product_bundle_name>/
├── ansible/        -- директория для Ansible, включающая Ansible playbook и роли; при организации структуры внутренних каталогов рекомендуется руководствоваться лучшими практиками
├── config.yaml     -- конфигурационный файл
└── ...             -- дополнительные вспомогательные файлы и модули
  1. Создайте конфигурационный файл config.yaml, который является обязательной частью продуктового бандла и используется ADCM при создании и управлении объектами.

  2. В конфигурационный файл добавьте блок описания кластера. Для этого укажите:

    • обязательные свойства:

      • 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"
  3. Чтобы обеспечить возможность управления конфигурацией кластера, в описание кластера добавьте блок 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 страницы кластера.

  4. Чтобы выполнять различные действия над кластером, в описание кластера добавьте блок actions. Указанные действия будут доступны в веб-интерфейсе ADCM на странице Clusters.

    ПРИМЕЧАНИЕ
    Для получения подробной информации о свойствах, доступных при описании действий, обратитесь к статье actions.

    Пример блока описания действий Precheck и Install:

      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
  5. Чтобы описать обновление кластера с одной версии бандла на другую, в описание кластера добавьте блок 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"
  6. Кластер может включать в себя сервисы. Чтобы реализовать собственный сервис, добавьте:

    • блок описания сервисов, входящих в состав кластера, по аналогии с описанием самого кластера;

    • блоки (непосредственно в описании каждого сервиса по аналогии с описанием действий и конфигурации кластера):

      • 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 }}.
  7. Сервис без компонентов является фиктивным и не распределяется по хостам. Чтобы предоставить пользователю возможность разместить сервис на хостах, добавьте как минимум один компонент. Для этого:

    • добавьте блоки описания компонентов, входящих в состав сервиса, по аналогии с описанием самого сервиса;

    • непосредственно в описании каждого компонента определите блоки:

      • 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
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней