Установка 2ГИС Про

Пароли и ключи приведены для примера

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

1. Подготовьтесь к установке

1.1. Подготовьте сетевую инфраструктуру

Рекомендуемая инфраструктура для работы сервисов программного комплекса 2ГИС состоит из публичной и приватной сетей. В таблице ниже описан пример такой инфраструктуры с доменами example.com и example.local. Все компоненты должны быть развёрнуты в одном кластере Kubernetes, управляемом с хоста example.com.

Компонент инфраструктуры	Кто должен иметь доступ	Тип сети	Домены, используемые в документации
Инфраструктура доставки артефактов	Администратор инфраструктуры	Публичная	example.com example-external.com example-internal.com
Реестр Docker для хранения образов сервисов	Утилита 2GIS CLI с хоста example.com	Публичная	docker.registry.example.com
Хранилище артефактов установки	Утилита 2GIS CLI с хоста example.com	Публичная	artifacts.example.com
Фронтенды сервисов	Приложения и конечные пользователи в приватной сети	Приватная	*.example.com
Бэкенды сервисов	Другие сервисы и хранилища из всех подов кластера Kubernetes	Приватная	*.example.local
Хранилища данных	Другие сервисы и хранилища из всех подов кластера Kubernetes	Приватная	*.storage.example.local

Настройка доступа к реестру Docker

Если для развёртывания продукта используется Managed Kubernetes (Kubernetes as a Service), убедитесь, что доступ к реестру Docker настроен с использованием протокола HTTPS и сертификата, подписанного доверенным центром сертификации (например, Let’s Encrypt).

1.2. Добавьте Helm-репозиторий

Для установки каждого продукта 2ГИС используется Helm-чарт из репозитория программного комплекса 2ГИС. Добавьте этот репозиторий на хосте, с которого будут устанавливаться продукты. В примере выше это хост example.com.

1. Установите в кластер менеджер пакетов Helm. Для этого используйте официальные инструкции по установке.

2. Добавьте репозиторий с Helm-чартами 2ГИС:

   helm repo add 2gis-on-premise https://2gis.github.io/on-premise-helm-charts
   helm repo update

3. Проверьте, что Helm и репозиторий установлены верно, с помощью команды:

   helm search repo 2gis-on-premise

   Если вывод команды содержит непустой список чартов, то всё настроено корректно.

Установка без доступа к интернету

Если вы устанавливаете сервисы в закрытом контуре без доступа к интернету, убедитесь, что у вас есть доступ к Helm-чартам 2ГИС — например, можно предварительно загрузить их.

1.3. Получите артефакты установки

Настройте хосты

Пример архитектуры хостов On-Premise:

docker.registry.example.com

Этот хост будет обслуживать реестр Docker. Хост должен быть доступен в публичной сети: см. Подготовка сетевой инфраструктуры.

Чтобы настроить хост:

1. Установите операционную систему.

2. Установите реестр Docker.

   Реестр должен быть доступен по адресу https://docker.registry.example.com/.

   Кластер Kubernetes должен доверять этому реестру и иметь возможность скачивать образы из него. Для этого реестр должен быть настроен с корректным HTTPS-сертификатом.

3. Настройте аутентификацию в реестре по имени пользователя и паролю.

   Пример:

   • Имя пользователя: registry.
   • Пароль: DOCKERregistryP@ssW0rd.

artifacts.example.com

Этот хост будет обслуживать S3-совместимое хранилище артефактов установки. Хост должен быть доступен в публичной сети: см. Подготовка сетевой инфраструктуры.

Чтобы настроить хост:

1. Установите операционную систему.

2. Установите подходящее для ваших задач S3-совместимое хранилище. Рекомендуется использовать Ceph.

   Хранилище должно быть доступно по адресу https://artifacts.example.com/.

3. В установленном хранилище создайте бакет onpremise-artifacts нужного размера.

4. Назначьте бакету сервисный аккаунт с правами на чтение и запись.

   Для этого сервисного аккаунта сгенерируйте ключ, с помощью которого можно получить доступ к бакету.

   Пример:

   • Идентификатор ключа: AKIAIOSFODNN7EXAMPLE.
   • Секрет ключа: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY.

example.com

Этот хост будет обслуживать утилиту 2GIS CLI. Хост должен быть доступен в публичной сети: см. Подготовка сетевой инфраструктуры.

Чтобы настроить хост:

1. Установите операционную систему.

2. Установите Docker Engine.

3. Убедитесь, что хост может подключаться к ранее настроенным сервисам:

   • https://docker.registry.example.com/
   • https://artifacts.example.com/

Теперь вы можете загрузить артефакты установки.

Если один хост не может обеспечить одновременный доступ к публичной сети, реестру Docker и S3-совместимому хранилищу, настройте два хоста:

• example-external.com — с доступом в публичную сеть;
• example-internal.com — с доступом к https://docker.registry.example.com/ и https://artifacts.example.com/.

После этого вы можете загрузить артефакты установки с использованием двух хостов.

Загрузите артефакты установки

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

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

Для загрузки артефактов установки используется утилита 2GIS CLI. Перед запуском утилиты убедитесь, что у вашего пользователя есть права на запуск Docker без использования sudo. В обратном случае возникнут ошибки загрузки.

Использование одного хоста

1. Зайдите по SSH на хост example.com.

