Утилита для управления установкой AW¶

awctl - утилита с интерфейсом командной строки, предназначенная для управления установками AW.

Поддерживаемые версии AW¶

Версия awctl	Поддерживаемые версии AW
1.6.4	1.18 - 1.29
1.7.0	1.18 - 1.32
1.7.1	1.18 - 1.32
1.7.2	1.18 - 1.32

Термины¶

профиль - именованная конфигурация установки AW на один или несколько серверов

Директории¶

В процессе работы awctl использует следующие директории и файлы:

Директории:

$HOME/.awctl - основная директория в которой храняться данные
$HOME/.awctl/releases - директория в которой хранятся выпуски AW
$HOME/.awctl/profiles - директория в которой хранятся конфигурационные файлы для профилей

Файлы:

$HOME/.awctl.yml - основной конфигурационный файл, содержит пути к директориям где храняться выпуски AW и конфигурационные файлы профилей
$HOME/.awctl/profiles/<имя_профиля>/config.yml - конфигурационный файл профиля

Установка¶

Утилита awctl написана на ЯП Python, скомпилирована в исполняемый файл с помощью компилятора nuitka и распространяется в формате rpm и deb пакетов, пригодных для автономной установки на дистрибутивы Linux. awctl рассчитан на запуск с рабочего компьютера администратора под управлением Linux. Для работы под управлением ОС Windows 10, 11 рекомендуется использовать систему WSL.

Загрузить установочный пакет можно по ссылке.

Для установки awctl нужно скопировать пакет на целевой компьютер и выполнить следующую команду:

для дистрибутивов Linux на основе rpm пакетов: sudo rpm -i <путь_к_пакету>
для дистрибутивов Linux на основе deb пакетов: sudo dpkg -i <путь_к_пакету>

Установка выполняется в директорию /opt/awctl Команда для запуска: /opt/awctl/awctl

Начальная настройка¶

При первом запуске awctl, например /opt/awctl/awctl list,, например /opt/awctl/awctl list, создаст файл $HOME/.awctl.yml с начальным конфигом и директорию $HOME/.awctl с поддиректориями. Для успешного продолжения работы нужно убедиться что следующие опции присутствуют в файл и их значения корректны:

aw_registry: registry.analyticworkspace.ru/aw
registry_user: ''
registry_password: ''
download_url: https://registry.analyticworkspace.ru/release/
download_user: ''
download_password: ''

Принцип работы¶

На основе файла конфигурации $HOME/.awctl/profiles/<имя_профиля>/config.yml awctl создает директории для каждого хоста, описанного в конфигурации, и формирует три файла:

docker-compose.yml - содержит сервисы, их переменные и тома для запуска на соответствующем хосте,
docker-compose.prod.yml - содержит список Docker - образов для запуска сервисов на соответствующем хосте,
.env - переменные для сервисов.

В процессе работы awctl старается автоматически разрещать зависимости между сервисами т.е. назначать экспортируемые порты и подставляеть адреса в случае необходимости.

Команды¶

awctl list¶

Выводит список доступных профилей

awctl init¶

/opt/awctl/awctl init <имя_профиля> выполняет следующие действия:

проверяет наличие скачанных релизов, находит последний и запоминает версию,
если скачанных релизов нет, то получает список доступных релизов с сервера, запоминает версии последнего доступного,
если скачанных релизов нет, то скачивает последний доступный,
создает директорию $HOME/.awctl/profiles/<имя_профиля>,
создает конфигурационный файл $HOME/.awctl/profiles/<имя_профиля>/config.yml с минимальной конфигураций на основе версии релиза полученной на предудущих шагах.

Дополнительные опции:

--version - задает версию AW на основе которой инициализировать профиль
--release-path - путь к, заранее загруженному, архиву с релизом, если опция установлена то --version и --release-type игнорируются
--release-type - тип релиза inet или full (автономная установка), применяется при наличие доступа к регистри
--preset - преподготовленный шаблон распределения сервисов для распределенной установки на 2, 3 или 4 сервера

