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	Нет	—	—

Для режимов license и 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.

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

  См. список названий компонентов и сервисов в справке по командам и аргументам 2GIS CLI.

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

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

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

подсказка

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

Режим restore

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

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

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

предупреждение

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

Режим save

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

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

предупреждение

Если вы используете режим 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-образов.