Перейти к основному содержимому

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

Ниже приведены несколько примеров файлов конфигурации и команд запуска утилиты 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.32.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.32.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.32.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.32.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.32.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. Следуйте инструкциям мастера импорта сертификатов для установки скачанного сертификата.

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