2GIS CLI

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

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

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

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

Архитектура

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

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

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

Вы можете использовать аргументы --only-apps, --only-data и --only-license, чтобы выполнять операции только над определённым типом артефактов: образами приложений, данными или лицензией соответственно. Также вы можете комбинировать эти аргументы, чтобы выбрать несколько типов артефактов.

Режимы работы

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

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

Для режимов licence и pull доступ в интернет нужен только для обращения по следующим адресам:

• datagateway.api.2gis.com — для получения файла лицензии и файла манифеста;
• origin-disk.2gis.com — для получения файлов приложений и данных.

Режим license

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

Общий процесс получения лицензии включает в себя запросы к S3-совместимому хранилищу и работу через интернет:

1. Сервис лицензий генерирует файлы для запроса лицензии и размещает их в S3-совместимом хранилище.
2. Утилита 2GIS CLI считывает эти файлы из S3, формирует из них запрос и отправляет его через интернет.
3. По итогам обработки запроса возвращается лицензия, которую утилита 2GIS CLI записывает в S3-совместимое хранилище.
4. Сервис лицензий считывает файл лицензии и обновляет своё состояние.

Примечание

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

Режим pull

В режиме pull утилита выполняет следующие операции:

• Загружает актуальные артефакты установки с серверов обновления 2ГИС в выбранное хранилище и (при необходимости) в реестр Docker.

  Если передан аргумент --services, утилита загружает артефакты установки только для указанных сервисов. См. список названий сервисов в справке по командам и аргументам 2GIS CLI.

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

• Записывает в лог размер выгрузки (образов сервисов, данных и т. д.) без учёта уже имеющихся в хранилище файлов (если не передан аргумент --overwrite).

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

• Создаёт файл манифеста в формате JSON, содержащий информацию обо всех сервисах, и размещает его в выбранном хранилище в директории /manifests.

  Файл манифеста можно использовать при последующих запусках 2GIS CLI в режиме pull с аргументом --by-manifest.

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

Режим restore

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

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

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

Примечание

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

Режим save

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

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

Примечание

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

Режим manifest

Режим manifest используется для работы с манифестами в S3-совместимом хранилище при чистке старых данных.

Зависимости

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

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

  Чтобы получить лицензию, см. инструкцию.

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

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

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

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

• Реестр Docker, если он будет использоваться для хранения Docker-образов.