2. Создайте конфигурационный файл dgctl-config.yaml. В блоке components укажите версии всех компонентов, которые входят в вашу поставку. Подробное описание доступных параметров см. в описании конфигурационного файла 2GIS CLI.

   dgctl-config.yaml

   key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
   log-format: json
   
   storage:
     type: s3
     host: artifacts.example.com
     bucket: onpremise-artifacts
     access-key: AKIAIOSFODNN7EXAMPLE
     secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
   
   docker:
     registry:
       username: registry
       password: DOCKERregistryP@ssW0rd
       server-address: https://docker.registry.example.com
       image-prefix: /
   
   # Для утилиты версии 3
   components:
     core:
       version: <core-version>
     api-platform:
       version: <api-platform-version>

3. Загрузите артефакты установки в файловую систему с помощью утилиты 2GIS CLI:

   docker run --rm \
      -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v $(pwd)/values:/values \
      --user $(id -u):$(id -g) \
      2gis/dgctl:3 \
      pull --config=/dgctl-config.yaml --apps-to-registry --generate-values

   Загрузка артефактов может занять длительное время. Когда процесс завершится, в консольном выводе команды будет указан путь к файлам манифестов для всех компонентов. Пример: manifests/<компонент>/1640661259.json.

   При использовании флага --generate-values файл с параметрами конфигурации general.yaml будет сгенерирован и размещён в локальной директории, которая указана в аргументе -v <путь>:/values/<компонент>/ (в примере: -v $(pwd)/values:/values). Если не указать путь, файл удалится после запуска утилиты.

   Особенности версий 2GIS CLI

   Если вы используете:

   • утилиту 2GIS CLI версии 2 — дополнительно укажите параметр --version с нужной версией программного комплекса On-Premise;
   • утилиту 2GIS CLI версии 3.6 и выше — использовать аргумент -v /var/run/docker.sock:/var/run/docker.sock не требуется.

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

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

При использовании двух хостов загрузите артефакты установки с серверов обновления 2ГИС и перенесите их в S3-совместимое хранилище. Для этого вы можете использовать утилиту 2GIS CLI (рекомендуется) или другой клиент для работы с S3.

1. Зайдите по SSH на хост example-external.com.

2. Создайте директорию для скачивания артефактов установки. Вы можете сохранить путь к ней в переменной окружения COPY_DIR. Например:

   COPY_DIR=/mnt/dgctl-source

3. Создайте конфигурационный файл dgctl-config.yaml. В блоке components укажите версии всех компонентов, которые входят в вашу поставку. Подробное описание доступных параметров см. в описании конфигурационного файла 2GIS CLI.

   dgctl-config.yaml

   key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
   log-format: json
   
   storage:
     type: fs
     directory: /data
   
   # Для утилиты версии 3
   components:
     core:
       version: <core-version>
     api-platform:
       version: <api-platform-version>

4. Загрузите артефакты установки в файловую систему с помощью утилиты 2GIS CLI:

   docker run --rm \
      -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
      -v $COPY_DIR:/data \
      -v $(pwd)/values:/values \
      --user $(id -u):$(id -g) \
      2gis/dgctl:3 \
      pull --config=/dgctl-config.yaml --generate-values

   Загрузка артефактов может занять длительное время. Когда процесс завершится, в консольном выводе команды будет указан путь к файлам манифестов для всех компонентов. Пример: manifests/<компонент>/1640661259.json.

   При использовании флага --generate-values файлы с параметрами конфигурации general.yaml будут сгенерированы для каждого компонента и размещены в локальной директории, которая указана в аргументе -v <путь>:/values/<компонент>/ (в примере: -v $(pwd)/values:/values). Если не указать путь, файлы удалятся после запуска утилиты.

   Использование 2GIS CLI версии 2

   Если вы используете утилиту 2GIS CLI версии 2, дополнительно укажите параметр --version с нужной версией программного комплекса On-Premise. Подробнее см. в Справке по командам и аргументам 2GIS CLI.

5. Перенесите директорию COPY_DIR с example-external.com на example-internal.com.

6. Зайдите по SSH на хост example-internal.com.

7. Создайте конфигурационный файл dgctl-config.yaml. В блоке components укажите версии всех компонентов, которые входят в вашу поставку. Подробное описание доступных параметров см. в описании конфигурационного файла 2GIS CLI.

   dgctl-config.yaml

   key: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
   log-format: json
   
   storage:
     type: s3
     host: artifacts.example.com
     bucket: onpremise-artifacts
     access-key: AKIAIOSFODNN7EXAMPLE
     secret-key: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
   
   docker:
     registry:
       username: registry
       password: DOCKERregistryP@ssW0rd
       server-address: https://docker.registry.example.com
       image-prefix: /
   
   # Для утилиты версии 3
   components:
     core:
       version: <core-version>
     api-platform:
       version: <api-platform-version>

8. Загрузите артефакты установки в реестр Docker и S3-совместимое хранилище с помощью утилиты 2GIS CLI:

   docker run --rm \
      -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
      -v $COPY_DIR:/dgctl-source \
      -v /var/run/docker.sock:/var/run/docker.sock \
      --user $(id -u):$(id -g) \
      2gis/dgctl:3 \
      restore --config=/dgctl-config.yaml --from-dir=/dgctl-source --apps-to-registry

   Использование утилиты версии 3.6 и выше

   Если вы используете утилиту 2GIS CLI версии 3.6 и выше, использовать аргумент -v /var/run/docker.sock:/var/run/docker.sock не требуется.

Создайте секрет Kubernetes для доступа к реестру Docker

Этот секрет нужен, чтобы Helm, с помощью которого устанавливаются сервисы программного комплекса 2ГИС, мог получить доступ к Docker-образам, которые находятся в реестре. Без такого секрета любая операция, связанная с реестром, завершится неудачей.

Пример:

kubectl create secret docker-registry onpremise-registry-creds \
    --docker-server=docker.registry.example.com \
    --docker-username=registry \
    --docker-password=DOCKERregistryP@ssW0rd