awctl md¶

/opt/awctl/awctl md <имя_профиля> - предназначена для предварительного создания каталогов для установки AW. Полезно при настройки NFS для распределенной установки

awctl gen¶

/opt/awctl/awctl gen <имя_профиля> предназначена для генерации конфигурационных для установки AW, выполняет следующие действия:

читает конфигурацию из файла $HOME/.awctl/profiles/<имя_профиля>/config.yml,
проверяет скачан ли релиз AW версии указанной в config.yml,
скачивает релиз AW соответствующей версии если необходимо,
на основе config.yml подготавливает файлы конфигурации для установки AW для каждого хоcта.

awctl download¶

/opt/awctl/awctl download <имя_профиля> - скачивает релиз AW версии указанной в config.yml.

awctl install¶

/opt/awctl/awctl install <имя_профиля> - выполняет установку на хост\хосты:

считывает config.yml,
для каждого хоста в config.yml создает директорию указанную в параметре aw_home,
для каждого хоста в config.yml копирует файлы из $HOME/.awctl/profiles/<имя_профиля>/<имя_хоста> в aw_home,
для каждого хоста в config.yml копирует файлы из $HOME/.awctl/releases/<версия_AW>/ в aw_home,
для каждого хоста в config.yml выполняет авторизацию в docker registry,
для каждого хоста в config.yml запускает на исполненне скрипт aw_home/create_project_dirs.sh для создания необходимых директорий,
для каждого хоста в config.yml запускает на исполнение команду docker-compose pull для загрузки образов,
для каждого хоста в config.yml останавливает запущенные контейнеры AW если такие есть,
для каждого хоста в config.yml запускает новые контейнеры.

Дополнительные опции:

--host - позволяет запустить установку только для определенного хоста
--config-only - выполняет только копирование сгенерированных конфигурационных файлов

awctl migrate¶

/opt/awctl/awctl migrate <имя_профиля> - выполняет миграции для сервисов etl-api и backend:

считывает config.yml,
находит хост на котором запущен сервис backend,
подключается но ssh и запускает на исполнение команду миграции БД,
находит хост на котором запущен сервис etl-api,
подключается но ssh и запускает на исполнение команду миграции.

awctl pull¶

/opt/awctl/awctl pull <имя_профиля> - для каждого хоста из config.yml выполняет загрузку docker-образов AW.

Дополнительные опции:

--host - позволяет запустить скачивание образов только для определенного хоста

awctl start¶

/opt/awctl/awctl start <имя_профиля> - для каждого хоста из config.yml выполняет запуск контейнеров AW (docker-compose up -d --force-recreate)

Дополнительные опции:

--host - позволяет выполнить запуск контейнеров только для определенного хоста

awctl stop¶

/opt/awctl/awctl stop <имя_профиля> - для каждого хоста из config.yml выполняет остановку контейнеров AW (docker-compose down -v)

Дополнительные опции:

--host - позволяет остановить контейнеры только на определенном хосте

awctl restart¶

/opt/awctl/awctl restart <имя_профиля> - для каждого хоста из config.yml выполняет последовательно остановку а затем запуск контейнеров AW.

Дополнительные опции:

--host - позволяет выполнить перезапуск контейнеров только на определенном хосте

awctl show¶

/opt/awctl/awctl show <имя_профиля> - выводит run-time конфигурацию профиля.

Формат конфигурационного файла профиля¶

config.yml - текстовый конфигурационный файл профиля в формате yaml на основе которого выполняется генерация установочных файлов и последующая установка AW. Файл состоит из двух секций: aw и hosts. Секция aw содержит общие настройки, применимые ко всем хостам, ниже приведен список доступных опций секции:

aw_version - строка содержащая число, версия AW для установки,
compose_file - строка, содержащая список docker-compose файлов с разделителем, пример 'docker-compose.yml:docker-compose.prod.yml',
docker_compose_separator - символ служащий расделителнм docker-compose файлов,
aw_rel_type - тип используемого архива, inet или full
aw_home - директория в которую будет произведена установка AW.
with_extra_hosts - строка, булевое - использовать extra_hosts для формирования DNS,
with_traefik - c версии 1.7.1, позволяет использовать traefik в качестве прокси сервера для сервисов распределенной установке, позволяет снизить кол-во экспортированных портов и у бирает необходимость исправлять порты пуллеров в базе.

Секция hosts сотержит перечень хостов, на которые будет произведена установка AW, с параметрами. Каждой хост должен содержать как минимум список сервисов AW для установки. Список параметров для хостов:

aw_host - строка, может содержать IP адрес или имя хоста, это значение будет использовано для установки подключения по SSH и как адрес для сервисов
aw_home - строка, полный путь к директории в которую будет производиться AW,
aw_ssh_user - строка, имя пользователя для подключения по ssh,
aw_ssh_host - строка, IP адрес или FQDN хоста для подключения по ssh,
aw_ssh_port - число, порт для подключения по ssh
aw_ssh_pass - пароль для подключения по SSH
dns - массив из адресов DNS серверов, будет добавлен с соответствующие секции в сгенерированном docker-compose файле,
env - массив типа ключ - значения для переопредления значения переменных окружения, пары будут записаны в сгенерированный .env файл,
services - список сервисов для установки на хост.

Пример config.yml для одного хоста:

aw:
  aw_compose_file: docker-compose.yml:docker-compose.prod.yml
  aw_docker_compose_separator: ':'
  aw_home: /opt/aw/app
  aw_install_type: docker-compose
  aw_rel_type: inet
  aw_version: '1.30'
hosts:
  aw:
    services:
    - frontend
    - backend
    - widget-export
    - clear-storage
    - model-changes
    - model-sync
    - websocket
    - puppeteer
    - db
    - pgbouncer
    - clickhouse-server
    - rabbitmq
    - memcached
    - etl-broker
    - etl-airflow-db
    - etl-airflow
    - etl-spark
    - etl-api
    - etl-data-preview
    - etl-tasks
    - java-puller
    - file-puller
    - odata-puller
    - etl-pusher
    - etl-stats
    - etl-mlflow
    - etl-mlflow-db
    - auth-bridge
    - data-master
    - minio
    - minio-init
    - diag
    - clickhouse-parser
    - preview
    - sender
    - file-builder
    - cron
    - swagger

Пример config.yml для установки на 3 хоста (backends, etl, clickhouse):

---
aw:
  aw_compose_file: docker-compose.yml:docker-compose.prod.yml
  aw_docker_compose_separator: ':'
  aw_home: /opt/aw/app
  aw_install_type: docker-compose
  aw_rel_type: inet
  with_extra_hosts: true
  aw_version: '1.30'
hosts:
  aw:
    aw_ssh_user: awuser
    aw_home: '/opt/aw/app'
    aw_host: 192.168.0.110
    dns:
      - 77.88.8.8
      - 77.88.8.1
    env:
      FRONTEND_URL: http://aw.example.ru
    services:
    - frontend
    - backend
    - widget-export
    - clear-storage
    - model-changes
    - model-sync
    - websocket
    - puppeteer
    - db
    - pgbouncer
    - rabbitmq
    - memcached
    - auth-bridge
    - data-master
    - minio
    - minio-init
    - diag
    - clickhouse-parser
    - preview
    - sender
    - file-builder
    - cron
    - swagger
  clk:
    aw_ssh_user: awuser
    aw_home: '/opt/aw/app'
    aw_host: 192.168.0.130
    services:
    - clickhouse-server
  etl:
    aw_ssh_user: awuser
    aw_home: '/opt/aw/app'
    aw_host: 192.168.0.120
    services:
    - etl-broker
    - etl-airflow-db
    - etl-airflow
    - etl-spark
    - etl-api
    - etl-data-preview
    - etl-tasks
    - java-puller
    - file-puller
    - odata-puller
    - etl-pusher
    - etl-stats
    - etl-mlflow
    - etl-mlflow-db