Сценарии использования

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

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

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

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

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

Базовые операции

pull в S3-хранилище

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 \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         pull --config=/dgctl-config.yaml --version=1.27.0 --apps-to-registry
     

   • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

     docker run --rm \
         -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
         -v /mnt/dgctl-source:/dgctl-source \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         pull --config=/dgctl-config.yaml --version=1.27.0
     

pull в файловую систему

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 \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         pull --config=/dgctl-config.yaml --version=1.27.0 --apps-to-registry
     

   • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

     docker run --rm \
         -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
         -v /mnt/dgctl-source:/dgctl-source \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         pull --config=/dgctl-config.yaml --version=1.27.0
     

restore в S3-хранилище

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 \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry
     

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

   • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

     docker run --rm \
         -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
         -v /mnt/dgctl-source:/dgctl-source \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         restore --config=/dgctl-config.yaml --from-dir=/dgctl-source
     

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

restore в файловую систему

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 \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry
     

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

   • Чтобы загрузить все артефакты в хранилище, включая Docker-образы:

     docker run --rm \
         -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
         -v /mnt/dgctl-source:/dgctl-source \
         -v /mnt/dgctl-target:/dgctl-target \
         --user $(id -u):$(id -g) \
         2gis/dgctl:latest \
         restore --config=/dgctl-config.yaml --from-dir=/dgctl-source
     

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

Использование системных сертификатов

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

Запуск в Docker

Чтобы обеспечить работу сертификата внутри Docker-контейнера с утилитой 2GIS CLI, добавляйте следующий аргумент во все команды запуска контейнера, чтобы подключить сертификат к утилите:

-v <path-to-cert>:/etc/ssl/cert.pem

Где <path-to-cert> — путь к установленному сертификату.

Пример полной команды для запуска утилиты с системным сертификатом безопасности:

docker run -it \
    -v <path-to-cert>:/etc/ssl/cert.pem \
    -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
    -v /mnt/dgctl-source:/dgctl-source \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --user $(id -u):$(id -g) \
    2gis/dgctl:latest \
    pull --config=/dgctl-config.yaml --version=1.27.0 --apps-to-registry

Запуск бинарного файла

При запуске бинарного файла утилиты вы можете получить ошибку следующего вида:

ERRO[0004] failed to upload object: unable to put object into s3

Это может свидетельствовать о проблемах с сертификатом для доступа к S3-совместимому хранилищу. Чтобы решить эту проблему:

1. Убедитесь, что эта проблема связана именно с сертификатом. Выполните следующую команду через S3cmd:

   s3cmd ls s3://bucket --host https://s3.my-host.com
   

   Примечание

   Для запуска S3cmd необходим конфигурационный файл с учетными данными для доступа к S3-хранилищу.

   Если вы получаете ошибку следующего вида, то проблема действительно связана с сертификатом:

   ERROR: SSL certificate verification failure: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1007)
   

2. Скачайте необходимый сертификат безопасности.

3. Установите сертификат в системе:

   Для UNIX-подобных систем (Linux, macOS):

   1. Запустите терминал.

   2. Скопируйте сертификат в системное хранилище сертификатов при помощи команды ниже:

      sudo cp /<path-to-cert>/sert.crt /usr/local/share/ca-certificates/
      

      Где <path-to-cert> — путь к скачанному сертификату.

   3. Обновите список доверенных сертификатов:

      sudo update-ca-certificates
      

   Для Windows:

   1. Откройте меню Пуск, начните вводить в поиске Управление сертификатами компьютьтера и выберите соответствующее приложение.
   2. В дереве папок слева выберите Личное -> Сертификаты.
   3. В верхнем меню выберите Действие -> Все задачи -> Импорт.
   4. Следуйте инструкциям мастера импорта сертификатов для установки скачанного сертификата.

Если сертификат установлен корректно, приложение будет соединяться с сервером без ошибок.