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

2GIS CLI позволяет разделить получение артефактов установки на два этапа.
- Загрузка артефактов установки из интернета (режим
pull
) - Установка сервисов из загруженных артефактов (режим
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
В режиме license
утилита запросит файл лицензии с серверов 2ГИС и запишет его в выбранное хранилище. Подробнее см. Установка сервиса лицензий.
Режим pull
В режиме pull
утилита выполнит загрузку актуальных артефактов установки с серверов обновления 2ГИС в выбранное хранилище и (при необходимости) в реестр Docker.
При использовании файловой системы в качестве хранилища (настройка storage.type: fs
) утилита 2GIS CLI также создаёт файл манифеста manifests/latest.json
, содержащий информацию обо всех сервисах. Файл манифеста можно использовать при последующих запусках 2GIS CLI в режиме restore
с аргументом --from-dir
или --by-manifest
.
Если в режиме pull
передан аргумент --services
, то утилита загрузит артефакты установки только для указанных сервисов. Обратите внимание, что даже при использовании этого аргумента информация в файле манифеста будет обновлена для всех сервисов.
Режим restore
В режиме restore
утилита выполнит загрузку артефактов установки, которые уже хранятся в файловой системе-источнике, в выбранное хранилище и (при необходимости) в реестр Docker. Артефакты должны быть предварительно загружены в файловую систему-источник с помощью режима pull.
Обратите внимание, что при использовании файловой системы в качестве целевого хранилища (настройка storage.type: fs
) запуск утилиты в режиме restore
требует монтирования двух папок: исходной и целевой. Подробнее см. в справке по командам и аргументам.
Зависимости
Для работы с утилитой 2GIS CLI вам понадобится:
-
Лицензия на программный комплекс 2ГИС, которая позволяет получать артефакты установки, связанные с приобретёнными продуктами 2ГИС.
Чтобы получить лицензию, заполните форму на dev.2gis.ru/order.
-
Хост с установленным Docker Engine. На этом хосте будет работать 2GIS CLI.
Для работы утилиты в режимах
license
илиpull
этот хост должен иметь доступ в интернет (до серверов 2ГИС). -
В зависимости от выбранного типа хранилища:
- S3-совместимое хранилище артефактов установки.
- Свободное место на файловой системе хоста, предназначенного для 2GIS CLI.
-
Реестр Docker, если он будет использоваться для хранения Docker-образов.
Сценарии использования
Ниже приведены несколько примеров файлов конфигурации и команд запуска утилиты 2GIS CLI.
Более полная документация, включая все доступные настройки, приведена в разделах Конфигурационный файл 2GIS CLI и Справка по командам и аргументам 2GIS CLI.
Важное примечание:
Все пароли в этом разделе приведены в иллюстративных целях.
При реальной установке рекомендуется использовать более сложные и надёжные пароли.
pull в S3-хранилище
-
Создайте файл конфигурации
dgctl-config.yaml
:dgctl-config.yaml
key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB log-format: json storage: type: s3 host: artifacts.storage.local bucket: dgctl-store access-key: AKIAIOSFODNN7EXAMPLE secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY docker: registry: username: registry-user password: DOCKERregistryP@ssW0rd server-address: http://docker.registry.local:5000 image-prefix: /
-
Запустите одну из следующих команд:
-
Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ -v /var/run/docker.sock:/var/run/docker.sock \ 2gis/dgctl:latest \ pull --config=/dgctl-config.yaml --version=1.4.5 --apps-to-registry
-
Чтобы загрузить все артефакты в хранилище, включая Docker-образы:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ 2gis/dgctl:latest \ pull --config=/dgctl-config.yaml --version=1.4.5
-
pull в файловую систему
-
Создайте файл конфигурации
dgctl-config.yaml
:dgctl-config.yaml
key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB log-format: json storage: type: fs directory: /dgctl-source docker: registry: username: registry-user password: DOCKERregistryP@ssW0rd server-address: http://docker.registry.local:5000 image-prefix: /
-
Запустите одну из следующих команд:
-
Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ -v /var/run/docker.sock:/var/run/docker.sock \ 2gis/dgctl:latest \ pull --config=/dgctl-config.yaml --version=1.4.5 --apps-to-registry
-
Чтобы загрузить все артефакты в хранилище, включая Docker-образы:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ 2gis/dgctl:latest \ pull --config=/dgctl-config.yaml --version=1.4.5
-
restore в S3-хранилище
-
Создайте файл конфигурации
dgctl-config.yaml
:dgctl-config.yaml
key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB log-format: json storage: type: s3 host: artifacts.storage.local bucket: dgctl-store access-key: AKIAIOSFODNN7EXAMPLE secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY docker: registry: username: registry-user password: DOCKERregistryP@ssW0rd server-address: http://docker.registry.local:5000 image-prefix: /
-
Запустите одну из следующих команд:
-
Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ -v /var/run/docker.sock:/var/run/docker.sock \ 2gis/dgctl:latest \ restore --config=/dgctl-config.yaml --version=1.4.5 --from-dir=/dgctl-source --apps-to-registry
-
Чтобы загрузить все артефакты в хранилище, включая Docker-образы:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ 2gis/dgctl:latest \ restore --config=/dgctl-config.yaml --version=1.4.5 --from-dir=/dgctl-source
-
restore в файловую систему
-
Создайте файл конфигурации
dgctl-config.yaml
:dgctl-config.yaml
key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB log-format: json storage: type: fs directory: /dgctl-target docker: registry: username: registry-user password: DOCKERregistryP@ssW0rd server-address: http://docker.registry.local:5000 image-prefix: /
-
Запустите одну из следующих команд:
-
Чтобы загрузить Docker-образы в реестр, а все прочие артефакты - в хранилище:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ -v /mnt/dgctl-target:/dgctl-target \ -v /var/run/docker.sock:/var/run/docker.sock \ 2gis/dgctl:latest \ restore --config=/dgctl-config.yaml --version=1.4.5 --from-dir=/dgctl-source --apps-to-registry
-
Чтобы загрузить все артефакты в хранилище, включая Docker-образы:
docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v /mnt/dgctl-source:/dgctl-source \ -v /mnt/dgctl-target:/dgctl-target \ 2gis/dgctl:latest \ restore --config=/dgctl-config.yaml --version=1.4.5 --from-dir=/dgctl-source
-