2. Выполните предварительные шаги

1. Ознакомьтесь с:

   • архитектурой сервисов 2ГИС Про;
   • архитектурой программного комплекса 2ГИС;
   • системными требованиями.

2. Установите сервисы API-платформы:

   1. Сервис лицензий.

      После установки получите лицензию, проверьте её статус и сохраните endpoint сервиса лицензий.

   2. Сервис API-ключей.

      После установки получите:

      • cервисные токены для сервисов Tiles API, Catalog APIs, Isochrone API и 2ГИС Про;

      • API-ключ c доступом к сервисам MapGL JS API, Catalog APIs, Search API и Isochrone API.

        Сервис	Что получить	Где используется
        Tiles API	Сервисный токен	Конфигурация Tiles API.
        MapGL JS API	API-ключ	Параметр ui.mapgl.key в Pro UI.
        Catalog APIs	Сервисный токен и API-ключ	Конфигурация Catalog APIs и параметр catalog.key в Pro API.
        Isochrone API	Сервисный токен и API-ключ	Параметр navi.key в Pro API
        2ГИС Про	Сервисный токен	Конфигурация Pro API.

   3. API карт.

      Установите обязательные компоненты:

      • Tiles API — при установке задайте types[0].kind: web и укажите сервисный токен Map Tiles API для доступа к векторным данным, полученный на предыдущем шаге.
      • MapGL JS API — после установки сохраните endpoint сервиса и API-ключ для настройки Pro UI.

   4. API поиска.

      Установите обязательные компоненты:

      • Search API — после установки сохраните endpoint сервиса настройки Pro API.
      • Catalog APIs — укажите сервисный токен, полученный на предыдущем шаге. После установки сохраните endpoint сервиса и ключ Catalog APIs для настройки Pro API.

   5. API навигации.

      • Убедитесь, что в файле правил rules.yaml есть правило для Isochrone API. В параметре queries укажите тип запроса get_hull, а в routing — типы транспорта, для которых нужно рассчитывать зоны доступности. Можно добавить эти значения в подходящее существующее правило или создать отдельное:

        - name: isochrone
          queries: ["get_hull"]
          routing: ["driving", "pedestrian"]

      • Установите обязательные компоненты:

        • Navi-Castle;
        • Navi-Back;
        • Navi-Router — в параметре keys.apis.isochrone-api укажите сервисный токен Isochrone API;
        • Navi-Front.

      • После установки сохраните:

        • endpoint сервиса Navi-Front;
        • API-ключ для Isochrone API для настройки Pro API.

3. Соберите данные, заданные или полученные на предыдущих шагах:

   Объект	Пример значения	Как получить значение
   Endpoint реестра Docker для хранения образов сервисов	docker.registry.example.com	См. Получение артефактов установки
   Endpoint S3-совместимого хранилища артефактов установки	artifacts.example.com	См. Получение артефактов установки
   Имя бакета для хранения артефактов	onpremise-artifacts	См. Получение артефактов установки
   Идентификатор ключа для доступа к артефактам установки	AKIAIOSFODNN7EXAMPLE	См. Получение артефактов установки
   Секрет ключа для доступа к артефактам установки	wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY	См. Получение артефактов установки
   Endpoint сервиса лицензий	https://license	См. Установка сервиса лицензий
   Endpoint MapGL JS API	http://mapgl-js-api	См. Установка API для работы с картами
   Endpoint Catalog APIs	http://catalog-api	См. Установка API для работы с поиском
   Endpoint Search API	http://search-api	См. Установка API для работы с поиском
   Endpoint API навигации	http://navi-front	См. Установка API для работы с навигацией
   API-ключи	MAPGL_KEY CATALOG_KEY NAVI_KEY	См. Установка сервиса API-ключей

4. Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чартах:

   • Pro API,
   • Pro UI.

   Подробнее о том, как это сделать, см. в документе Системные требования.

   Используйте чарты, соответствующие версии 2ГИС Про

   Содержание Helm-чартов, описанное в данном разделе, актуально для последней версии 2ГИС Про (см. Релизы 2ГИС Про). Чтобы изучить параметры для предыдущих версий, откройте нужный values.yaml в GitHub и в списке тегов слева выберите тег Pro-<версия>.

5. Определите доменные имена для сервиса 2ГИС Про. Например:

   • Доменное имя для API-бэкенда: pro-api.example.com
   • Доменное имя для Permissions UI: pro-permissions-api.example.com
   • Доменное имя для фронтенда: pro-ui.example.com

3. Подготовьте инфраструктуру

Настройка аналогов из реестра Минцифры

Если вместо PostgreSQL и Apache Kafka вы используете аналоги из реестра Минцифры, для инструкций по их настройке обратитесь к официальной документации этих сервисов.

Настройте PostgreSQL

1. Разместите кластер PostgreSQL с доменным именем pro-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.

2. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).

3. Создайте пользователя баз данных и установите пароль для него:

   create user dbuser_pro password '';

4. Создайте базы данных, принадлежащие этому пользователю:

   create database onpremise_pro owner dbuser_pro;
   create database onpremise_pro_tasks owner dbuser_pro;

Настройте S3-хранилище

1. Разместите S3-совместимое хранилище с доменным именем pro-s3.storage.example.local в приватной сети. Предполагается, что хранилище работает на стандартном порту 80.

2. Создайте ключи для подключения к сервису. Запомните реквизиты.

   Пример:

   • Ключ доступа: AKIAIOSFODNN7EXAMPLE.
   • Секретный ключ: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY.

