Инфраструктурный бандл

Аделя Звягинцева

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

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

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

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

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

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

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

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

  1. Создайте конфигурационный файл config.yaml, который является обязательной частью инфраструктурного бандла и используется ADCM при создании и управлении объектами.

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

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

      • name — внутреннее имя хостпровайдера, используемое для обращения к нему;

      • type — тип объекта (в данном случае для хостпровайдера указывается значение provider);

      • version — версия хостпровайдера;

    • опциональные свойства:

      • display_name — имя прототипа хостпровайдера, отображаемое в веб-интерфейсе ADCM;

      • description — описание прототипа хостпровайдера;

      • edition — издание хостпровайдера; допустимо любое строковое значение, например, community или enterprise;

      • license — путь к файлу лицензионного соглашения, которое пользователь обязан принять при создании хостпровайдера (полный текст соглашения отображается на странице бандла);

      • adcm_min_version — минимальная поддерживаемая версия ADCM для работы с бандлом;

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

      • venv — версия Ansible, которая будет использоваться при запуске действий (action) хостпровайдера.

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

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

        - type: provider
  name: SSH Common
  version: &version '3.0.1-1'
  description: "Simple ssh hosts"
  adcm_min_version: "2.2.0"

  3. Чтобы обеспечить возможность управления конфигурацией хостпровайдера, в описание хостпровайдера добавьте блок config. К указанным параметрам конфигурации хостпровайдера можно обращаться из Ansible playbook (параметры добавляются в inventory-файл в {{ vars.provider.config }}). Для получения подробной информации о структуре inventory-файла обратитесь к статье Структура inventory-файла Ansible.

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

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

      config:
  - name: __main_info
    type: text
    default: >
      The main goal of SSH Common bundle is to quickly and easily
      manage hosts using Arenadata Cluster Manager.
      You can specify connection options for existing hosts
      to use them in cluster deployments.
    required: false
  - name: metadata
    display_name: Metadata
    type: group
    subs:
    - name: admin_ssh_keys
      display_name: "Ssh keys"
      type: list
      description: |
        List of openssh keys with user@hostname data at the end
        On create users hostprovider action user list will be parsed from keys
        and will be created with corresponding keys
      required: false
    - name: ansible_ssh_port
      display_name: "Port"
      type: string
      default: "22"
      description: "SSH port"
    - name: ansible_user
      display_name: "Username"
      type: string
      default: "root"
      required: false
      description: "Username used for SSH connection"

    где __main_info — специализированный служебный конфигурационный параметр, в качестве которого может использоваться HTML-файл.

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

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

    Пример блока описания действия Create users для хостпровайдера:

      actions:
    create_users:
      type: job
      script_type: ansible
      script: ansible/common_data/playbooks/create_user.yaml
      display_name: "Create users"
      allow_to_terminate: true
      params:
        ansible_tags: create_users
      states:
        available: *id001
    ПРИМЕЧАНИЕ
    Указанный Ansible playbook может использовать inventory-группы, которые генерируются в соответствии с топологией созданного пользователем хостпровайдера. Для получения подробной информации о группах inventory-файла обратитесь к статье Inventory-группы Ansible.
    Файл create_user.yaml
    ---

- name: "Create users"
  hosts: all
  tags: ["create_users"]
  gather_facts: yes
  tasks:
    - include_role:
        name: create_user
      loop: "{{ provider.config.metadata.admin_ssh_keys | to_users(additional_users_groups|default(None, true)) }} "
      loop_control:
        loop_var: user


