Обзор утилиты | On-Premise | 2GIS Documentation
On-Premise

2GIS CLI

Утилита 2GIS CLI (также известна как dgCtl) предназначена для получения файла с лицензией, а также для загрузки, сохранения и восстановления артефактов, которые необходимы для установки и обновления сервисов программного комплекса 2ГИС.

Артефакты установки включают в себя:

  • Docker-образы сервисов.
  • данные, необходимые для работы сервисов.

Подробнее о жизненном цикле артефактов установки см. здесь.

dgctl apps to registry argument behavior

2GIS CLI позволяет разделить получение артефактов установки на два этапа.

  1. Загрузка артефактов установки из интернета (режим pull)
  2. Установка сервисов из загруженных артефактов (режим restore)

В качестве хранилища артефактов могут быть использованы S3-совместимое хранилище или файловая система, см. настройку storage.type в конфигурационном файле.

При любом выбранном режиме и типе хранилища рекомендуется разделять артефакты установки с помощью аргумента --apps-to-registry (см. справку по командам и аргументам). В этом случае Docker-образы сервисов будут помещены в реестр Docker, а все прочие артефакты — в хранилище выбранного типа. Такой подход дает больше контроля над размещением артефактов и позволяет избежать их смешения.

2GIS CLI запускается в одном из следующих режимов: license, pull или restore.

Режим Нужен доступ в интернет Откуда загружать Типы целевых хранилищ
license Да Серверы лицензирования 2ГИС S3-совместимое хранилище
Файловая система
pull Да Серверы обновления 2ГИС S3-совместимое хранилище и реестр Docker
Файловая система и реестр Docker
restore Нет Файловая система S3-совместимое хранилище и реестр Docker
Файловая система и реестр Docker

В режиме license утилита запросит файл лицензии с серверов 2ГИС и запишет его в выбранное хранилище. Подробнее см. Установка сервиса лицензий.

Примечание

При использовании режима license на версии On-Premise 1.16.0 и ниже необходимо всегда использовать аргумент --with-license-v1 в командах.

В режиме pull утилита выполнит загрузку актуальных артефактов установки с серверов обновления 2ГИС в выбранное хранилище и (при необходимости) в реестр Docker. Утилита также записывает в лог размер выгрузки (образов сервисов, данных и т.д.) без учёта уже имеющихся в хранилище файлов (если не передан аргумент --overwrite).

При использовании файловой системы в качестве хранилища (настройка storage.type: fs) утилита 2GIS CLI также создаёт файл манифеста manifests/latest.json, содержащий информацию обо всех сервисах. Файл манифеста можно использовать при последующих запусках 2GIS CLI в режиме restore с аргументом --from-dir или --by-manifest.

Если в режиме pull передан аргумент --services, то утилита загрузит артефакты установки только для указанных сервисов. Обратите внимание, что даже при использовании этого аргумента информация в файле манифеста будет обновлена для всех сервисов.

Чтобы узнать ожидаемый размер выгрузки, передайте в режиме pull аргумент --dry-run. Утилита не выполнит загрузку артефактов, а только запишет размер в лог. Совместимо с аргументами --services, --only-apps и --only-data.

В режиме restore утилита выполнит загрузку артефактов установки, которые уже хранятся в файловой системе-источнике, в выбранное хранилище и (при необходимости) в реестр Docker. Артефакты должны быть предварительно загружены в файловую систему-источник с помощью режима pull.

Обратите внимание, что при использовании файловой системы в качестве целевого хранилища (настройка storage.type: fs) запуск утилиты в режиме restore требует монтирования двух папок: исходной и целевой. Подробнее см. в справке по командам и аргументам.

Примечание

При использовании режима restore на версии On-Premise 1.16.0 и ниже необходимо всегда использовать аргумент --with-license-v1, а также --only-apps, --only-data и --only-license в зависимости от загружаемых сущностей.

Для работы с утилитой 2GIS CLI вам понадобится:

  • Лицензия на программный комплекс 2ГИС, которая позволяет получать артефакты установки, связанные с приобретёнными продуктами 2ГИС.

    Чтобы получить лицензию, заполните форму на dev.2gis.ru/order.

  • Хост с установленным Docker Engine. На этом хосте будет работать 2GIS CLI.

    Для работы утилиты в режимах license или pull этот хост должен иметь доступ в интернет (до серверов 2ГИС).

  • В зависимости от выбранного типа хранилища:

    • S3-совместимое хранилище артефактов установки.
    • Свободное место на файловой системе хоста, предназначенного для 2GIS CLI.
  • Реестр Docker, если он будет использоваться для хранения Docker-образов.