3. Определите названия бакетов, которые будут использоваться для сервиса.

   Пример:

   • Бакет с наборами данных, агрегатами и фильтрами (assetsDataBucket): assets.
   • Бакет с наборами данных, агрегатами и фильтрами, созданными пользователем (userAssetsDataBucket): user_assets.
   • Бакет с подготовленными данными слоя (layerDataBucket): layer_data.
   • Бакет для хранения снапшотов (snapshotBucket): snapshots.
   • Бакет для хранения статичных ресурсов (resourcesBucket): resources.

Настройте Elasticsearch

1. Разместите кластер Elasticsearch с доменным именем pro-elastic.storage.example.local в приватной сети. Предполагается, что кластер работает на порту 9200.

2. Создайте пользователя для подключения к сервису. Запомните его реквизиты.

   Пример:

   • Имя пользователя: elasticsearch.
   • Пароль: elasticsearch_password.

Настройте Apache Kafka

1. Разместите кластер Apache Kafka с доменным именем pro-kafka.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 9092.

2. Создайте пользователя для подключения к сервису. Запомните его реквизиты.

   Пример:

   • Имя пользователя: kafka.
   • Пароль: kafka_password.

3. (Рекомендуется) Настройте топики Apache Kafka следующим образом:

   Имя топика	Передаваемые данные	Рекомендуемые настройки
   kafka.importTasksTopic.name	Задачи на импорт пользовательских наборов данных	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880). Период хранения файла лога — 3 дня (retention.ms: 259200000). См. подробные рекомендации по выбору значения ниже. Формат сжатия — Gzip (compression.type: gzip).
   kafka.assetDataTopic.name	Объекты пользовательских наборов данных	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880). Период хранения файла лога — 5 дней (retention.ms: 432000000). См. подробные рекомендации по выбору значения ниже. Формат сжатия — Gzip (compression.type: gzip).
   kafka.permissionsTopic.name	Сообщения об изменении прав доступа	Максимальный размер сообщения — 5 Мб (max.message.bytes: 5242880). Период хранения файла лога — 1 день (retention.ms: 86400000). См. подробные рекомендации по выбору значения ниже. Формат сжатия — Gzip (compression.type: gzip).
   kafka.eventsTopic.name	Различные события	Максимальный размер сообщения — 20 Мб (max.message.bytes: 20000000). Период хранения файла лога — 1 день (retention.ms: 86400000). См. подробные рекомендации по выбору значения ниже. Максимальный размер данных для хранения — 500 Мб (retention.bytes: 524288000). Формат сжатия — Gzip (compression.type: gzip).

   Параметр retention.ms определяет гарантированное время хранения сообщений в Apache Kafka и используется как буфер на случай деградации или недоступности потребителей (consumers) и соответствующих сервисов. Значение параметра следует выбирать исходя из скорости обработки очереди и допустимого времени восстановления системы. Более высокое значение снижает риск потери данных при инцидентах, но избыточное увеличение не даёт дополнительной надёжности, при этом увеличивает расход дискового пространства и время восстановления кластера.

   Указанные значения параметра retention.ms — рекомендуемые, так как помогают сохранить баланс между надёжностью хранения данных и эксплуатационными затратами. Вы можете изменять значения, если это обосновано нагрузкой, архитектурными особенностями или требованиями к времени восстановления.

   Полное описание настроек см. в документации Apache Kafka.

4. Установите 2ГИС Про

Установите Pro API

1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

   Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

   values-pro-api.yaml

   dgctlDockerRegistry: docker.registry.example.com
   
   dgctlStorage:
     host: artifacts.example.com
     secure: true
     bucket: onpremise-artifacts
     accessKey: AKIAIOSFODNN7EXAMPLE
     secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
     manifest: manifests/pro/1640661259.json
     region: ''
     disablePayloadSigning: false
   
   api:
     ingress:
       enabled: true
       className: nginx
       annotations:
         nginx.ingress.kubernetes.io/proxy-body-size: 100m
         nginx.ingress.kubernetes.io/proxy-connect-timeout: '120'
         nginx.ingress.kubernetes.io/proxy-read-timeout: '120'
         nginx.ingress.kubernetes.io/proxy-send-timeout: '120'
         nginx.ingress.kubernetes.io/enable-cors: 'true'
         nginx.ingress.kubernetes.io/cors-allow-credentials: 'true'
         nginx.ingress.kubernetes.io/cors-allow-origin: 'https://pro-ui.example.com'
         nginx.ingress.kubernetes.io/cors-allow-methods: 'GET, PUT, POST, DELETE, PATCH, OPTIONS'
         nginx.ingress.kubernetes.io/cors-allow-headers: 'DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,x-share-token,x-auth-token,x-brand,pragma'
         nginx.ingress.kubernetes.io/proxy-buffer-size: 256k
         nginx.ingress.kubernetes.io/proxy-buffering: 'on'
         nginx.ingress.kubernetes.io/proxy-buffers-number: '4'
       hosts:
         - host: pro-api.example.com
           paths:
             - path: /
               pathType: Prefix
       tls: []
       # - hosts:
       #   - pro-api.example.com
       #   secretName: secret.tls
   
     pod:
       imagePullSecrets: [onpremise-registry-creds]
       resources:
         requests:
           cpu: 400m
           memory: 256M
         limits:
           cpu: 1
           memory: 1024M
     settings:
       licenseKey: ''
       corsOrigins: ''
       auth:
         url: https://keycloak.example.com
         apiKey: ''
         type: openid10
         userInfoEndpoint: realms/Pro/protocol/openid-connect/userinfo
         autoRegisterUsers: true
   
   permissions:
     ingress:
       className: nginx
       enabled: true
       hosts:
       - host: pro-permissions-api.example.com
         paths:
         - path: /
           pathType: Prefix
       tls:
       # - hosts:
       #   - pro-permissions-api.example.com
       #   secretName: secret.tls
     settings:
       auth:
         enabled: true
         apiKey: ''
         uiRequiredRoles:
         - permAdmin
       # Только для новых пользователей
       defaultPermissions:
         openProUi: true
         assets: ['*']
         territories: ['*']
         addUserAssets:
           allow: true
           quantity: 1000
           fileSize: 100
         isochrones: 1000
   
   authProvider:
     enabled: true
     schema: Basic
     host: https://pro-permissions-api.example.com
     allowedHosts:
     - ['*']
     # Если в параметре authProvider.schema указано значение Basic
     basic:
       users:
       - username: 'admin'
         password: 'password'
         roles:
         - 'permAdmin'
     # Если в параметре authProvider.schema указано значение Oidc
     oidc:
       authority: ''
       clientId: ''
       clientSecret: ''
       nameClaim: ''
       roleClaim: ''
   
   license:
     url: 'https://license.svc'
   
   s3:
     assetsDataBucket: 'pro-assets'
     userAssetsDataBucket: 'pro-userassets'
     layerDataBucket: 'pro-layers'
     snapshotBucket: 'pro-snapshot'
     resourcesBucket: 'pro-resources'
   
   postgres:
     api:
       rw:
         host: 'pro-postgresql.storage.example.local'
         port: 5432
         name: 'onpremise_pro'
         username: 'dbuser_pro'
         password: ''
       ro: {}
     tasks:
       rw:
         host: 'pro-postgresql.storage.example.local'
         port: 5432
         name: 'onpremise_pro_tasks'
         username: 'dbuser_pro'
         password: ''
       ro: {}
     permissions:
       rw:
         host: 'pro-postgresql.storage.example.local'
         port: 5432
         name: 'onpremise_pro'
         username: 'dbuser_pro'
         password: ''
       ro: {}
   
   kafka:
     bootstrapServers: 'kafka:9092'
     securityProtocol: SaslPlaintext
     createTopics: true
     sasl:
       mechanism: Plain
       username: kafka-user
       password: kafka-password
     assetTopicsReaderGroupId: pro.asset.gr
     importTasksTopic:
       name: pro.tasks
       readerGroupId: pro.import.gr
     assetDataTopic:
       name: pro.assetdata
     permissionsTopic:
       name: pro.permissions
       readerGroupId: pro.permissions.gr
     eventsTopic:
       name: pro.events
       readerGroupId: pro.events.gr
     refreshAssetsIntervalMinutes: 60
   
   elastic:
     username: ''
     password: ''
     secure: false
     nodes:
       - port: 9200
         host: pro-elastic.storage.example.local
   
   redis:
     host: 'redis.svc'
     port: '6379'
   
   catalog:
     url: 'http://catalog-api.svc'
     key: ''
   
   navi:
     url: 'http://navi-front.svc'
     key: ''
   
   search:
     url: 'http://search-api.svc'
   
   assetImporter:
     appName: asset-importer
     repository: 2gis-on-premise/pro-importer
     schedule: 0 18 * * *
     backoffLimit: 2
     successfulJobsHistoryLimit: 3
     failedJobsHistoryLimit: 3
     nodeSelector: {}
     settings:
       maxParallelJobs: 4
     startOnDeploy: true

   Где:

   • dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.

   • dgctlStorage: настройки доступа к хранилищу артефактов установки.

     • host: endpoint S3-совместимого хранилища артефактов установки в формате HOST:PORT.
     • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
     • bucket: имя бакета S3.
     • accessKey: идентификатор ключа для доступа к бакету S3.
     • secretKey: секретный ключ для доступа к бакету S3.
     • manifest: путь до файла с манифестом в формате manifests/pro/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
     • region: регион S3-совместимого хранилища.
     • disablePayloadSigning: отключить ли проверку целостности данных. Если S3-совместимое хранилище не поддерживает AWS Signature Version 4 streaming, значение должно быть true. Значение по умолчанию: false.

   • api: переменные окружения.

     • ingress: конфигурация ресурса Ingress. Адаптируйте приведённую конфигурацию для используемого вами Ingress. URL, указанный в параметре api.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

       • annotations: аннотации Kubernetes, предназначенные для настройки поведения nginx Ingress-контроллера.

         Если CORS обрабатывается Ingress-контроллером, настройте его независимо от settings.corsOrigins. Для этого укажите для nginx.ingress.kubernetes.io/cors-allow-credentials значение true, а в nginx.ingress.kubernetes.io/cors-allow-origin укажите источник запроса.

     • pod.imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

     • pod.resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.

     • settings.licenseKey: лицензионный ключ 2ГИС Про. Чтобы получить ключ, обратитесь к менеджеру 2ГИС или вашему поставщику.

     • settings.corsOrigins: политика CORS. Если значение пустое, любому источнику разрешается выполнять запросы к сервису Pro API. Значение * не поддерживается. Если CORS настраивается в Ingress или прокси, настройте разрешённые источники там: см. блок настроек api.ingress.annotations.

     • settings.auth: настройки сервиса аутентификации.

       • url: URL сервиса аутентификации.
       • apiKey: API-ключ для доступа к сервису аутентификации.
       • type: тип аутентификации. Возможные значения: openid10 для протокола OpenID 1.0/OAuth 2.0; urbi для внутреннего протокола Urbi.
       • userInfoEndpoint: путь к endpoint-у Userinfo.
       • autoRegisterUsers: регистрировать ли новых пользователей автоматически при первом входе.

   • permissions: настройки Permissions API.

     • ingress: конфигурация ресурса Ingress для Permissions API. Адаптируйте приведённую конфигурацию для используемого вами Ingress. URL, указанный в параметре permissions.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes.

       • enabled: включить ли Ingress для сервиса.
       • className: имя класса Ingress-контроллера.
       • hosts[0].host: доменное имя для Ingress.
       • hosts[0].paths[0].path: путь для Ingress.
       • hosts[0].paths[0].pathType: тип пути для Ingress.
       • tls: конфигурация TLS.

     • settings.auth.enabled: включить ли аутентификацию. Значение параметра должно быть согласовано со значением authProvider.enabled: либо оба со значением true, либо оба со значением false.

     • settings.auth.apiKey: ключ доступа к Permissions API для выполнения авторизованных действий. Обязателен, если у параметра permissions.settings.auth.enabled значение true.

     • settings.auth.uiRequiredRoles: роли пользователей, необходимые для доступа к Permissions UI. Значения должны совпадать с ролями, определёнными в конфигурации authProvider. Обязателен, если у параметра permissions.settings.auth.enabled значение true.

     • settings.defaultPermissions: настройки доступа по умолчанию для новых пользователей.

       • openProUi: доступ к Pro UI. Значение по умолчанию: true.
       • assets: список идентификаторов системных наборов данных, к которым предоставляется доступ. Значение ['*'] предоставляет доступ ко всем наборам данных.
       • territories: список идентификаторов территорий, к которым предоставляется доступ. Значение ['*'] предоставляет доступ ко всем территориям.
       • addUserAssets: блок настроек, который управляет возможностью добавления пользовательских наборов данных новыми пользователями.
       • isochrones: максимальное количество зон доступности, которые может создать пользователь.

   • authProvider: настройки поставщика аутентификации для Permissions UI.

     • enabled: использовать ли поставщика аутентификации. Значение параметра должно быть согласовано со значением permissions.settings.auth.enabled: либо оба со значением true, либо оба со значением false.

     • host: адрес хоста поставщика аутентификации. Должен указывать на URL Permissions Ingress. Обязателен, если у параметра authProvider.enabled значение true.

     • schema: схема аутентификации. Поддерживаемые значения: Basic, Oidc. Подробнее о настройке OIDC-поставщика см. в разделе Настройка внешнего поставщика аутентификации. Обязателен, если у параметра authProvider.enabled значение true.

     • allowedHosts: список разрешённых хостов. Значение ['*'] предоставляет доступ со всех хостов.

     • basic: настройки базовой аутентификации. Используется, если в параметре authProvider.schema указано Basic.

       • users[0].username: имя пользователя.
       • users[0].password: пароль пользователя.
       • users[0].roles: роли, назначаемые пользователю. Могут быть любыми. Параметры permissions.settings.auth.uiRequiredRoles и tasks.settings.auth.adminRequiredRoles должны ссылаться на роли, определённые здесь.

     • oidc: настройки аутентификации по протоколу OIDC. Используется, если в параметре authProvider.schema указано Oidc.

       • authority: URL OIDC-поставщика.
       • clientId: идентификатор клиента, зарегистрированного у OIDC-поставщика.
       • clientSecret: секрет клиента OIDC-поставщика.
       • nameClaim: название утверждения (claim), содержащего имя пользователя. Точное название зависит от конфигурации OIDC-поставщика.
       • roleClaim: название утверждения (claim), содержащего роли пользователя. Точное название зависит от конфигурации OIDC-поставщика.

   • license.url: URL сервиса лицензий.

   • s3: настройки доступа к S3-совместимому хранилищу.

     • assetsDataBucket: имя бакета S3 с подготовленными наборами данных, агрегатами и фильтрами.
     • userAssetsDataBucket: имя бакета S3 с наборами данных, агрегатами и фильтрами, созданными пользователем.
     • layerDataBucket: имя бакета S3 с подготовленными данными слоя.
     • snapshotBucket: имя бакета S3 для хранения снапшотов пошагового обновления данных.
     • resourcesBucket: имя бакета S3 для хранения статичных ресурсов.

   • postgres: настройки PostgreSQL.

     • api: настройки доступа к базе данных onpremise_pro для чтения и записи (postgres.api.rw) или только для чтения (postgres.api.ro).

       • host: имя или IP-адрес хоста.
       • port: номер порта.
       • name: имя базы данных.
       • username: имя пользователя базы данных.
       • password: пароль пользователя базы данных.

     • tasks: настройки доступа к базе данных onpremise_pro_tasks микросервиса для управления фоновыми задачами для чтения и записи (postgres.tasks.rw) или только для чтения (postgres.tasks.ro). Набор параметров аналогичен группе postgres.api, но используется отдельная база данных.

     • permissions: настройки доступа к базе данных onpremise_pro микросервиса для управления правами доступа (Permissions API) для чтения и записи (postgres.permissions.rw) или только для чтения (postgres.permissions.ro). Набор параметров аналогичен группе postgres.api, и используется та же база данных.

   • kafka: настройки Apache Kafka.

     • bootstrapServers: endpoints брокера Kafka. Пример: HOST1:PORT1,HOST2:PORT2.

     • securityProtocol: протокол безопасности Kafka. Доступные значения: Plaintext, SaslPlaintext.

     • createTopics: включить автоматическое создание топиков или нет.

     • sasl: настройки SASL.

       • mechanism: механизм SASL. Доступные значения: Plain, ScramSha256, ScramSha512.
       • username: имя пользователя SASL.
       • password: пароль пользователя SASL.

     • assetTopicsReaderGroupId: ID потребительской группы Kafka для чтения данных из стриминговых наборов данных.

     • importTasksTopic: настройки топика Kafka для задач импорта пользовательских наборов данных.

       • name: название топика.
       • readerGroupId: ID потребительской группы Kafka для чтения задач импорта.

     • assetDataTopic: настройки топика Kafka для объектов в пользовательских наборах данных.

       • name: название топика.

     • permissionsTopic: настройки топика Kafka для чтения событий, связанных с изменениями прав доступа.

       • name: название топика.
       • readerGroupId: ID потребительской группы Kafka для чтения данных о правах доступа.

     • eventsTopic: настройки топика Kafka для событий.

       • name: название топика.
       • readerGroupId: ID потребительской группы Kafka для чтения событий.

     • refreshAssetsIntervalMinutes: интервал обновления настроек для стриминговых наборов данных в минутах.

   • elastic: настройки Elasticsearch.

     • username: имя пользователя Elasticsearch.
     • password: пароль пользователя Elasticsearch.
     • secure: использовать ли HTTPS для работы с Elasticsearch. Значение по умолчанию: false.
     • nodes[0].host: адрес хоста Elasticsearch.
     • nodes[0].port: номер порта Elasticsearch.

   • redis: настройки Redis.

     • host: адрес хоста Redis. Пример: HTTP(S)://HOST.
     • port: номер порта.

   • catalog: настройки доступа к Catalog APIs.

     • url: URL-адрес Catalog APIs. Пример: HTTP(S)://HOST.
     • key: ключ доступа к Catalog APIs.

   • navi: настройки доступа к Isochrone API.

     • url: URL-адрес Isochrone API. Пример: HTTP(S)://HOST.
     • key: ключ доступа к Isochrone API.

   • search: настройки доступа к Search API.

     • url: URL-адрес Search API. Пример: HTTP(S)://HOST.

   • assetImporter: настройки cron-задания для импорта данных.

     • appName: имя cron-задания для импорта данных.
     • repository: адрес репозитория с Docker-образом.
     • schedule: расписание выполнения задания в cron-формате. Например: */10 * * * *.
     • backoffLimit: количество повторных попыток, после которых задание будет считаться неуспешным.
     • successfulJobsHistoryLimit: ограничение на размер истории выполненных заданий.
     • failedJobsHistoryLimit: ограничение на размер истории невыполненных заданий.
     • nodeSelector: селектор узлов Kubernetes.
     • settings.maxParallelJobs: количество заданий импорта, которые могут быть запущены одновременно.
     • startOnDeploy: импорт данных должен начинаться при установке или обновлении сервиса.

2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-pro-api.yaml:

   helm upgrade --install --version=VERSION --atomic --wait --timeout 3600s --values ./values-pro-api.yaml pro-api 2gis-on-premise/pro-api

   В параметре --version укажите нужную версию 2ГИС Про. Список версий см. в разделе Релизы 2ГИС Про.

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

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

Установите Pro UI

1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

   Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

   values-pro-ui.yaml

   dgctlDockerRegistry: docker.registry.example.com
   
   imagePullSecrets: [onpremise-registry-creds]
   
   dgctlStorage:
     host: artifacts.example.com
     secure: true
     bucket: onpremise-artifacts
     accessKey: AKIAIOSFODNN7EXAMPLE
     secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
     manifest: manifests/pro/1640661259.json
     region: ''
     disablePayloadSigning: false
   
   ui:
     auth:
       sso: true
       secure: true
     appTheme: 2gis
     appLocale: ru_RU
     whiteLabel:
       configUrl: "/static/theme/pro.json"
     appInitialMapCenter: '[37.64, 55.74]'
     publicS3Url: https://artifacts.example.com/
     styles:
       s3Bucket: 'pro-ui-styles'
       configUrl: 'https://artifacts.example.com/pro-ui-styles/config/production/styleConfig.json'
     api:
       url: 'https://pro-api.example.com/'
     mapgl:
       host: 'mapgl-js-api.example.com'
       key: ''
       styleUrl: 'https://artifacts.example.com/pro-ui-styles/styles/default/'
       stylePreview: ''
   
   resources:
     requests:
       cpu: 300m
       memory: 256Mi
     limits:
       cpu: 1
       memory: 384Mi
   
   ingress:
     enabled: true
     className: nginx
     hosts:
     - host: pro-ui.example.com
       paths:
       - path: /
         pathType: Prefix
     tls: []
     # - hosts:
     #   - pro-ui.example.com
     #   secretName: secret.tls
   
   stylesImporter:
     startOnDeploy: true

   Где:

   • dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.

   • imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

   • dgctlStorage: настройки доступа к хранилищу артефактов установки.

     • host: endpoint S3-совместимого хранилища артефактов установки в формате HOST:PORT.
     • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
     • bucket: имя бакета S3.
     • accessKey: идентификатор ключа для доступа к бакету S3.
     • secretKey: секретный ключ для доступа к бакету S3.
     • manifest: путь до файла с манифестом в формате manifests/pro/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
     • region: регион S3-совместимого хранилища.
     • disablePayloadSigning: отключить ли проверку целостности данных. Если S3-совместимое хранилище не поддерживает AWS Signature Version 4 streaming, значение должно быть true. Значение по умолчанию: false.

   • ui: настройки приложения.

     • auth: настройки аутентификации.

       • sso: включить ли аутентификацию по технологии единого входа (SSO). Значение по умолчанию: true.
       • secure: использовать ли HTTPS для работы с аутентификацией. Значение по умолчанию: true.

     • appTheme: брендирование внутри приложения.

     • appLocale: язык приложения по умолчанию.

     • whiteLabel.configUrl: URL конфигурационного файла для настройки пользовательского логотипа, фавиконки и других. Пример: /static/theme/pro.json.

     • appInitialMapCenter: координаты карты по умолчанию в формате [lng, lat]. Пример: [37.64, 55.74] для Москвы.

     • publicS3Url: URL публичного S3-совместимого хранилища, в котором будут размещены стили.

     • styles: настройки стилей карты.

       • s3Bucket: имя бакета S3 для стилей. Бакет должен быть публичным и иметь настроенный CORS.
       • configUrl: URL конфигурационного файла для стилей. Пример: https://artifacts.example.com/pro-ui-styles/config/production/styleConfig.json.

     • api.url: базовый URL для Pro API со слэшем в конце. Пример: HTTP(S)://HOST/.

     • mapgl: настройки сервиса MapGL JS API.

       • host: хост сервиса MapGL JS API без протокола и без слэша в конце.
       • key: ключ доступа для сервиса MapGL JS API.
       • styleUrl: путь к директории с конфигурационным файлом (styles.json) для управления стилями карты. Пример: https://artifacts.example.com/pro-ui-styles/styles/default/.
       • stylePreview: URL для миниатюры изображения, которая будет отображаться в менеджере стилей карты для стиля по умолчанию.

   • resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.

   • ingress: конфигурация ресурса Ingress. Адаптируйте приведённую конфигурацию для используемого вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

   • stylesImporter.startOnDeploy: включить ли импорт собственных стилей для Про при установке или обновлении сервиса.