- name: "Create user"
  hosts: HOST
  tags: ["create_user"]
  gather_facts: yes
  tasks:
    - name: "Import user role"
      import_role:
        name: create_user
      vars:
        user: "{{ job.config }}"

  5. Чтобы описать обновление хостпровайдера с одной версии бандла на другую, в описание хостпровайдера добавьте блок upgrade. Указанное обновление будет доступно в веб-интерфейсе ADCM в столбце Actions на странице Hostproviders. Для этого в блоке upgrade укажите следующие свойства:

    • name — внутренний идентификатор операции обновления.

    • description — текстовое описание операции обновления.

    • display_name — название операции обновления, отображаемое в веб-интерфейсе ADCM.

    • versions — допустимые версии для обновления хостпровайдера.

    • scripts (опционально) — последовательность запускаемых Ansible playbook, отображаемых на странице Jobs.

    • from_edition — список изданий хостпровайдера, для которых разрешено обновление.

    • states — состояния хостпровайдера:

      • available — список допустимых состояний хостпровайдера для проведения операции обновления.

      • on_success — состояние, в которое переходит хостпровайдер после успешного завершения операции обновления.

      • on_fail — состояние, в которое переходит хостпровайдер при аварийном завершении операции обновления.

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

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

          upgrade:
  - name: *version
    description: "That is not a disruptive update. Just metainfo is in upgrade process"
    versions:
      min: 1.0
      max_strict: *version
    states:
      available: any

  6. Хостпровайдер предназначен для создания хоста. Для реализации собственного хоста добавьте:

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

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

      • config — для управления конфигурацией хоста;

      • actions — для выполнения действий над хостом.

        ВАЖНО
        Обратите внимание, что для свойства type необходимо указать значение host.

        Пример блока описания хоста:

        - type: host
  name: SSH Common Host
  version: *version
  actions:
    ping:
      display_name: "Check connection"
      type: job
      script: ansible/ping.yaml
      script_type: ansible
      allow_to_terminate: true
      states:
        available: any
    statuschecker:
      display_name: "Install statuschecker"
      params:
        ansible_tags: statuschecker,instal,enable,start,configure
      states:
        available: any
      type: job
      script_type: ansible
      script: ansible/main.yaml
      allow_to_terminate: true
  config:
    __main_info:
      type: text
      default: >
        Please configure <b>Connection address</b> (if DNS does not work), <b>Username</b>,
        <b>Password</b> or <b>SSH private key</b> (if used instead of a password).
        And do not forget to run <b>Install statuschecker</b> action.
      required: false
    ansible_user:
      display_name: "Username"
      type: string
      default: "root"
      required: false
      description: "Username used for SSH connection"
    ansible_ssh_pass:
      display_name: "Password"
      type: password
      required: false
      description: "Ansible SSH password"
        Файл ping.yaml
        ---

- name: "Ping connection to host"
  hosts: "{{ job.hostname }}"
  tasks:
    - name: ping
      ping:

    # Note: In API v2, host state is managed automatically by ADCM
    # The adcm_state module has been removed as there is no direct API endpoint
    # State changes are handled through actions and ADCM internal logic
        Файл main.yaml
        ---

# Install status_checker
- name: "Install status_checker"
  hosts: "{{ groups.HOST[0] }}"
  gather_facts: no
  tasks:
    - include_role:
        name: status_checker
      vars:
        host_id: '{{ adcm_hostid }}'
        token: '{{ env.status_api_token }}'
        service_name: '{{ adcm_hostid }}'
        checker_type: hosts
      tags:
        - statuschecker
        - install
        - enable
        - start
        - configure

Ниже представлен финальный вариант конфигурационного файла config.yaml:

- type: provider
  name: SSH Common
  version: &version '3.0.1-1'
  description: "Simple ssh hosts"
  adcm_min_version: "2.2.0"
  upgrade:
  - name: *version
    description: "That is not a disruptive update. Just metainfo is in upgrade process"
    versions:
      min: 1.0
      max_strict: *version
    states:
      available: any
  actions:
    create_users:
      type: job
      script_type: ansible
      script: ansible/common_data/playbooks/create_user.yaml
      display_name: "Create users"
      allow_to_terminate: true
      params:
        ansible_tags: create_users
      states:
        available: *id001
  config:
  - name: __main_info
    type: text
    default: >
      The main goal of SSH Common bundle is to quickly and easily
      manage hosts using Arenadata Cluster Manager.
      You can specify connection options for existing hosts
      to use them in cluster deployments.
    required: false
  - name: metadata
    display_name: Metadata
    type: group
    subs:
    - name: admin_ssh_keys
      display_name: "Ssh keys"
      type: list
      description: |
        List of openssh keys with user@hostname data at the end
        On create users hostprovider action user list will be parsed from keys
        and will be created with corresponding keys
      required: false
    - name: ansible_ssh_port
      display_name: "Port"
      type: string
      default: "22"
      description: "SSH port"
    - name: ansible_user
      display_name: "Username"
      type: string
      default: "root"
      required: false
      description: "Username used for SSH connection"
- type: host
  name: SSH Common Host
  version: *version
  actions:
    ping:
      display_name: "Check connection"
      type: job
      script: ansible/ping.yaml
      script_type: ansible
      allow_to_terminate: true
      states:
        available: any
    statuschecker:
      display_name: "Install statuschecker"
      params:
        ansible_tags: statuschecker,instal,enable,start,configure
      states:
        available: any
      type: job
      script_type: ansible
      script: ansible/main.yaml
      allow_to_terminate: true
  config:
    __main_info:
      type: text
      default: >
        Please configure <b>Connection address</b> (if DNS does not work), <b>Username</b>,
        <b>Password</b> or <b>SSH private key</b> (if used instead of a password).
        And do not forget to run <b>Install statuschecker</b> action.
      required: false
    ansible_user:
      display_name: "Username"
      type: string
      default: "root"
      required: false
      description: "Username used for SSH connection"
    ansible_ssh_pass:
      display_name: "Password"
      type: password
      required: false
      description: "Ansible SSH password"
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней