Обзор утилиты | 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 запускается в одном из двух режимов: pull или restore.

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

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

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

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

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

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

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

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

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

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

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

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

Ниже приведены несколько примеров файлов конфигурации и команд запуска утилиты 2GIS CLI.

Более полная документация, включая все доступные настройки, приведена в разделах Конфигурационный файл 2GIS CLI и Справка по командам и аргументам 2GIS CLI.

Важное примечание:

Все пароли в этом разделе приведены в иллюстративных целях.

При реальной установке рекомендуется использовать более сложные и надёжные пароли.

  1. Создайте файл конфигурации 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: /
    
  2. Запустите одну из следующих команд:

    • Чтобы загрузить 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
      
  1. Создайте файл конфигурации 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: /
    
  2. Запустите одну из следующих команд:

    • Чтобы загрузить 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
      
  1. Создайте файл конфигурации 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: /
    
  2. Запустите одну из следующих команд:

    • Чтобы загрузить 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
      
  1. Создайте файл конфигурации 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: /
    
  2. Запустите одну из следующих команд:

    • Чтобы загрузить 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