2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-pro-ui.yaml:

   helm upgrade --install --version=VERSION --atomic --values ./values-pro-ui.yaml pro-ui 2gis-on-premise/pro-ui

   В параметре --version укажите нужную версию 2ГИС Про. Список версий см. в разделе Релизы 2ГИС Про.

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

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

5. Проверьте работоспособность установленных сервисов

Выполните запрос с использованием cURL или аналогичного инструмента:

curl -X 'GET' \
  'https://PRO-API/items/1,14,164' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer TOKEN' # Или см. settings.auth.apiKey

Для авторизации используйте Bearer-токен или см. установленное значение параметра settings.auth.apiKey в конфигурационном файле Pro API.

Ответ должен иметь код состояния HTTP 200 и содержать список элементов в формате JSON.

6. Настройте аутентификацию пользователей

Чтобы работать с продуктом 2ГИС Про, конечные пользователи должны проходить аутентификацию. Программный комплекс 2ГИС не предоставляет готовый сервис аутентификации для установки в закрытом контуре. Поэтому вам нужно использовать собственного поставщика OpenID Connect (OIDC) для авторизации пользователей по технологии единого входа (SSO).

Аутентифицироваться и авторизоваться в 2ГИС Про могут пользователи, зарегистрированные в базе внешнего поставщика OIDC. Управление пользователями также осуществляется на стороне этого поставщика.

Настройте поставщика OIDC, выполнив следующие условия:

1. Определите обязательные утверждения (claims) о данных пользователя. Следующие данные гарантированно должны быть заполнены в ответе user-info:

   • sub — идентификатор пользователя.
   • email — email пользователя.
   • email_verified — флаг, указывающий на то, был ли email подтверждён пользователем.
   • name — полное имя пользователя.
   • phone_number — номер телефона пользователя.

2. Настройте области видимости (scopes), по которым можно получать заданные утверждения (claims). Стандартно используются следующие scopes:

   • openid — обязательный параметр, указывающий на использование OpenID Connect для аутентификации пользователя.
   • email — email пользователя.
   • profile — ссылка на профиль пользователя.
   • phone — номер телефона пользователя.

3. Создайте клиента в вашем поставщике OIDC:

   1. Настройте идентификатор (client_id) и cекрет (client_secret) клиента.

   2. Укажите Callback URL и Logout URL для сервиса:

      • Callback URL: https://{application_host}/api/auth/code;
      • Logout URL: https://{application_host}/api/auth/after_sign_out_openid.

   3. Настройте работу клиента с заданными на предыдущем шаге scopes.

4. Настройте передачу ролей для авторизации.

   Сервисы, использующие поставщика OIDC (authProvider.schema: Oidc), проверяют права доступа на основе ролей, переданных в id_token. Если id_token не содержит утверждение (claim) с ролями, пользователь не сможет получить доступ к таким сервисам даже после авторизации.

   Чтобы авторизация работала корректно, настройте вашего поставщика OIDC:

   1. Назначьте пользователям нужные роли.
   2. Настройте маппинг ролей в отдельный claim токена (например, roles).
   3. Убедитесь, что claim размещён на верхнем уровне JSON (не во вложенной структуре).
   4. Укажите тип значения claim — массив строк.
   5. Убедитесь, что claim включён в id_token.

   Пример id_token:

   {
     "sub": "123456",
     "name": "Иван Иванов",
     "roles": ["admin", "editor"],
     "iss": "https://idp.example.com",
     "aud": "client_id",
     "exp": 1710000000
   }

   Если поставщик по умолчанию формирует вложенные claims, настройте преобразование в плоский claim.

7. После установки

После установки 2ГИС Про в вашем контуре и настройки доступов конечные пользователи могут начать работу с продуктом. Подробные инструкции см. в Руководстве пользователя.

Доступность наборов данных

Некоторые системные наборы данных могут быть доступны только в облачной версии 2ГИС Про. Подробнее см. в описании Системных данных.

Что дальше?

• Узнайте, как обновить 2ГИС Про.

• Установите другие продукты программного комплекса 2ГИС:

  • 2ГИС Ситискан,
  • мобильный SDK,
  • прокси для API пробок,
  • Менеджер Платформы.

• Изучите рекомендации по обслуживанию системы.