Установка API-платформы

Чтобы установить API-платформу:

Подготовьтесь к установке.
Установите сервис лицензий.
Установите сервис ключей.
Установите сервис сбора статистики.
Установите прокси для API пробок.
Установите API карт.
Установите API поиска.
Установите API навигации.
Установите Менеджер Платформы.
Установите мобильный SDK.

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

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

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`

deployment-guide-networks

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

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

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

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

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

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

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

Проверьте, что Helm и репозиторий установлены верно, с помощью команды:
```
helm search repo 2gis-on-premise
```
Если вывод команды содержит непустой список чартов, то всё настроено корректно.

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

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

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

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

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

Архитектура хостов

docker.registry.example.com

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

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

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

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

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

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

artifacts.example.com

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

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

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

Хранилище должно быть доступно по адресу https://artifacts.example.com/.
В установленном хранилище создайте бакет onpremise-artifacts нужного размера.
Назначьте бакету сервисный аккаунт с правами на чтение и запись.

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

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

example.com

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

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

Установите операционную систему.
Установите Docker Engine.
Убедитесь, что хост может подключаться к ранее настроенным сервисам:
- 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. В обратном случае возникнут ошибки загрузки.

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

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

Создайте конфигурационный файл 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>

Загрузите артефакты установки в файловую систему с помощью утилиты 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.

Зайдите по SSH на хост example-external.com.
Создайте директорию для скачивания артефактов установки. Вы можете сохранить путь к ней в переменной окружения COPY_DIR. Например:
```
COPY_DIR=/mnt/dgctl-source
```
Создайте конфигурационный файл 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>
Загрузите артефакты установки в файловую систему с помощью утилиты 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.
Перенесите директорию COPY_DIR с example-external.com на example-internal.com.
Зайдите по SSH на хост example-internal.com.

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>

Загрузите артефакты установки в реестр 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. Установка сервиса лицензий

2.1. Перед установкой

Ознакомьтесь с:
- архитектурой программного комплекса 2ГИС;
- системными требованиями к программному обеспечению и вычислительным ресурсам.
Убедитесь, что выполнены подготовительные шаги.

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

Объект	Значение	Как получить значение
Ключ лицензии на программный комплекс 2ГИС	`DEMO-KEY-DGCTL-AAAAAA-BBBBBB`	См. Подготовка к установке
Endpoint S3-совместимого хранилища артефактов установки	`artifacts.example.com`	См. Получение артефактов установки
Инфраструктура доставки артефактов	`example.com` `example-external.com` `example-internal.com`	См. Получение артефактов установки
Имя бакета для хранения артефактов	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Имя пользователя для реестра Docker	`registry`	См. Получение артефактов установки
Пароль для реестра Docker	`DOCKERregistryP@ssW0rd`	См. Получение артефактов установки

Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чарте. Подробнее о том, как это сделать, см. в разделе Системные требования.

Используйте подходящий чарт

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

2.2. Установите сервис лицензий

Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь. Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-license.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] dgctlStorage: host: artifacts.example.com secure: true bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY region: '' license: type: '' retryPeriod: 30s softBlockPeriod: 2w persistence: host: artifacts.example.com secure: true region: '' bucket: onpremise-artifacts root: 'license_state' accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY tpm: mountTPMDevice: false pvcBind: enable: false storageClassName: '' customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: '' affinity: {}
Где:
- 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.
  - region: регион S3-совместимого хранилища.
- license: настройки сервиса лицензий.
  - type: тип лицензии (не версия). Скопируйте цифровое значение из файла values/general.yaml, который генерируется автоматически на этапе загрузки артефактов установки. Не изменяйте это значение вручную.
  - retryPeriod: через какой период времени повторить проверку лицензии, если предыдущая проверка не удалась.
  - softBlockPeriod: за какой период времени появляется уведомление об истечении срока лицензии. Поддерживаются дополнительные единицы измерения времени: d для дней и w для недель.
- persistence: настройки доступа к хранилищу для состояний сервиса лицензий.
  - host: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - region: регион S3-совместимого хранилища.
  - bucket: имя бакета S3.
  - root: корневая директория бакета S3, в которой будут храниться файлы состояния.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
    
    предупреждение
    При потере указанных данных текущая лицензия перестанет работать. Для получения новой лицензии см. Продвинутые способы получения лицензии.
- tpm: настройки для доступа к Trusted Platform Module (TPM). Только для типа лицензии 2 (license.type: 2). Тип лицензии — это цифровое значение из файла values/general.yaml, который генерируется автоматически на этапе загрузки артефактов установки.
  - mountTPMDevice: способ предоставления доступа к TPM:
    - true: монтировать TPM внутрь пода Kubernetes. Включается привилегированный доступ к основному контейнеру.
    - false: использовать плагин для автоматического монтирования TPM-устройства внутрь пода Kubernetes. Вы можете использовать готовый плагин от 2ГИС или собрать и установить свой плагин в кластере Kubernetes.
  - pvcBind: создать Persistent Volume Claim (PVC), чтобы привязать под сервиса лицензий к узлу кластера.
    - enable: использовать ли PVC. Значение по умолчанию: false.
    - storageClassName: имя класса хранения (StorageClass) в Kubernetes.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
- affinity: настройки affinity-правил для привязки подов сервиса лицензий к конкретным узлам кластера.
Примеры настройки affinity-правил:
- Для всех типов лицензий, кроме 1 (тип лицензии — это цифровое значение из файла values/general.yaml, который генерируется автоматически на этапе загрузки артефактов установки), рекомендуется располагать поды сервиса лицензий на разных узлах кластера:
  
  affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - topologyKey: kubernetes.io/hostname labelSelector: matchExpressions: - key: app.kubernetes.io/name operator: In values: - '' # значение этого параметра зависит от настроек вашего окружения
- Для типа лицензии 2 рекомендуется ограничить набор узлов кластера, к которым получает доступ сервис лицензий:
  
  affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: kubernetes.io/hostname operator: In values: - node-1 # название узла кластера - node-2 # название узла кластера
Подробное описание параметров affinity-правил см. в документации Kubernetes.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-license.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
В параметре --version укажите нужную версию базовых сервисов. Список версий см. в разделе Релизы базовых сервисов.

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

При первом запуске команда вернёт ошибку, что под сервиса лицензий не может быть запущен. Это ожидаемое поведение, переходите к следующим шагам.

2.3. Получите лицензию

Ниже описан стандартный способ получения лицензии

Чтобы получить лицензию после обновления сертификата сервера Kubernetes API, смены ключа, типа лицензирования или в других частных случаях, см. Продвинутые способы получения лицензии.

Для операций с лицензиями используется конфигурационный файл утилиты 2GIS CLI. Подробнее о процессе получения лицензии см. в описании режима утилиты license.

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

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

Зайдите по SSH на хост example.com и создайте конфигурационный файл dgctl-config.yaml. Подробнее о доступных параметрах см. в описании конфигурационного файла 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>

Запросите лицензию:
```
docker run --rm \
  -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
  --user $(id -u):$(id -g) \
  2gis/dgctl:3 \
  license --config=/dgctl-config.yaml
```
Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
Снова установите сервис с помощью Helm:
```
helm upgrade --install --version=VERSION --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
В параметре --version укажите ту же версию базовых сервисов, что и при прошлом выполнении команды.

Перед началом работы убедитесь, что у вас настроены два хоста:

example-external.com с доступом в публичную сеть или только к следующим адресам:
- datagateway.api.2gis.com — для получения файла лицензии и файла манифеста;
- origin-disk.2gis.com — для получения файлов приложений и данных.
example-internal.com с доступом к реестру Docker и S3-совместимому хранилищу.

Подробнее см. в разделе Настройка хостов.

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

На обоих хостах создайте директорию для переноса файлов. Вы можете сохранить путь к директории в переменной окружения COPY_DIR. Например:
```
COPY_DIR=/mnt/dgctl-source
```

Зайдите по SSH на хост example-internal.com и создайте конфигурационный файл dgctl-config.yaml. Подробнее о доступных параметрах см. в описании конфигурационного файла 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>

Сформируйте файлы для запроса лицензии на хосте example-internal.com:
1. Проверьте наличие всех необходимых файлов для запроса лицензии (если используете утилиту 2GIS CLI):
  docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ --user $(id -u):$(id -g) \ 2gis/dgctl:3 \ license --config=/dgctl-config.yaml --dry-run
  Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
2. Скопируйте файлы для запроса лицензии из S3-совместимого хранилища в COPY_DIR:
  - Если вы используете утилиту 2GIS CLI, выполните следующую команду:
    docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v $COPY_DIR:/data \ --user $(id -u):$(id -g) \ 2gis/dgctl:3 \ save --config=/dgctl-config.yaml --to-dir /data --only-license
    Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
  - Если вы используете сторонний клиент S3, скопируйте всё содержимое директории license-dir из S3 в COPY_DIR.
Скопируйте содержимое директории COPY_DIR с example-internal.com на example-external.com.
Зайдите по SSH на хост example-external.com и создайте конфигурационный файл dgctl-config-fs.yaml. Подробнее о доступных параметрах см. в описании конфигурационного файла 2GIS CLI.
dgctl-config-fs.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>
Запросите лицензию на example-external.com:
```
docker run --rm \
  -v $(pwd)/dgctl-config-fs.yaml:/dgctl-config.yaml \
  -v $COPY_DIR:/data \
  --user $(id -u):$(id -g) \
  2gis/dgctl:3 \
  license --config=/dgctl-config.yaml
```
Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
Скопируйте содержимое директории COPY_DIR с example-external.com на example-internal.com.
На хосте example-internal.com используйте конфигурационный файл dgctl-config.yaml из шага 2 или создайте такой же.
Скопируйте файл с лицензией из COPY_DIR в S3-совместимое хранилище:
- Если вы используете утилиту 2GIS CLI, выполните команду:
  docker run --rm \ -v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \ -v $COPY_DIR:/data \ --user $(id -u):$(id -g) \ 2gis/dgctl:3 \ restore --config=/dgctl-config.yaml --from-dir /data --only-license
  Если вы используете On-Premise версии 1.16.0 и ниже, добавьте аргумент --with-license-v1 в конец команды.
- Если вы используете сторонний клиент S3, скопируйте всё содержимое директории license-dir из COPY_DIR в S3-совместимое хранилище.
Снова установите сервис с помощью Helm:
```
helm upgrade --install --version=VERSION --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
В параметре --version укажите ту же версию базовых сервисов, что и при прошлом выполнении команды.

2.4. Проверьте статус лицензии

Пробросьте порт сервиса с помощью kubectl:
```
kubectl port-forward <namespace> license.svc 8080:80
```

Выполните запрос к endpoint-у /status:

curl -v 'http://localhost:8080/status' -H "Accept: application/json" | jq

Проверьте ответ:

Если лицензия действительна, ответ содержит HTTP-код 200 и информацию о статусе лицензии и сроке её действия в формате JSON.

Пример ответа

curl -s 'http://localhost:8080/status' -H "Accept: application/json" | jq
{
   "status": 200,
   "issued-at": "2025-08-21T13:49:26Z",
   "soft-block-at": "2026-01-17T21:00:00Z",
   "hard-block-at": "2026-01-31T21:00:00Z",
   "services": {
   "pro": {
         "status": 200,
         "soft-block-at": "2026-01-17T21:00:00Z",
         "hard-block-at": "2026-01-31T21:00:00Z"
   }
   }
}

Если лицензия скоро истечёт или уже истекла, в ответе указан код 402 (предупреждение) или 403 (блокировка).

Пример ответа

curl -s 'http://localhost:8080/status' -H "Accept: application/json" | jq
{
   "status": 402,
   "issued-at": "2025-10-16T05:50:46Z",
   "soft-block-at": "2026-01-17T21:00:00Z",
   "hard-block-at": "2026-01-31T21:00:00Z",
   "services": {
   "pro": {
         "status": 402,
         "soft-block-at": "2026-01-17T21:00:00Z",
         "hard-block-at": "2026-01-31T21:00:00Z"
   }
   }
}

3. Установка сервиса API-ключей

3.1. Перед установкой

Ознакомьтесь с:
- документацией сервиса API-ключей;
- архитектурой программного комплекса 2ГИС;
- системными требованиями к программному обеспечению и вычислительным ресурсам.
Убедитесь, что выполнены подготовительные шаги.

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

Объект	Значение	Как получить значение
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Секрет Kubernetes для доступа к реестру Docker	`onpremise-registry-creds`	См. Получение артефактов установки
Endpoint S3-совместимого хранилища артефактов установки	`artifacts.example.com`	См. Получение артефактов установки
Название бакета с артефактами установки	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Путь к файлу манифеста	`manifests/core/1640661259.json`	См. Получение артефактов установки

Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чарте. Подробнее о том, как это сделать, см. в разделе Системные требования.

Требования к хранилищу могут меняться в зависимости от настроенного временного периода для хранения статистики. Чем больше период, тем больший объём хранилища требуется.

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

Пример:
- Веб-интерфейс администратора: keys-admin.example.com.
- API backend: keys-api.example.com.

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

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

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

Настройте PostgreSQL

Разместите кластер PostgreSQL с доменным именем keys-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.
Подключитесь к кластеру от имени суперпользователя (обычно это postgres).

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

create user keys_superuser_rw password 'KEYS_Db_Owner_Password_1234';
create user keys_user_ro password 'KEYS_Db_RO_User_Password_5678';

Создайте базу данных, принадлежащую одному из пользователей:
```
create database onpremise_keys owner keys_superuser_rw;
```

Добавьте ограниченные права к этой базе данных другому пользователю:

\c onpremise_keys

ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON TABLES TO keys_user_ro;
ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON SEQUENCES TO keys_user_ro;

Настройте LDAP

Чтобы сервисы могли выполнять аутентификацию администраторов сервиса API-ключей, рекомендуется использовать LDAP-сервер (например, Microsoft Active Directory). Этот шаг можно пропустить, если у вас нет возможности развернуть LDAP-сервер и вы собираетесь использовать аутентификацию по plaintext-паролям в конфигурационном файле.

Разместите LDAP-сервер с доменным именем keys-ldap.storage.example.local в приватной сети. Предполагается, что сервер работает на стандартном порту 3268.

Получите значения настроек LDAP:

Настройка	Пример значения
Пользователь для подключения к службе LDAP	`keys_ldap_user`
Пароль пользователя для подключения к службе LDAP	`KEYS_LDAP_PaSSw0rd_8901`
Основное уникальное имя (base relative distinguished name), относительно которого выполняется поиск в каталоге LDAP	`dc=2gis`
Фильтр LDAP, используемый для идентификации записей в поисковых запросах	`(&(objectClass=user)(sAMAccountName=%s))`

Добавьте в LDAP пользователя admin, которому будет назначена роль администратора в сервисе API-ключей.

Настройте Apache Kafka

примечание

Если вы не планируете использовать сервис сбора статистики, пропустите этот шаг.

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

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

Настройте Redis

примечание

Если вы не планируете использовать сервис сбора статистики, пропустите этот шаг.

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

Пример:
- Имя пользователя: redisuser.
- Пароль: Redis_Password_6379.

3.3. Установите сервис API-ключей

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-keys.yaml
dgctlDockerRegistry: docker.registry.example.com dgctlStorage: host: artifacts.example.com secure: true bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/core/1640661259.json region: '' verifySsl: true redis: enabled: false host: redis.cache.example.local port: 6379 db: 1 password: Redis_Password_6379 postgres: ro: host: keys-postgresql.storage.example.local port: '5432' name: onpremise_keys username: keys_user_ro password: KEYS_Db_RO_User_Password_5678 rw: host: keys-postgresql.storage.example.local port: '5432' name: onpremise_keys username: keys_superuser_rw password: KEYS_Db_Owner_Password_1234 kafka: bootstrapServers: 'keys-kafka.storage.example.local:9092' username: kafka password: kafka_password securityProtocol: SASL_PLAINTEXT saslMechanism: SCRAM-SHA-512 stats: topic: 'stat_master_type.401' groupId: 'keys-counter' clientId: 'keys-counter' counter: enabled: false preloader: refreshTick: 10s ldap: host: ldap.keys.example.com port: 3268 useStartTLS: false useLDAPS: false skipServerCertificateVerify: false serverName: ldap.keys.example.com clientCertificatePath: /home/user/certificates/cert.crt clientKeyPath: /home/user/certificates/cert.key rootCertificateAuthoritiesPath: /home/user/certificates/root.cer bind: dn: keys_ldap_user password: KEYS_LDAP_PaSSw0rd_8901 search: baseDN: dc=2gis filter: (&(objectClass=user)(sAMAccountName=%s)) statApi: enabled: false url: '' timeout: 30s retryCount: 3 tasker: resources: requests: cpu: 10m memory: 32Mi limits: cpu: 100m memory: 64Mi delay: 30s admin: host: https://keys-admin.example.com ingress: enabled: true className: nginx hosts: - host: keys-admin.example.com paths: - path: / pathType: Prefix tls: [] #- hosts: # - keys-admin.example.com # secretName: secret.tls api: adminUsers: 'admin:8k7RVCP8m3AABDzD' oidc: enabled: true enableSinglePartnerMode: true enableExternalProvider: true url: https://keycloak.example.com/realms/platform defaultPartner: id: 1 name: 'Partner' role: admin ingress: enabled: true className: nginx hosts: - host: keys-api.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - keys-api.example.com # secretName: secret.tls customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- dgctlStorage: настройки доступа к хранилищу артефактов установки.
  - host: endpoint S3-совместимого хранилища артефактов установки в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - bucket: имя бакета S3.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
  - manifest: путь до файла с манифестом в формате manifests/core/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
  - region: регион S3-совместимого хранилища.
  - verifySsl: включить ли проверку SSL-сертификатов при подключении к dgctlStorage.host по HTTPS. Значение по умолчанию: true.
- redis: настройки доступа к серверу Redis.
  - enabled: включить ли использование Redis. Значение по умолчанию: false.
  - host: имя хоста или IP-адрес сервера.
  - port: порт, на котором слушает сервер.
  - db: номер базы данных Redis.
  - password: пароль пользователя Redis. Если аутентификация не требуется, оставьте поле пустым.
- postgres: настройки доступа к серверу PostgreSQL.
  
  Сервис API-ключей работает с данными в двух режимах: только чтение (ro) и чтение-запись (rw). В обоих режимах сервис работает с одной базой, но от имени пользователей с разными правами (см. подробности в шаге 1).
  - Настройки, общие для обоих режимов:
    - host: имя хоста или IP-адрес сервера. Вы можете добавить несколько хостов или IP-адресов, разделив их запятыми.
    - port: порт, на котором слушает сервер. Вы можете добавить несколько портов, разделив их запятыми.
    - name: имя базы данных.
  - Реквизиты для доступа к базе пользователя с правами только на чтение (секция ro).
  - Реквизиты для доступа к базе пользователя с правами на чтение и запись (секция rw).
  Для хранения настроек password в группах ro и rw Helm-чарт использует Kubernetes Secrets.
- kafka: настройки доступа к Apache Kafka.
  - bootstrapServers: адреса и порты брокеров Apache Kafka через запятую. Пример: HOST1:PORT1,HOST2:PORT2.
  - username: имя пользователя для аутентификации через SASL.
  - password: пароль пользователя для аутентификации через SASL.
  - securityProtocol: протокол безопасности для подключения.
  - saslMechanism: механизм SASL-аутентификации.
  - stats: настройки для сбора статистики использования API-ключей.
    - topic: имя топика Kafka, из которого сервис API-ключей будет считывать данные о статистике использования ключей.
    - groupId: идентификатор группы потребителей Kafka.
    - clientId: идентификатор клиента Kafka.
- counter: настройки сервиса подсчёта использования API-ключей.
  - enabled: включить ли сервис. Значение по умолчанию: false.
  - preloader.refreshTick: период (в секундах), с которым сервис будет обновлять кеш с информацией о лимитах.
- ldap: настройки доступа к серверу LDAP.
  - host: имя хоста или IP-адрес сервера.
  - port: порт, на котором слушает сервер.
  - Группа настроек для обеспечения защищенного соединения с сервером LDAP:
    - useStartTLS: использовать StartTLS.
    - useLDAPS: использовать Secure LDAP.
    - skipServerCertificateVerify: не проверять сертификат сервера.
    - serverName: строка с именем сервера. Используется при проверке сертификата сервера.
    - clientCertificatePath: путь к сертификату клиента.
    - clientKeyPath: путь к ключу клиента.
    - rootCertificateAuthoritiesPath: путь к файлу с корневыми сертификатами от центров сертификации (root certificate authorities).
  - bind: реквизиты для доступа к серверу LDAP:
    - dn: уникальное имя пользователя (distinguished name).
    - password: пароль пользователя.
  - search: настройки поиска LDAP:
    - baseDN: основное относительное уникальное имя (base relative distinguished name).
    - filter: фильтр LDAP, используемый для идентификации записей в поисковых запросах.
- statApi: настройки доступа к сервису Stat API.
  - enabled: включён ли сервис. Значение по умолчанию: false.
  - url: ссылка на сервис. Обязательное значение, если параметр statApi.enabled имеет значение true.
  - timeout: таймаут запросов к сервису. Значение может быть числом с единицей времени и, при необходимости, дробной частью. Допустимые единицы: ns, us (или µs), ms, s, m, h. Например: 100ms, 2.3h, 4h35m.
  - retryCount: максимальное количество повторных попыток запроса к сервису.
- tasker: настройки сервиса Tasker, который выполняет административные задачи, связанные с API-ключами.
  - resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
  - delay: период (в секундах). Эта настройка определяет, с каким периодом проверять задачи, которые связаны с настроенными отложенными действиями (например, блокировкой API-ключа).
- admin: настройки веб-сервиса администратора (предоставляет доступ к веб-интерфейсу для администрирования сервиса).
  - host: URL фронтенда сервиса API-ключей. Этот URL должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
  - ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- api: настройки API сервиса.
  - adminUsers: список реквизитов пользователей с административными правами в формате username1:password1,username2:password2,....
    
    Для хранения этой настройки Helm-чарт использует Kubernetes Secrets.
    
    примечание
    Если у вас есть сервер LDAP, то рекомендуется использовать его для аутентификации, а настройку api.adminUsers пропустить.
  - oidc: настройки внешнего поставщика OpenID Connect (OIDC). Необходимы для работы со статистикой по API-ключам в Менеджере Платформы.
    - enabled: включить ли аутентификацию через OIDC.
    - enableSinglePartnerMode: включить режим одного партнёра — все пользователи привязываются к сконфигурированному партнёру (компании). Статистика по API-ключам будет отображаться только для компании, указанной в параметре defaultPartner.
    - enableExternalProvider: использовать ли внешнего поставщика OIDC. При включении управление пользователями осуществляется на стороне внешнего поставщика.
    - url: URL OIDC-поставщика.
    - defaultPartner: параметры партнёра.
  - ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-keys.yaml:
```
helm upgrade --install --version=VERSION --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
```
В параметре --version укажите нужную версию базовых сервисов. Список версий см. в разделе Релизы базовых сервисов.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
Добавьте пользователей в сервис с помощью утилиты keysctl. Этим пользователям будет назначена роль администратора сервиса API-ключей.

Чтобы добавить одного пользователя, выполните эту команду из любого пода keys-api:
```
keysctl users add admin 'Keys Service Admin'
```

3.4. Получите сервисные токены

Каждый сервис, который интегрируется с сервисом API-ключей, обязан отправлять информацию об использовании ключей конечными пользователями на бэкенд сервиса API-ключей. Чтобы сервис мог взаимодействовать с этим бэкендом, во время его конфигурации задайте сервисный токен.

Чтобы получить список доступных сервисных токенов, выполните следующую команду из любого пода keys-api:

keysctl services

3.5. Проверьте работоспособность сервиса API-ключей

Откройте в браузере веб-интерфейс для администрирования сервиса (используйте значение настройки admin.host из конфигурационного файла values-keys.yaml):
```
https://keys-admin.example.com
```
Войдите в веб-интерфейс с учётными данными администратора — пользователя, которому назначена роль администратора с помощью утилиты keysctl. Вы должны увидеть веб-интерфейс для управления API-ключами.

3.6. Создайте API-ключ

Для работы с сервисами добавьте первого партнёра, оформите для него подписку и выпустите API-ключ. Без корректного API-ключа Catalog APIs не пройдёт проверку работоспособности, а другие сервисы не будут возвращать ответы. Подробнее о создании подписки и API-ключа см. в разделе Управление доступом к API.

Можно использовать один API-ключ для нескольких сервисов. Для этого убедитесь, что необходимые сервисы включены в настройках ключа.

4. Установка сервиса сбора статистики

Установка сервиса сбора статистики необязательна, если вы не планируете собирать и анализировать статистические данные по использованию API-ключей для работы с сервисами API-платформы.

4.1. Перед установкой

Ознакомьтесь с:
- документацией сервиса сбора статистики;
- архитектурой программного комплекса 2ГИС.
Убедитесь, что выполнены предварительные шаги:

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

Объект	Пример значения	Как получить значение
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Секрет Kubernetes для доступа к реестру Docker	`onpremise-registry-creds`	См. Получение артефактов установки

Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чарте. Подробнее о том, как это сделать, см. в разделе Системные требования.

Используйте подходящий чарт
Содержание Helm-чарта, описанное в этом разделе, актуально для последней версии API-платформы (см. Релизы API-платформы). Чтобы изучить параметры для предыдущих версий, откройте values.yaml в GitHub и в списке тегов слева выберите тег Platform-<версия>.
Определите доменное имя:
- для сервиса Stat Receiver — например, stat-receiver.example.com;
- для сервиса Stat API (если вы планируете его устанавливать) — например, stat-api.example.com.

4.2. Установите сервис сбора статистики

Установите сервис Stat Receiver

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-stat-receiver.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] kafka: servers: 'keys-kafka.storage.example.local:9092' securityProtocol: PLAINTEXT truststore: enabled: false keystore: enabled: false sasl: enabled: true secretName: 'stat-receiver-kafka-creds' jaasLoginModule: 'org.apache.kafka.common.security.scram.ScramLoginModule' username: '' password: '' initializeTopics: enabled: true topicsPrefix: 'stat_master_'
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- kafka: настройки Apache Kafka.
  - servers: адрес и порт кластера Apache Kafka, который был настроен на этапе Установки сервиса API-ключей.
  - securityProtocol: протокол безопасности для подключения к брокеру.
  - truststore.enabled: включите, чтобы использовать TLS для подключения к Kafka.
  - keystore.enabled: включите, чтобы использовать клиентскую аутентификацию TLS для подключения к Kafka.
  - sasl: настройка SASL для подключения к Kafka.
    - enabled: включите, если в сервисе API-ключей также включена аутентификация в Kafka.
    - secretName: имя секрета Kubernetes, в котором хранятся учётные данные для подключения к Kafka. Имя должно быть уникальным в пространстве имён кластера, который используется для установки.
    - jaasLoginModule: строка конфигурации JAAS для SASL-подключения.
    - username: имя пользователя для подключения к Kafka. Требуется, если в поле secretName пустое значение.
    - password: пароль для подключения к Kafka. Требуется, если в поле secretName пустое значение.
- initializeTopics.enabled: включите, чтобы сервис сбора статистики создал необходимые топики в Kafka при первом запуске.
- topicsPrefix: префикс для имен топиков, которые будут созданы в Kafka. См. имя топика, которое вы задали в параметре kafka.stats.topic в конфигурационном файле сервиса API-ключей: префикс — начальная часть имени топика до type.401 (фиксированная часть имени).
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-stat-receiver.yaml:
```
helm upgrade --install --version=VERSION --atomic --wait --timeout 7200s --values ./values-stat-receiver.yaml stat-receiver 2gis-on-premise/stat-receiver
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис Stat API (опционально)

Сервис Stat API нужен для отображения статистики распределения запросов в личном кабинете.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-stat-api.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] migrate: kafkaTableEngine: brokers: broker1:9092,broker2:9092 topic: type.401 group: '' clickhouse: clientName: stat-api-migrate clickhouse: servers: host1:port1,host2:port2 cluster: '' database: '' username: clickhouse-user password: password
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- migrate: настройки для модуля миграции данных из Apache Kafka в ClickHouse.
  - kafkaTableEngine: параметры подключения к Apache Kafka для чтения данных в процессе миграции.
    - brokers: список адресов Kafka-брокеров, разделённых запятой.
    - topic: имя топика Apache Kafka, в котором находятся данные от сервиса Stat Receiver.
    - group: имя потребительской группы.
  - clickhouse.clientName: имя клиента, которое будет использоваться при подключении к ClickHouse.
- clickhouse: параметры подключения к ClickHouse.
  - servers: список адресов серверов ClickHouse, разделённых запятой.
  - cluster: имя кластера ClickHouse при выполнении распределённых запросов и миграций.
  - database: имя базы данных ClickHouse для подключения.
  - username: имя пользователя для аутентификации в ClickHouse.
  - password: пароль пользователя для аутентификации в ClickHouse.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-stat-api.yaml:
```
helm upgrade --install --version=VERSION --atomic --wait --timeout 7200s --values ./values-stat-api.yaml stat-api 2gis-on-premise/stat-api
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

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

После установки сервисов API-платформы вы сможете просматривать статистику их использования в Менеджере Платформы и настраивать лимиты в веб-интерфейсе сервиса API-ключей.

5. Установка прокси для API пробок

Установка прокси для API пробок необязательна, если вы не собираетесь получать данные о пробках в реальном времени. Для этого сервиса также нужен постоянный доступ в интернет.

5.1. Перед установкой

Ознакомьтесь с:
- документацией прокси для API пробок;
- архитектурой программного комплекса 2ГИС.
Убедитесь, что выполнены предварительные шаги:

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

Объект	Пример значения	Как получить значение
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Секрет Kubernetes для доступа к реестру Docker	`onpremise-registry-creds`	См. Получение артефактов установки
Ключ лицензии на программный комплекс 2ГИС	`DEMO-KEY-DGCTL-AAAAAA-BBBBBB`	См. Получение лицензии на программный комплекс 2ГИС

Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чарте. Подробнее о том, как это сделать, см. в разделе Системные требования.

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

5.2. Установите прокси для API пробок

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-traffic-proxy-navi.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] replicaCount: 1 proxy: host: https://datagateway.api.2gis.com locationDG: true licenseKey: DEMO-KEY-DGCTL-AAAAAA-BBBBBB
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- replicaCount: число реплик сервиса nginx.
- proxy: настройки прокси-сервера.
  - host: доменное имя, IP-адрес или URL публичного сервера обновлений для пробок 2ГИС. Список доступных серверов приведен в разделе Архитектура.
  - locationDG: включает дополнительные контексты для работы с datagateway.api.2gis.com.
  - licenseKey: ключ лицензии на программный комплекс 2ГИС. Требуется, если locationDG имеет значение true.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-traffic-proxy-navi.yaml:
```
helm upgrade --install --atomic --wait-for-jobs --values ./values-traffic-proxy-navi.yaml traffic-proxy-navi 2gis-on-premise/traffic-proxy
```

Для использования сервисами карт

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-traffic-proxy-map.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] replicaCount: 1 proxy: host: https://jam.api.2gis.com locationDG: false ingress: enabled: true className: nginx hosts: - host: traffic-proxy-map.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - traffic-proxy-map.example.com # secretName: secret.tls
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- replicaCount: число реплик сервиса nginx.
- proxy: настройки прокси-сервера.
  - host: доменное имя, IP-адрес или URL публичного сервера обновлений для пробок 2ГИС. Список доступных серверов приведен в разделе Архитектура.
  - locationDG: включает дополнительные контексты для работы с datagateway.api.2gis.com.
  - licenseKey: ключ лицензии на программный комплекс 2ГИС. Требуется, если locationDG имеет значение true.
- ingress: конфигурация ресурса Ingress. Адаптируйте приведённую конфигурацию для соответствия используемому вами Ingress. Обратите внимание, что путь для хоста должен указывать на /.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-traffic-proxy-map.yaml:
```
helm upgrade --install --atomic --wait-for-jobs --values ./values-traffic-proxy-map.yaml traffic-proxy-map 2gis-on-premise/traffic-proxy
```

5.3. Проверьте работоспособность прокси для API пробок

1. Проверьте работу прокси для API пробок

Выполните следующие запросы к адресу, указанному в параметре ingress.hosts[0].host конфигурационного файла для установки прокси API пробок для сервисов навигации:

curl -X GET 'https://traffic-proxy-navi.example.com/eca/traffic/moses/speeds5.json'
curl -X GET 'https://traffic-proxy-navi.example.com/forecast/index.json'
curl -X GET 'https://traffic-proxy-navi.example.com/long-forecast/index.json'
curl -X GET 'https://traffic-proxy-navi.example.com/eta/eta-predictions/index.json'
curl -X GET 'https://traffic-proxy-navi.example.com/navi-castle/restrictions_index.json.zip' --output restrictions_index.json.zip
curl -X GET 'https://traffic-proxy-navi.example.com/navi-castle/restricted_transport.json.zip' --output restricted_transport.json.zip

В ответе вы должны получить JSON-объекты и валидные архивы.

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

Чтобы проверить, что сервис Navi-Back получает данные пробок через прокси:

Выполните любой из подготовительных шагов:
- Убедитесь, что в конфигурационном файле для установки сервиса Navi-Back задан параметр ingress.enabled: "true". В следующих шагах используйте адрес, который указан в параметре ingress.hosts[0].host конфигурационного файла Navi-Back (например, https://navi-back-ingress.example.com).
- Пробросьте HTTP-порт контейнера Navi-Back на уровень хост-сети для обращения к сервисным endpoint-ам. В следующих шагах используйте IP-адрес и порт хоста.
Проверьте время последнего получения данных о пробках одним из способов:
- Получите значения метрик Navi-Back в формате Prometheus через endpoint /metrics. Добавьте к адресу из подготовительного шага путь /metrics и отправьте GET-запрос. Пример:
  curl -X GET 'https://navi-back-ingress.example.com/metrics'
  Ответ должен содержать метрики mosesd_jams (временную метку последнего получения данных пробок в формате UNIX timestamp) и mosesd_jams_delay (время, прошедшее с последнего момента получения данных). Если эти метрики отсутствуют, сервис не смог получить данные о пробках через прокси.
- В браузере перейдите по адресу из подготовительного шага и добавьте к нему путь /city. Например, navi-back-ingress.example.com/city?type=json.
  
  Вы должны получить HTML-страницу со столбцом пробки и временем последнего получения данных.
- Отправьте GET-запрос по адресу из подготовительного шага и добавьте к нему путь /city. Например:
  curl -X GET 'https://navi-back-ingress.example.com/city?type=json'
  В ответе вы должны получить JSON-объект с полем пробки и временем последнего получения данных.

Для использования сервисами карт

1. Проверьте работу прокси для API пробок

Выполните один из шагов:

В браузере перейдите по адресу, который указан в параметре ingress.hosts[0].host конфигурационного файла для установки прокси API пробок для сервисов карт, и укажите путь /meta?reg=65536,108&time&score. Например, traffic-proxy-map.example.com/meta?reg=65536,108&time&score.
Выполните GET-запрос к аналогичному адресу:
```
curl -X GET 'https://traffic-proxy-map.example.com/meta?reg=65536,108&time&score'
```
Запрос должен выполниться успешно и вернуть результат в виде списка.

2. Проверьте получение данных пробок сервисом MapGL JS API

Чтобы проверить, что сервис MapGL JS API получает данные о пробках через прокси:

Выполните любой из подготовительных шагов:
- Убедитесь, что в конфигурационном файле для установки сервиса MapGL JS API задан параметр ingress.enabled: "true". В следующих шагах используйте адрес, который указан в параметре ingress.hosts[0].host конфигурационного файла MapGL JS API (например, https://mapgl-js-api.example.com).
- Пробросьте HTTP-порт контейнера MapGL JS API на уровень хост-сети для обращения к сервисным endpoint-ам. В следующих шагах используйте IP-адрес и порт хоста.
Нажмите на иконку пробок в верхнем правом углу карты. На карте отобразятся пробки, а на кнопке будет указан текущий уровень пробок и соответствующий цвет.

6. Установка API карт

6.1. Перед установкой

Ознакомьтесь с:
- документацией сервисов карт;
- архитектурой программного комплекса 2ГИС.
Убедитесь, что выполнены предварительные шаги:

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

Объект	Пример значения	Как получить значение
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Секрет Kubernetes для доступа к реестру Docker	`onpremise-registry-creds`	См. Получение артефактов установки
Endpoint S3-совместимого хранилища артефактов установки	`artifacts.example.com`	См. Получение артефактов установки
Название бакета с артефактами установки	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Путь к файлу манифеста	`manifests/api-platform/1640661259.json`	См. Получение артефактов установки
Endpoint сервиса лицензий	`https://license`	См. Установка сервиса лицензий
Endpoint сервиса API-ключей	`http://keys-service-api`	См. Установка сервиса API-ключей
Endpoint сервиса сбора статистики	`http://stat-receiver`	См. Установка сервиса сбора статистики
Endpoint прокси для API пробок	`http://traffic-proxy`	См. Установка прокси для API пробок
Сервисные токены	`TILES_VECTOR_TOKEN`, `TILES_RASTER_TOKEN`	См. Установка сервиса API-ключей

Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чартах:
- MapGL JS API,
- Tiles API,
- Styles API.
Подробнее о том, как это сделать, см. в разделе Системные требования.

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

Пример:
- Доменное имя для MapGL JS API: mapgl-js-api.example.com.
- Доменное имя для Tiles API: tiles-api.example.com.
- Доменное имя для Styles API: styles.example.com.

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

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

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

Для установки Tiles API

Разместите один или несколько инстансов хранилища Apache Cassandra в приватной сети.

Рекомендуется включить доступ к Apache Cassandra по протоколу JMX, чтобы разрешить очистку снимков хранилища (см. Обновление сервиса Tiles API).

Если настройки безопасности не разрешают автоматическое создание пространств ключей (keyspace), то для хранения данных о тайлах создайте пространство ключей вручную.

Пример:

Хосты:
- tiles-cassandra-1.storage.example.local.
- tiles-cassandra-2.storage.example.local.
- tiles-cassandra-3.storage.example.local.
Имя пользователя: cassandrauser.
Пароль: CASSANDRAPASSWORD-DWTYB05URKZJEDDN.
Имя пользователя для JMX: jmxuser.
Пароль для JMX: JMXPASSWORD-MNZLQTFH0MDDHIX8.

Для установки Styles API

Сервис Styles API необходим для подключения пользовательских стилей карты. Styles API является опциональным сервисом и не обязателен для работы API-платформы.

Если вы планируете устанавливать Styles API, выполните дополнительные шаги:

Настройте доступ к S3-совместимому хранилищу:
1. Разместите S3-совместимое хранилище с доменным именем s3.storage.example.local в приватной сети. Предполагается, что хранилище работает на стандартном порту 80.
2. Создайте ключи для подключения к сервису. Запомните реквизиты.
  
  Пример:
  - Ключ доступа: PHEI4AHTHEETHAHXEEGE.
  - Секретный ключ: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1.
3. Определите название бакета, который будет использоваться для сервиса.
  
  Пример: styles.
  
  Бакет должен быть публичным и иметь настроенный CORS, чтобы файлы из него были доступны для загрузки из браузера с произвольного хоста.
Настройте PostgreSQL:
1. Разместите кластер PostgreSQL с доменным именем styles-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.
2. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).
3. Создайте пользователя базы данных и установите пароль для него:
  create user dbuser_styles password 'wNgJamrIym8UAcdX';
4. Создайте базу данных, принадлежащую этому пользователю:
  create database onpremise_styles owner dbuser_styles;

6.3. Установите сервисы карт

Установите сервис Tiles API

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-tiles.yaml
dgctlDockerRegistry: docker.registry.example.com dgctlStorage: host: artifacts.example.com secure: true bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/api-platform/1640661259.json region : '' warningText: License expiring in %d days.\nPlease contact your account manager.\n%s errorText: License expired.\nPlease contact your account manager.\n%s emailManager: on-premise@2gis.com types: - kind: web - kind: web subtype: immersive - kind: web subtype: relief cassandra: environment: prod hosts: - tiles-cassandra-1.storage.example.local - tiles-cassandra-2.storage.example.local - tiles-cassandra-3.storage.example.local replicaFactor: 3 consistencyLevelRead: LOCAL_ONE consistencyLevelWrite: LOCAL_QUORUM credentials: user: cassandrauser password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN jmxUser: jmxuser jmxPassword: JMXPASSWORD-MNZLQTFH0MDDHIX8 tls: enabled: false enableHostVerification: false deploySecret: false ca: '' # ca: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- cert: '' # cert: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- key: '' # key: | # -----BEGIN PRIVATE KEY----- # ... # -----END PRIVATE KEY----- importer: enabled: true workerNum: 4 writerNum: 8 workerResources: requests: cpu: 256m memory: 512Mi limits: cpu: 2 memory: 2048Mi cleaner: enabled: true limit: 3 clearSnapshots: true api: imagePullSecrets: [onpremise-registry-creds] pdb: enabled: false ingress: enabled: true className: nginx hosts: - host: tiles-api.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - tiles-api.example.com # secretName: secret.tls proxy: access: enabled: true url: http://keys-service-api vector: token: 'TILES_VECTOR_TOKEN' raster: token: 'TILES_RASTER_TOKEN' stat: enabled: false url: 'http://stat-receiver/bss/3' license: url: 'https://license' retryPeriod: 30s customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- dgctlStorage: настройки доступа к хранилищу артефактов установки.
  - host: endpoint S3-совместимого хранилища артефактов установки в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - bucket: имя бакета S3.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
  - manifest: путь до файла с манифестом в формате manifests/api-platform/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
  - region: регион S3-совместимого хранилища.
- warningText: предупреждающее сообщение о скорой блокировке при работе с растровыми тайлами. Должно содержать: %d — плейсхолдер для количества дней до полной блокировки, %s — плейсхолдер для контакта менеджера аккаунта.
- errorText: сообщение о полной блокировке при работе с растровыми тайлами. Должно содержать %s — плейсхолдер для контакта менеджера аккаунта.
- emailManager: контакт менеджера аккаунта, который используется в сообщениях при работе с растровыми тайлами.
- types: массив из одного и более типов тайлов, которые будет предоставлять сервис.
  - types[0].kind: задаёт тип возвращаемых тайлов. Возможные значения:
    - web: векторные тайлы для MapGL JS API.
      - subtype: подтип векторных тайлов. Возможные значения: immersive для отображения 3D-моделей или relief для отображения трёхмерного рельефа местности и 3D-моделей.
    - raster: растровые тайлы.
    - native: векторные тайлы для версий Mobile SDK 12.10 и ниже.
    - native-v4: векторные тайлы для версий Mobile SDK выше 12.10.
    - mapbox: векторные тайлы в формате MVT для использования в сторонних ГИС-системах. Подробнее см. в разделе Экспорт векторных тайлов.
- cassandra: настройки хранилища данных Apache Cassandra.
  - environment: имя окружения, не более 7 символов.
  - hosts: массив из одного и более IP-адресов или имён хоста инсталляции Apache Cassandra.
  - replicaFactor: фактор репликации. Задайте подходящее значение для этой настройки в соответствии с вашей инсталляцией Apache Cassandra.
  - При необходимости задайте подходящее значение для настроек консистентности данных в соответствии с вашей инсталляцией Apache Cassandra.
  - credentials: учётные данные для аутентификации. Значения user и password являются обязательными, а jmxUser и jmxPassword используются только для очистки снимков хранилища (см. Обновление сервиса Tiles API). Значение по умолчанию каждого из параметров — cassandra.
  - tls: конфигурация TLS для доступа к Apache Cassandra.
    - enabled: включите, если Apache Cassandra использует TLS для клиентских подключений. Значение по умолчанию: false (выключено).
    - enableHostVerification: включите для проверки имени хоста во время TLS-соединения. Значение по умолчанию: true (включено).
    - deploySecret: включите для создания секрета Kubernetes, в котором будут храниться сертификаты TLS для подключения к Apache Cassandra. Значение по умолчанию: false (выключено).
    - ca: корневой сертификат.
    - cert: клиентский сертификат.
    - key: приватный клиентский ключ для установления защищённого соединения.
- importer: настройки воркеров процесса импорта (Kubernetes Importer job).
  - enabled: включить ли процесс импорта данных.
  - workerNum: число воркеров (параллельных процессов импорта).
  - writerNum: число процессов-писателей на один воркер.
    
    Рекомендуемые настройки
    При установке Tiles API с поддержкой растровых тайлов рекомендуется уменьшить значения настроек workerNum (по умолчанию: 20) и writerNum (по умолчанию: 8)
    Импорт данных для растровых тайлов может занять длительное время. Использование относительно высоких значений по умолчанию может привести к преждевременному завершению задания из-за истечения таймаута.
  - workerResources: настройки вычислительных ресурсов для воркера. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
  - cleaner и clearSnapshots: настройки автоматического удаления старых данных. Подробнее см. в разделе Обновление сервиса Tiles API.
  См. Жизненный цикл артефактов установки для получения дополнительной информации о работе процесса импорта.
- api: Настройки бэкенд-сервиса API.
  - imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
  - pdb.enabled: включена ли защита сервиса с использованием Pod Disruption Budget.
  - ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре api.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- proxy: настройки сервиса ключей. Используйте эти настройки, если вы хотите ограничить доступ к сервису Tiles API для конечных пользователей.
  - access.enabled: флаг, определяющий, проверять ли действие ограничений для ключей доступа.
  - access.url: URL API-endpoint сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - access.vector.token: отдельный сервисный токен для доступа к векторным данным Tiles API. Этот ключ можно получить с помощью утилиты keysctl.
  - access.raster.token: отдельный сервисный токен для доступа к растровым данным Tiles Raster API. Этот ключ можно получить с помощью утилиты keysctl.
  - stat: настройки взаимодействия с сервисом сбора статистики.
    - enabled: включите, чтобы отправлять статистику использования ключей.
    - url: URL сервиса сбора статистики.
- license: настройки сервиса лицензий.
  - url: URL-адрес сервиса лицензий. Пример: https://license.
  - retryPeriod: как часто Tiles API должен пытаться обновить статус лицензии, если ему не удается его получить.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-tiles.yaml.
```
helm upgrade --install --version=VERSION --atomic --wait --timeout 7200s --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Процесс импорта (Kubernetes Importer job) получит все необходимые данные из хранилища артефактов установки и далее импортирует эти данные в Apache Cassandra. Затем Helm выполнит установку самого сервиса.

Установите сервис MapGL JS API

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-mapgl.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] env: MAPGL_DEMO_KEY: '' MAPGL_HOST: https://mapgl-api.ingress.host MAPGL_TILES_API: https://tiles-api.ingress.host MAPGL_TILESET: web MAPGL_IMMERSIVE_TILESET: web_immersive MAPGL_TRAFFICSERVER: https://traffic-proxy.ingress.host MAPGL_STYLESERVER: https://styles.ingress.host MAPGL_ICONS_URL: https://s3.ingress.host/styles/icons MAPGL_MODELS_URL: https://s3.ingress.host/styles/models MAPGL_KEYSERVER: https://keys-api.example.com/public/v1/keys/{keyID}/services/mapgl-js-api MAPGL_RTLPLUGIN: https://mapgl-api.ingress.host/api/js/plugins/rtl-v1.0.0.js MAPGL_INVALID_KEY_MESSAGE: Your MapGL key is invalid. resources: requests: cpu: 30m memory: 32Mi limits: cpu: 100m memory: 96Mi ingress: enabled: true className: nginx hosts: - host: mapgl-js-api.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - mapgl-js-api.example.com # secretName: secret.tls
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- env: переменные окружения.
  - MAPGL_DEMO_KEY: API-ключ для доступа к сервису. Должен быть сгенерирован с помощью сервиса API-ключей.
  - MAPGL_HOST: URL сервиса, который ваши приложения должны использовать для коммуникаций с сервисами карт.
  - MAPGL_TILES_API: URL сервиса Tiles API.
  - MAPGL_TILESET: подложка сервиса Tiles API с векторными тайлами.
  - MAPGL_IMMERSIVE_TILESET: подложка сервиса Tiles API с тайлами для отображения 3D-моделей.
  - MAPGL_TRAFFICSERVER: URL сервиса прокси для API пробок.
  - MAPGL_STYLESERVER: URL сервиса Styles API.
  - MAPGL_ICONS_URL: URL директории с иконками для стилей. URL должен быть публично доступен.
  - MAPGL_MODELS_URL: URL директории с моделями для стилей. URL должен быть публично доступен.
  - MAPGL_KEYSERVER: URL сервиса API-ключей.
  - MAPGL_RTLPLUGIN: URL плагина для поддержки языков с направлением письма справа налево (RTL).
  - MAPGL_INVALID_KEY_MESSAGE: текст сообщения об ошибке при использовании невалидного ключа для MapGL JS API.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. Обратите внимание, что для использования TLS необходимо создать секрет, содержащий сертификат и приватный ключ.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-mapgl.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис Static API (опционально)

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-staticmaps.yaml
app: access: enabled: true stat: enabled: true url: http://stat-receiver-api/bss/3 log: format: json level: info dgctlDockerRegistry: docker.registry.example.com ingress: className: nginx enabled: true hosts: - host: staticmaps.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - staticmaps.example.com # secretName: secret.tls keys: token: STATIC_API_TOKEN url: http://keys-service-api license: url: https://license tiles: key: TILES_KEY url: http://tiles-api-raster
Где:
- app.access: настройки доступа к сервису API-ключей.
  - enabled: включить ли доступ к сервису API-ключей.
  - stat: настройки взаимодействия с сервисом сбора статистики.
    - enabled: отправлять ли статистику использования ключей.
    - url: URL сервиса сбора статистики.
- app.log: настройки логирования.
  - format: формат логов.
  - level: уровень логирования.
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре api.ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- keys: настройки доступа к сервису API-ключей.
  - token: сервисный токен (см. Установка сервиса API-ключей). Обязательный параметр, если для параметра app.access.enabled указано значение true.
  - url: URL сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes. Обязательный параметр, если для параметра app.access.enabled указано значение true.
- license.url: URL сервиса лицензий.
- tiles: настройки доступа к сервису Tiles API.
  - key: ключ доступа к Tiles API.
  - url: URL сервиса Tiles API. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-staticmaps.yaml.
```
helm upgrade --install --version=VERSION --atomic --values ./values-staticmaps.yaml staticmaps 2gis-on-premise/staticmaps
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис Styles API (опционально)

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-styles.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] log: level: info postgres: host: 'styles-postgresql.storage.example.local' name: 'onpremise_styles' username: '' password: '' s3: host: 's3.storage.example.local:80' secure: false bucket: 'styles' accessKey: '' secretKey: '' publicDomain: '' region: '' verifySsl: false api: resources: requests: cpu: 50m memory: 128Mi limits: cpu: 1 memory: 256Mi ingress: enabled: true className: nginx hosts: - host: styles.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - styles-api.example.com # secretName: secret.tls
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- log.level: уровень логирования.
- postgres: настройки доступа к серверу PostgreSQL.
  - host: имя или IP-адрес хоста PostgreSQL.
  - name: имя базы данных.
  - username: имя пользователя базы данных PostgreSQL.
  - password: пароль для подключения к базе данных PostgreSQL.
- s3: настройки доступа к S3-совместимому хранилищу.
  - host: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - bucket: имя бакета S3 для хранения и публикации стилей.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
  - publicDomain: домен для публичного доступа к S3-совместимому хранилищу по протоколу HTTPS.
  - region: регион S3-совместимого хранилища.
  - verifySsl: включить ли проверку SSL-сертификатов при подключении. Значение по умолчанию: false.
- api.resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- api.ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-styles.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-styles.yaml styles-api 2gis-on-premise/styles-api
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

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

Проверьте сервис Tiles API

Чтобы проверить работу сервиса Tiles API:

Для растровых тайлов: перейдите в браузере по адресу (приведён пример для Москвы):
```
http://tiles-api.example.com/tiles?x=1237&y=640&z=11&v=1
```
Должен отобразиться демонстрационный растровый тайл.
Для векторных тайлов в формате MVT: см. инструкцию в разделе Экспорт векторных тайлов.
Для других векторных тайлов: см. раздел Тестирование MapGL JS API.

Проверьте сервис MapGL JS API

Чтобы проверить работу сервиса MapGL JS API, используйте один из способов:

Перейдите в браузере по доменному имени или IP-адресу сервиса:
```
http://mapgl-js-api.example.com
```

Если вы хотите поменять настройки инициализации карты, создайте файл test.html со следующим содержимым и запустите его в браузере:

<html>
    <head>
        <title>MapGL JS API. On-Premise</title>
        <style>
            #map {
                width: 100%;
                height: 100%;
            }
        </style>
    </head>

    <body>
        <div id="map"></div>
        <script src="//mapgl-js-api.example.com/api.js"></script>
        <script>
            const map = new mapgl.Map('map', {
                center: [55.31878, 25.23584],
                zoom: 13,
                useRtlTextPlugin: 'always-on', // отображение текстов на арабском языке справа налево
            });
        </script>
    </body>
</html>

Должна отобразиться демонстрационная векторная карта, которая использует векторные тайлы, получаемые от сервиса Tiles API.

В этом случае опции style и styleOptions не указываются, и их значения будут разрешены по умолчанию относительно MAPGL_HOST. Если вы планируете использовать собственные стили, см. проверку Styles API.

Проверьте сервис Static API

Выберите произвольные координаты (широта, долгота) на доступной территории.
Сформируйте ссылку:
```
https://staticmaps.example.com/static/2.0?s=640x400&pt={lat,lon}&z=13&key=YOUR_KEY
```
Где:
- s — размер изображения в пикселях.
- pt — координаты маркера (широта, долгота).
- z — уровень масштабирования (от 1 до 18). Чем больше число, тем подробнее карта.
- key — API-ключ для доступа к сервису (если для параметра app.access.enabled указано значение true).
Откройте сформированную ссылку в браузере. При успешном ответе вы получите изображение карты в формате PNG.

Проверьте сервис Styles API

Чтобы подключить пользовательский стиль карты, установите Менеджер Платформы и выполните шаги по загрузке и применению стиля.

7. Установка API поиска

В этом разделе описана установка сервиса Search API. Инструкцию по установке обновлённой версии сервиса (Search API v8) см. в разделе Установка обновлённой версии API поиска.

7.1. Перед установкой

Ознакомьтесь с:
- документацией сервисов поиска;
- архитектурой программного комплекса 2ГИС.
Убедитесь, что выполнены предварительные шаги:

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

Объект	Пример значения	Как получить значение
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Секрет Kubernetes для доступа к реестру Docker	`onpremise-registry-creds`	См. Получение артефактов установки
Endpoint S3-совместимого хранилища артефактов установки	`artifacts.example.com`	См. Получение артефактов установки
Название бакета с артефактами установки	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Путь к файлу манифеста	`manifests/api-platform/1640661259.json`	См. Получение артефактов установки
Endpoint сервиса лицензий	`https://license`	См. Установка сервиса лицензий
Endpoint сервиса API-ключей	`http://keys-service-api`	См. Установка сервиса API-ключей
Endpoint сервиса сбора статистики	`http://stat-receiver`	См. Установка сервиса сбора статистики
Сервисный токен	`CATALOG_APIS_TOKEN`	См. Установка сервиса API-ключей

Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чартах:
- Search API,
- Catalog APIs.
Подробнее о том, как это сделать, см. в документе Системные требования.

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

Пример:
- Доменное имя для Search API: search-api.example.com.
- Доменное имя для Catalog APIs: catalog-api.example.com.

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

Настройте PostgreSQL

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

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

Разместите кластер PostgreSQL с доменным именем catalog-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.
Подключитесь к кластеру от имени суперпользователя (обычно это postgres).
Создайте пользователя базы данных и установите пароль для него:
```
create user dbuser_catalog password '650D7AmZjSR1dkNa';
```
Создайте базу данных, принадлежащую этому пользователю:
```
create database onpremise_catalog owner dbuser_catalog;
```
Установите необходимое внешнее расширение PostGIS для PostgreSQL.

Вы можете получить расширение из репозитория, в котором оно доступно в виде готовых пакетов. Например, для дистрибутивов на базе Debian/Ubuntu установка выполняется командами:
```
sudo apt install postgresql-15-postgis-3
sudo apt install postgis
```

Включите требуемое расширение для базы данных:

\c onpremise_catalog

create schema extensions;
grant usage on schema extensions to public;
grant execute on all functions in schema extensions to public;
alter default privileges in schema extensions grant execute on functions to public;
alter default privileges in schema extensions grant usage on types to public;
create extension if not exists plpgsql with schema pg_catalog;
create extension if not exists postgis with schema extensions;

Создайте API-ключ

Наличие ключа проверяется перед установкой Catalog APIs.

Добавьте первого партнёра и создайте для него API-ключ. В список доступных сервисов для ключа должны быть включены API поиска. См. инструкцию Управление доступом к API.

7.3. Установите сервисы поиска

Установите сервис Search API

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-search.yaml
dgctlDockerRegistry: docker.registry.example.com dgctlStorage: host: artifacts.example.com secure: true bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/api-platform/1640661259.json region: '' api: resources: limits: cpu: 1 memory: 3Gi requests: cpu: 100m memory: 1Gi nginx: resources: limits: cpu: 1 memory: 1Gi requests: cpu: 100m memory: 200Mi customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- dgctlStorage: настройки доступа к хранилищу артефактов установки.
  - host: endpoint S3-совместимого хранилища артефактов установки в формате HOST:PORT.
  - secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
  - bucket: имя бакета S3.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
  - manifest: путь до файла с манифестом в формате manifests/api-platform/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
  - region: регион S3-совместимого хранилища.
- api.resources: настройки вычислительных ресурсов для бэкенд-сервиса API. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- nginx.resources: настройки вычислительных ресурсов для бэкенд-сервиса nginx. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл:
```
helm upgrade --install --version=VERSION --atomic --values ./values-search.yaml search-api 2gis-on-premise/search-api
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис Catalog APIs

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

Настройка импорта данных
Вы можете настроить процесс импорта новых данных для Catalog APIs. За это отвечают настройки группы importer конфигурационного файла (см. ниже).

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-catalog.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/api-platform/1640661259.json region: '' verifySsl: true api: postgres: host: catalog-postgresql.storage.example.local port: 5432 name: onpremise_catalog username: dbuser_catalog password: 650D7AmZjSR1dkNa ingress: enabled: true className: nginx hosts: - host: catalog-api.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - catalog-api.example.com # secretName: secret.tls search: url: http://search-api keys: url: http://keys-service-api token: CATALOG_APIS_TOKEN stat: url: 'http://stat-receiver' enabled: false request: enabled: false search: enabled: false importer: postgres: host: catalog-postgresql.storage.example.local port: 5432 name: onpremise_catalog username: dbuser_catalog password: 650D7AmZjSR1dkNa schemaSwitchEnabled: true cleaner: enabled: true versionLimit: 2 license: url: 'https://license' requestTimeout: 1s customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- 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/api-platform/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
  - region: регион S3-совместимого хранилища.
  - verifySsl: включить ли проверку SSL-сертификатов при подключении к dgctlStorage.host по HTTPS. Значение по умолчанию: true.
- api.postgres: настройки доступа к серверу PostgreSQL.
  - host: имя хоста или IP-адрес сервера.
  - port: порт, на котором слушает сервер.
  - name: имя базы данных.
  - username: имя пользователя.
  - password: пароль пользователя.
- api.ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- search: настройки доступа к сервису Search API.
  - url: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
- keys: настройки сервиса ключей.
  - url: URL сервиса. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - token: сервисный токен для сохранения статистики использования (см. Установка сервиса API-ключей).
- stat: настройки взаимодействия с сервисом сбора статистики.
  - url: URL сервиса сбора статистики.
  - enabled: включите, чтобы отправлять статистику использования ключей.
  - request.enabled: включите, чтобы отправлять статистику по запросам к API.
  - search.enabled: включите, чтобы отправлять данные по поисковым запросам.
- importer: настройки процесса импорта (Kubernetes Importer job). Импорт новых наборов данных происходит, только если для указанного манифеста не происходил импорт ранее.
  - postgres: настройки доступа к серверу PostgreSQL для импорта новых данных об объектах.
    - host: имя хоста или IP-адрес сервера.
    - port: порт, на котором слушает сервер.
    - name: имя базы данных.
    - username: имя пользователя.
    - password: пароль пользователя.
    - schemaSwitchEnabled: разрешить ли работу со схемами.
      - true: каждый импорт данных происходит в новую схему, возможно переключение на старые схемы и их очистка.
      - false: создание новых схем и очистка базы производятся администратором вручную.
    Подробнее см. в разделе Обновление сервиса Catalog APIs.
  - cleaner: настройки автоматического удаления старых наборов данных.
    - enabled: включено ли автоматическое удаление старых наборов данных. Подробнее см. в разделе Обновление сервиса Catalog APIs.
    - versionLimit: количество старых наборов данных, которые нужно хранить.
    См. Жизненный цикл артефактов установки для получения дополнительной информации о работе процесса импорта.
- license: настройки сервиса лицензий.
  - url: URL-адрес сервиса лицензий. Пример: https://license.
  - requestTimeout: таймаут запросов к сервису лицензий.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл:
```
helm upgrade --install --version=VERSION --atomic --wait --timeout 7200s --values ./values-catalog.yaml catalog-api 2gis-on-premise/catalog-api
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Если в конфигурационном файле были указаны настройки importer, то при установке сервиса проверяется наличие данных в базе и при необходимости происходит импорт этих данных в PostgreSQL. Затем Helm выполняет установку самого сервиса.

7.4. Проверьте работоспособность сервисов поиска

С хоста в приватной сети example.com выполните GET-запрос:

curl 'catalog-api.example.com/3.0/items/geocode?key=API_KEY&q=City'

Где:

API_KEY — значение созданного ключа.
City — имя города, о котором вы хотите найти информацию.

При успешной установке сервис вернёт список результатов поиска в формате JSON.

8. Установка API навигации

8.1. Перед установкой

Ознакомьтесь с:
- документацией сервисов навигации;
- архитектурой программного комплекса 2ГИС.
Убедитесь, что выполнены предварительные шаги:

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

Объект	Пример значения	Как получить значение
Endpoint реестра Docker для хранения образов сервисов	`docker.registry.example.com`	См. Получение артефактов установки
Секрет Kubernetes для доступа к реестру Docker	`onpremise-registry-creds`	См. Получение артефактов установки
Endpoint S3-совместимого хранилища артефактов установки	`artifacts.example.com`	См. Получение артефактов установки
Название бакета с артефактами установки	`onpremise-artifacts`	См. Получение артефактов установки
Идентификатор ключа для доступа к артефактам установки	`AKIAIOSFODNN7EXAMPLE`	См. Получение артефактов установки
Секрет ключа для доступа к артефактам установки	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	См. Получение артефактов установки
Путь к файлу манифеста	`manifests/api-platform/1640661259.json`	См. Получение артефактов установки
Endpoint сервиса лицензий	`https://license`	См. Установка сервиса лицензий
Endpoint сервиса API-ключей	`http://keys-service-api`	См. Установка сервиса API-ключей
Endpoint сервиса сбора статистики	`http://stat-receiver`	См. Установка сервиса сбора статистики
Endpoint прокси для API пробок	`http://traffic-proxy`	См. Установка прокси для API пробок
Сервисные токены^*	`DIRECTIONS_TOKEN` `TRUCK_DIRECTIONS_TOKEN` `PAIRS_DIRECTIONS_TOKEN` `PUBLIC_TRANSPORT_TOKEN` `DISTANCE_MATRIX_TOKEN` `ISOCHRONE_TOKEN` `MAP_MATCHING_TOKEN` `TSP_TOKEN` `ROUTES_PLANNER_TOKEN` (для работы с 2ГИС Ситискан)	См. Установка сервиса API-ключей

* В иллюстративных целях предполагается, что сервисные токены доступны для всех продуктов навигации.

Определите, какие API вам необходимо установить:
- Базовые API навигации: Routing API, Directions API, Truck Directions API, Pairs Directions API, Distance Matrix API, Map Matching API и Isochrone API. Подробнее о сервисах см. в обзоре.
- Distance Matrix Async API для расчёта матрицы расстояний для большого количества точек. Может быть установлен отдельно или в сочетании с другими API. Подробнее о сервисе см. на странице архитектуры.
- TSP API для решения задачи коммивояжёра (построить кратчайший маршрут обхода точек). Подробнее о сервисе см. на странице архитектуры.
- Restrictions API для управления собственной информацией о дорожных перекрытиях. Устанавливается в сочетании с другими API. Подробнее о сервисе см. на странице архитектуры.

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

Сервис	Для работы каких API необходим
Navi-Castle	Все
Navi-Attractor	Все
Navi-Back	Все
Navi-Router	Базовые API
Navi-Front	Базовые API
Navi-Restrictions	Restrictions API
Navi-Splitter	Distance Matrix API (часть базовых API)
Distance Matrix Async API	Distance Matrix Async API, TSP API
Navi Async gRPC proxy	Distance Matrix Async API, если запросы к сервису будут отправляться в формате gRPC
VRP Task Manager	TSP API
VRP Solver	TSP API

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

Используйте чарты, соответствующие версии API-платформы

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

Определите доменные имена для сервисов навигации.

Пример:
- Доменное имя для Navi-Front: navi-front.example.com.
- Доменное имя для Distance Matrix Async API: navi-async-matrix.example.com.
- Доменное имя для Restrictions API: navi-restrictions.example.com.

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

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

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

Для установки Distance Matrix Async API

Если вы планируете устанавливать Distance Matrix Async API, выполните дополнительные шаги:

Настройте PostgreSQL:
1. Разместите кластер PostgreSQL с доменным именем navi-async-matrix-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.
2. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).
3. Создайте пользователя базы данных и установите пароль для него:
  create user dbuser_navi_async_matrix password 'wNgJamrIym8UAcdX';
4. Создайте базу данных, принадлежащую этому пользователю:
  create database onpremise_navi_async_matrix owner dbuser_navi_async_matrix;
Настройте доступ к S3-совместимому хранилищу:
1. Разместите S3-совместимое хранилище с доменным именем navi-async-matrix-s3.storage.example.local в приватной сети. Предполагается, что хранилище работает на стандартном порту 80.
2. Создайте ключи для подключения к сервису. Запомните реквизиты.
  
  Пример:
  - Ключ доступа: TRVR4ESNMDDSIXLB3ISV.
  - Секретный ключ: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK.
3. Определите название бакета, который будет использоваться для сервиса.
  
  Пример: navi-async-matrix-bucket.
  
  предупреждение
  По умолчанию Distance Matrix Async API удаляет все файлы старше 14 дней в бакете.
Настройте брокер сообщений Apache Kafka.
1. Разместите кластер Apache Kafka с доменным именем kafka.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 9092.
2. Создайте пользователя для подключения к сервису. Запомните его реквизиты.
  
  Пример:
  - Имя пользователя: kafka-async-matrix.
  - Пароль: 1Y2u3gGvi6VjNHUt.

Для установки TSP API

Если вы планируете устанавливать TSP API, выполните дополнительные шаги:

Настройте PostgreSQL:
1. Разместите кластер PostgreSQL с доменным именем navi-vrp-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.
2. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).
3. Создайте пользователя базы данных и установите пароль для него:
  create user dbuser_navi_vrp password 'wNgJamrIym8UAcdX';
4. Создайте базу данных, принадлежащую этому пользователю:
  create database onpremise_navi_vrp owner dbuser_navi_vrp;
Настройте доступ к S3-совместимому хранилищу:

Определите название бакета, который будет использоваться для сервиса в S3-совместимом хранилище с доменным именем navi-async-matrix-s3.storage.example.local.

Пример: navi-vrp-bucket.
Настройте брокер сообщений Apache Kafka:
1. Разместите кластер Apache Kafka с доменным именем kafka.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 9092.
2. Создайте пользователя для подключения к сервису. Запомните его реквизиты.
  
  Пример:
  - Имя пользователя: kafka-vrp.
  - Пароль: 1Y2u3gGvi6VjNHUt.

Для установки Restrictions API

Если вы планируете устанавливать Restrictions API, дополнительно настройте PostgreSQL:

Разместите кластер PostgreSQL с доменным именем navi-restrictions-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.
Подключитесь к кластеру от имени суперпользователя (обычно это postgres).
Создайте пользователя базы данных и установите пароль для него:
```
create user dbuser_restrictions password 'jwbK65iFrCCcNrkg';
```
Создайте базу данных, принадлежащую этому пользователю:
```
create database onpremise_restrictions owner dbuser_restrictions;
```

8.3. Создайте файл правил

Navi-Back использует файл правил, чтобы указать, какие типы запросов он может обрабатывать. Это позволяет инстансу Navi-Back запрашивать и хранить минимальный набор данных от Navi-Castle, достаточный для обработки указанных типов запросов.

Navi-Router использует файл правил, чтобы определить, какой из инстансов Navi-Back может обработать запрос.

Создайте файл rules.yaml с необходимым набором правил для вашей установки. Вы можете скопировать необходимые блоки из примера ниже.

Структура правила

Одно правило содержит:

name — произвольное имя правила;
queries — список типов запросов, которые может обрабатывать инстанс;
routing — список типов транспорта, маршруты для которых поддерживаются в рамках этого правила.

Тип запросов (`queries`)	Назначение	Каким сервисом используется
`free_roam`	Свободная навигация без маршрута.	Mobile SDK
`routing`	Маршруты для транспорта, кроме общественного.	Directions API, Truck Directions API, Routing API
`ctx`, `public_transport`	Маршруты для общественного транспорта.	Routing API
`get_pairs`	Построение нескольких маршрутов одновременно.	Pairs Directions API
`get_hull`	Построение зон доступности.	Isochrone API
`map_matching`	Восстановление маршрута по точкам.	Map Matching API
`get_dist_matrix`	Синхронная и асинхронная матрица расстояний.	Distance Matrix API
`route_planner`, `area_clustering`	Маршруты для Планировщика задач 2ГИС Ситискан.	CityLens Routes API

Тип транспорта (`routing`)	Значение
`driving`	Автомобили.
`truck`	Грузовики.
`pedestrian`	Пешеходы.
`bicycle`	Велосипеды.
`scooter`	Самокаты.
`motorcycle`	Мотоциклы.
`taxi`	Такси.
`public_transport`, `ctx`	Общественный транспорт.
`emergency`	Экстренные службы.

Рекомендуется объединять правила по типу транспорта, чтобы запросы, связанные с определённым типом транспорта, обрабатывались одним экземпляром Navi-Back. Например:

- name: all-truck
  queries: ["routing", "get_dist_matrix"]
  routing: ["truck"]

Чтобы запросы обслуживались разными экземплярами Navi-Back (например, для приоритетного обслуживания определённых типов запросов или распределения нагрузки), разбейте агрегированное правило на отдельные. Например:

- name: directions-truck
  queries: ["routing"]
  routing: ["truck"]

- name: distance-matrix-truck
  queries: ["get_dist_matrix"]
  routing: ["truck"]

Пример файла правил

Скопируйте из примера только те блоки, которые понадобятся для вашей установки:

rules:
    - name: freeroam
      queries: ["free_roam"]
      routing: []

    - name: all-car
      queries: ["routing", "get_hull", "map_matching", "route_planner", "area_clustering", "get_pairs", "get_dist_matrix"]
      routing: ["driving"]

    - name: all-truck
      queries: ["routing", "get_dist_matrix"]
      routing: ["truck"]

    - name: all-pedestrian
      queries: ["routing", "get_hull", "get_pairs", "get_dist_matrix"]
      routing: ["pedestrian"]

    - name: all-bicycle
      queries: ["routing", "get_hull", "get_pairs", "get_dist_matrix"]
      routing: ["bicycle", "scooter"]

    - name: all-taxi
      queries: ["routing", "get_pairs", "get_dist_matrix"]
      routing: ["taxi"]

    - name: all-motorcycle
      queries: ["routing", "get_hull", "get_dist_matrix"]
      routing: ["motorcycle"]

    - name: all-ctx
      queries: ["public_transport", "get_dist_matrix", "get_hull"]
      routing: ["public_transport", "ctx"]

    - name: emergency
      queries: ["routing"]
      routing: ["emergency"]

    - name: async-car
      queries: ["get_dist_matrix"]
      routing: ["driving"]

    - name: async-truck
      queries: ["get_dist_matrix"]
      routing: ["truck"]

    - name: async-bicycle
      queries: ["get_dist_matrix"]
      routing: ["bicycle", "scooter"]

    - name: async-pedestrian
      queries: ["get_dist_matrix"]
      routing: ["pedestrian"]
    
    - name: async-ctx
      queries: ["get_dist_matrix"]
      routing: ["ctx"]

    - name: route-planner
      queries: ["route_planner", "area_clustering"]
      routing: ["driving"]

8.4. Установите сервисы навигации

Установите сервис Navi-Castle

Установка Navi-Castle обязательна для работы любых API навигации.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-castle.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/api-platform/latest.json region: '' resources: limits: cpu: 1000m memory: 512Mi requests: cpu: 500m memory: 128Mi cron: enabled: import: true restriction: false restrictionImport: true schedule: import: '*/10 * * * *' restriction: "*/5 * * * *" restrictionImport: "*/5 * * * *" concurrencyPolicy: Forbid successfulJobsHistoryLimit: 3 failedJobsHistoryLimit: 3 init: enabled: import: true restriction: false restrictionImport: false customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- 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/api-platform/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
  - region: регион S3-совместимого хранилища.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- cron: настройки cron-заданий (Kubernetes CronJob) для импорта данных. Cron-задание получает актуальные данные из хранилища артефактов установки и затем обновляет их на реплике Navi-Castle. Эти настройки одинаковы для всех реплик сервиса Navi-Castle.
  - enabled.import: флаг, определяющий, включены ли задания для импорта данных. Если задания выключены, то ни одна из реплик Navi-Castle не будет получать обновления данных.
  - enabled.restriction, enabled.restrictionImport: флаги, определяющие, включены ли задания для импорта данных о дорожных перекрытиях из сервиса Restrictions API или поставляемых данных 2ГИС, соответственно. Флаги не могут быть включены одновременно.
  - schedule.import, schedule.restriction, schedule.restrictionImport: расписания выполнения заданий в cron-формате.
  - concurrencyPolicy: политика одновременного выполнения (concurrency policy) для задания.
  - successfulJobsHistoryLimit: ограничение на размер истории выполненных заданий.
  - failedJobsHistoryLimit: ограничение на размер истории невыполненных заданий.
- init: настройки импорта данных при старте сервиса.
  - enabled.import: флаг, определяющий, включен ли импорт данных. Если флаг persistentVolume.enabled отключен, то старые данные будут утеряны при новом импорте.
  - enabled.restriction, enabled.restrictionImport: флаги, определяющие, включен ли сервис Restrictions API или импорт поставляемых данных 2ГИС о дорожных перекрытиях, соответственно. Флаги не могут быть включены одновременно.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-castle.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-castle.yaml navi-castle 2gis-on-premise/navi-castle
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

При первом запуске реплика Navi-Castle получит данные из хранилища артефактов установки. В дальнейшем, эти данные будут обновляться cron-заданием по расписанию.
Проверьте работоспособность Navi-Castle по инструкции сейчас (рекомендуется) или в конце процедуры установки.

Установите сервис Navi-Attractor

Установка Navi-Attractor обязательна для работы любых API навигации.

Выполните шаги ниже для каждого устанавливаемого типа навигации:

Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь. Присвойте файлу имя по схеме values-attractor-<transport>.yaml (например, values-attractor-car.yaml).

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-attractor-TRANSPORT.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] navigroup: async # Если эта сущность Navi-Attractor работает с Distance Matrix Async API kafka: enabled: true groupId: navi-async properties: bootstrap.servers: kafka.example.local:9092 security.protocol: SASL_PLAINTEXT sasl.mechanism: SCRAM-SHA-512 sasl.username: kafka-async-matrix sasl.password: 1Y2u3gGvi6VjNHUt distanceMatrix: taskTopic: navi.attract.task.topic cancelTopic: navi.cancel.topic statusTopic: navi.attract.status.topic # Если эта сущность Navi-Attractor работает с Distance Matrix Async API s3: enabled: true host: navi-async-matrix-s3.storage.example.local:80 bucket: navi-async-matrix-bucket accessKey: TRVR4ESNMDDSIXLB3ISV secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK attractor: appRule: async-car castleUrl: http://navi-castle # Если эта сущность Navi-Attractor работает с прокси для API пробок (используются онлайн-данные) castleUrlProxy: http://traffic-proxy/navi-castle restrictions: enabled: true resources: requests: cpu: 100m memory: 1024Mi limits: cpu: 2 memory: 4000Mi
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- navigroup: идентификатор группы для построения маршрутов. Все компоненты, которые взаимодействуют друг с другом в рамках одного процесса построения маршрутов, должны иметь одинаковое значение этого параметра. Обычно можно использовать две стандартные группы: sync для синхронных сервисов и async для асинхронных сервисов (например, Distance Matrix Async API).
- kafka: настройки доступа к брокеру Apache Kafka для взаимодействия с Distance Matrix Async API. Укажите, только если сущность Navi-Attractor используется для работы с Distance Matrix Async API.
  - groupId: идентификатор группы, которой принадлежит сервис Navi-Attractor.
  - properties: параметры для доступа к серверу Kafka:
    
    Варианты подключения к серверу Kafka
    В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.
    - bootstrap.servers: URL сервера Kafka.
    - sasl.username: имя пользователя Kafka.
    - sasl.password: пароль для пользователя Kafka.
  - distanceMatrix: названия топиков для взаимодействия с сервисом Distance Matrix Async API. Подробную схему взаимодействия см. в разделе Архитектура сервисов навигации.
    - taskTopic: название топика для обмена информацией о задачах. Distance Matrix Async API записывает данные, а Navi-Attractor считывает их.
    - cancelTopic: название топика для отмены или завершения задач. Этот топик общий для Navi-Back и Navi-Attractor.
    - statusTopic: название топика для обмена информацией о статусах задач. Navi-Attractor записывает данные, а Distance Matrix Async API считывает их.
- s3: настройки доступа к S3-совместимому хранилищу для взаимодействия с Distance Matrix Async API. Укажите, только если сущность Navi-Attractor используется для работы с Distance Matrix Async API.
  - host: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - bucket: имя бакета S3 для хранения данных запросов.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
- attractor: настройки сервиса Navi-Attractor.
  - appRule: имя правила из списка rules для устанавливаемого типа навигации.
  - castleUrl: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - castleUrlProxy: URL прокси для получения дорожных перекрытий. Имеет больший приоритет, чем castleUrl.
  - restrictions.enabled: включать ли получение информации о дорожных перекрытиях.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-attractor-<transport>.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./rules.yaml --values ./values-attractor-<transport>.yaml --values ./rules.yaml navi-attractor-<transport> 2gis-on-premise/navi-attractor
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
Повторите шаги выше для следующего типа транспорта, если необходимо.

Установите сервис Navi-Back

Установка Navi-Back обязательна для работы любых API навигации.

Для каждого типа навигации необходимо установить отдельную сущность Navi-Back. Выполните шаги ниже для каждого устанавливаемого типа навигации:

Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь. Присвойте файлу имя по схеме values-back-<service>.yaml (например, values-back-directions-car.yaml).

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-back-SERVICE.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] # Названия групп навигации должны различаться для синхронных и асинхронных сущностей Navi-Back navigroup: async naviback: appRule: directions-car castleUrl: http://navi-castle handlersNumber: 1 # Если эта сущность Navi-Back работает с прокси для API пробок (используются онлайн-данные) ecaUrl: http://traffic-proxy-navi/eca castleUrlProxy: http://traffic-proxy-navi/navi-castle forecastUrl: http://traffic-proxy-navi/forecast longForecastUrl: http://traffic-proxy-navi/long-forecast restrictions: enabled: true indices: etaCorrectionCores: enabled: true proxy: true forecastedLongSpeeds: enabled: true forecastedLongSpeedsIndex: enabled: true forecastedSpeeds: enabled: true forecastedSpeedsIndex: enabled: true onlineSpeeds: enabled: true speedIndex: enabled: true simpleNetwork: emergency: false # Если эта сущность Navi-Back работает с Distance Matrix API behindSplitter: true stat: enabled: false url: 'http://stat-receiver/bss/3' # Если эта сущность Navi-Back не работает с Distance Matrix Async API # (исключение — матрицы расстояний для общественного транспорта) remoteAttractor: enabled: true host: navi-attractor # Если эта сущность Navi-Back не работает с Distance Matrix Async API envoy: resources: requests: cpu: 0.1 memory: 128Mi limits: cpu: 0.1 memory: 128Mi replicaCount: 1 resources: limits: cpu: 2000m memory: 16000Mi requests: cpu: 1000m memory: 1024Mi license: url: 'https://license' # Если эта сущность Navi-Back работает с Distance Matrix Async API kafka: enabled: true groupId: navi-back handlersNumber: 2 properties: bootstrap.servers: kafka.example.local:9092 security.protocol: SASL_PLAINTEXT sasl.mechanism: SCRAM-SHA-512 sasl.username: kafka-async-matrix sasl.password: 1Y2u3gGvi6VjNHUt distanceMatrix: taskTopic: navi.<navigationType>.task.topic cancelTopic: navi.cancel.topic statusTopic: navi.one.to.many.topic # Если эта сущность Navi-Back работает с Distance Matrix Async API s3: enabled: true host: navi-async-matrix-s3.storage.example.local:80 bucket: navi-async-matrix-bucket accessKey: TRVR4ESNMDDSIXLB3ISV secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- navigroup: идентификатор группы для построения маршрутов. Все компоненты, которые взаимодействуют друг с другом в рамках одного процесса построения маршрутов, должны иметь одинаковое значение этого параметра. Обычно можно использовать две стандартные группы: sync для синхронных сервисов и async для асинхронных сервисов (например, Distance Matrix Async API).
- naviback: настройки сервиса Navi-Back.
  - appRule: имя правила из списка rules для устанавливаемого типа навигации. Обратите внимание, что для построения маршрутов и для вычисления матриц расстояний используются разные правила.
  - castleUrl: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - handlersNumber: количество параллельных потоков расчётов. Если обрабатывается много небольших задач (коротких маршрутов), рекомендуется установить значение ниже, чем указано в параметре kafka.handlersNumber. Если обрабатывается немного крупных задач, рекомендуется указывать значение, равное значению kafka.handlersNumber.
  - ecaUrl: URL прокси для получения скоростей.
  - castleUrlProxy: URL прокси для получения дорожных перекрытий. Имеет больший приоритет, чем castleUrl.
  - forecastUrl: URL прокси для получения краткосрочных прогнозов скоростей.
  - longForecastUrl: URL прокси для получения долгосрочных прогнозов скоростей.
  - restrictions.enabled: включать ли получение информации о дорожных перекрытиях.
  - indices: подключение данных для скачивания файлов. Если вы получаете данные через прокси для API пробок, параметры ниже обязательны и должны иметь значение true:
    - etaCorrectionCores: коэффициенты коррекции времени в пути.
      - enabled: включать ли получение данных о коэффициентах коррекции времени в пути.
      - proxy: использовать URL прокси naviback.castleUrlProxy вместо naviback.castleUrl или naviback.castleHost.
    - forecastedLongSpeeds.enabled: долгосрочный прогноз скоростей (от часа до суток).
    - forecastedLongSpeedsIndex.enabled: получение индекса долгосрочных прогнозов скоростей.
    - forecastedSpeeds.enabled: краткосрочный прогноз скоростей (до 1 часа).
    - forecastedSpeedsIndex.enabled: получение индекса краткосрочных прогнозов скоростей.
    - onlineSpeeds.enabled: текущие скорости, могут обновляться раз в минуту.
    - speedIndex.enabled: получение индекса текущих скоростей.
  - simpleNetwork.emergency: включить поддержку построения маршрутов для экстренных служб.
    
    Обратите внимание, что для построения таких маршрутов необходимо также добавить тип маршрутизации emergency в один из проектов в вашем файле правил.
  - behindSplitter: взаимодействует ли Navi-Back с сервисом Navi-Splitter. Укажите значение true, только если сущность Navi-Back используется для работы Distance Matrix API (в синхронном режиме).
  - stat: настройки взаимодействия с сервисом сбора статистики.
    - enabled: включите, чтобы отправлять статистику использования ключей.
    - url: URL сервиса сбора статистики.
- remoteAttractor: настройки взаимодействия Navi-Attractor. Укажите, только если сущность Navi-Back не используется для работы с Distance Matrix Async API (исключение — асинхронное вычисление матриц расстояний для общественного транспорта, для которого требуется взаимодействие с Navi-Attractor).
  - enabled: требуется ли взаимодействие с Navi-Attractor.
  - host: URL сервиса Navi-Attractor.
- envoy: настройки балансировщика. Укажите, только если сущность Navi-Back не используется для работы с Distance Matrix Async API.
- replicaCount: число реплик сервиса Navi-Back.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- license: настройки сервиса лицензий.
  - url: URL-адрес сервиса лицензий. Пример: https://license.
- kafka: настройки доступа к брокеру Apache Kafka для взаимодействия с Distance Matrix Async API.
  - groupId: идентификатор группы, которой принадлежит сервис Navi-Back.
  - handlersNumber: количество задач, которые одновременно читаются из Apache Kafka. Если обрабатывается много небольших задач (коротких маршрутов), рекомендуется установить значение выше, чем указано в параметре naviback.handlersNumber. Если обрабатывается немного крупных задач, рекомендуется указывать значение, равное значению naviback.handlersNumber.
  - properties: параметры для доступа к серверу Kafka:
    
    Варианты подключения к серверу Kafka
    В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.
    - bootstrap.servers: URL сервера Kafka.
    - sasl.username: имя пользователя Kafka.
    - sasl.password: пароль для пользователя Kafka.
  - distanceMatrix: названия топиков для взаимодействия с сервисом Distance Matrix Async API. Подробную схему взаимодействия см. в разделе Архитектура сервисов навигации.
    - taskTopic: название топика для обмена информацией о задачах. Distance Matrix Async API записывает данные о новых задачах, а Navi-Back считывает их. Придумайте и укажите navigationType в зависимости от типа навигации: например, bicycle или pedestrian. При использовании нескольких сущностей Navi-Back укажите уникальный taskTopic для каждой сущности.
      
      Для асинхронных матриц расстояний для общественного транспорта нужно настроить две сущности Navi-Back, которые будут использовать разные топики Apache Kafka:
      - Для сущности navi-back-distance-matrix-ctx (вычисление матриц) укажите navi.ctx.task.topic в параметре taskTopic.
      - Для сущности navi-back-find-platform (поиск остановочных платформ) укажите navi.find.platform.task.topic в параметре taskTopic.
    - cancelTopic: название топика для отмены или завершения задач. Этот топик общий для Navi-Back и Navi-Attractor.
    - statusTopic: название топика для обмена информацией о статусах задач. Navi-Back записывает данные о статусах, а Distance Matrix Async API считывает их.
      
      Для асинхронных матриц расстояний для общественного транспорта нужно настроить две сущности Navi-Back, которые будут использовать разные топики Apache Kafka:
      - Для сущности navi-back-distance-matrix-ctx (вычисление матриц) укажите navi.one.to.many.topic в параметре statusTopic.
      - Для сущности navi-back-find-platform (поиск остановочных платформ) укажите navi.find.platform.status.topic в параметре statusTopic.
- s3: настройки доступа к S3-совместимому хранилищу для взаимодействия с Distance Matrix Async API.
  - host: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - bucket: имя бакета S3 для хранения данных запросов.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-back-<service>.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./rules.yaml --values ./values-back-<service>.yaml navi-back-<service> 2gis-on-premise/navi-back
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Пример команды для установки Directions API для автомобильных маршрутов:
```
helm upgrade --install --version=VERSION --atomic --values ./rules.yaml --values ./values-back-directions-car.yaml navi-back-directions-car 2gis-on-premise/navi-back
```
Проверьте работоспособность Navi-Back по инструкции сейчас (рекомендуется) или в конце процедуры установки.
Повторите шаги выше для следующего типа навигации.

Установите сервис Navi-Splitter (опционально)

Установка Navi-Splitter обязательна, если вы планируете использовать Distance Matrix API (в синхронном режиме).

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-splitter.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] splitter: appRule: # Если планируется работа с Distance Matrix API для общественного транспорта ctxUrl: http://navi-back-distance-matrix-ctx.svc/ctx/2.0/?source=distance_matrix ctxBaseUrl: http://navi-back-distance-matrix-ctx.svc/ctx/2.0 findPlatformUrl: http://navi-back-distance-matrix-ctx/find_platforms attractor: enabled: true host: navi-attractor.svc oneToMany: enabled: true host: navi-back-headless.svc passThrough: enabled: true host: navi-back.svc
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- splitter: настройки сервиса Navi-Splitter.
  - appRule: имя правила из списка rules для устанавливаемого типа навигации.
  - ctxUrl: полный URL хоста Navi-Back для работы с Distance Matrix API для общественного транспорта. Укажите, если планируете работать с таким типом матриц.
  - ctxBaseUrl: базовый URL хоста Navi-Back для работы с Distance Matrix API для общественного транспорта. Укажите, если планируете работать с таким типом матриц.
  - findPlatformUrl: полный URL хоста для поиска остановочных платформ при построении маршрутов общественного транспорта в формате http(s)://HOST:PORT/find_platforms.
- attractor: настройка сервиса Navi-Attractor.
  - enabled: включена ли интеграция с Navi-Attractor.
  - host: имя хоста сервиса Navi-Attractor.
- oneToMany: настройка поддержки маршрута от одной точки к нескольким.
  - enabled: включена ли поддержка маршрута от одной точки к нескольким через Navi-Back. Укажите значение true, если планируете работать с Distance Matrix API.
  - host: имя хоста Navi-Back.
- passThrough: настройка проксирования запросов напрямую в другой сервис.
  - enabled: включено ли проксирование напрямую в Navi-Back. Укажите значение true, если вы планируете работать с другими базовыми API кроме Distance Matrix API.
  - host: имя хоста Navi-Back, куда проксируются запросы.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-splitter.yaml.
```
helm upgrade --install --version=VERSION --atomic --values ./values-splitter.yaml navi-splitter 2gis-on-premise/navi-splitter
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
Проверьте работоспособность Navi-Splitter по инструкции сейчас (рекомендуется) или в конце процедуры установки.

Установите сервис Navi-Router

Установка Navi-Router обязательна, если вы планируете использовать базовые API навигации.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-router.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] navigroup: sync router: logLevel: Warning castleUrl: http://navi-castle.svc keys: enabled: true url: http://keys-service-api/service/v1/keys refreshIntervalSec: 30 downloadTimeoutSec: 30 apis: comboroutes-api: '' directions-api: '' distance-matrix-api: '' freeroam-api: '' isochrone-api: '' map-matching-api: '' pairs-directions-api: '' ppnot-api: '' public-transport-api: '' truck-directions-api: '' truck-distance-matrix-api: '' routing-api: '' route-planner-api: '' # для работы с 2ГИС Ситискан replicaCount: 2 resources: limits: cpu: 2000m memory: 1024Mi requests: cpu: 500m memory: 128Mi
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- navigroup: идентификатор группы для построения маршрутов. Все компоненты, которые взаимодействуют друг с другом в рамках одного процесса построения маршрутов, должны иметь одинаковое значение этого параметра. Обычно можно использовать две стандартные группы: sync для синхронных сервисов и async для асинхронных сервисов (например, Distance Matrix Async API).
- router: настройки сервиса Navi-Router.
  - logLevel: уровень логирования, по умолчанию Warning. Доступные уровни: Verbose, Info, Warning, Error, Fatal.
  - castleUrl: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
- keys: настройки сервиса ключей. Если не задавать эти настройки, то проверка API-ключа для запроса будет пропущена.
  - enabled: включено ли использование сервиса ключей.
  - url: URL API-endpoint сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - refreshIntervalSec: интервал обновления ключей в секундах.
  - downloadTimeoutSec: таймаут загрузки ключей в секундах.
  - apis: сервисные токены для сохранения статистики использования (см. Сервис ключей).
- replicaCount: число реплик сервиса Navi-Router.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-router.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./rules.yaml --values ./values-router.yaml navi-router 2gis-on-premise/navi-router
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
Проверьте работоспособность Navi-Router по инструкции сейчас (рекомендуется) или в конце процедуры установки.

Установите сервис Navi-Front

Установка Navi-Front обязательна, если вы планируете использовать базовые API навигации.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-front.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] navigroup: sync replicaCount: 2 resources: limits: cpu: 100m memory: 128Mi requests: cpu: 100m memory: 128Mi ingress: enabled: true className: nginx hosts: - host: navi-front.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - navi-front.example.com # secretName: secret.tls
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- navigroup: идентификатор группы для построения маршрутов. Все компоненты, которые взаимодействуют друг с другом в рамках одного процесса построения маршрутов, должны иметь одинаковое значение этого параметра. Обычно можно использовать две стандартные группы: sync для синхронных сервисов и async для асинхронных сервисов (например, Distance Matrix Async API).
- replicaCount: число реплик сервиса Navi-Front.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-front.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-front.yaml navi-front 2gis-on-premise/navi-front
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
Проверьте работоспособность Navi-Front по инструкции сейчас (рекомендуется) или в конце процедуры установки.

Установите сервис Distance Matrix Async API (опционально)

Установка Distance Matrix Async API обязательна, если вы планируете использовать Distance Matrix Async API или TSP API.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-navi-async-matrix.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] resources: requests: cpu: 100m memory: 100Mi limits: cpu: 1 memory: 1Gi dm: citiesUrl: http://navi-castle/cities.conf merger: resources: requests: cpu: 100m memory: 100Mi limits: cpu: 1 memory: 1Gi serviceAccount: create: true s3: host: http://navi-async-matrix-s3.storage.example.local:80 bucket: navi-async-matrix-bucket accessKey: TRVR4ESNMDDSIXLB3ISV secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK region: '' db: host: navi-async-matrix-postgresql.storage.example.local port: 5432 name: onpremise_navi_async_matrix user: dbuser_navi_async_matrix password: wNgJamrIym8UAcdX schema: public tls: enabled: false rootCert: '' cert: '' key: '' mode: verify-full kafka: groupId: navi_async properties: bootstrap.servers: kafka.example.local:9092 security.protocol: SASL_PLAINTEXT sasl.mechanism: SCRAM-SHA-512 sasl.plain.username: kafka-async-matrix sensitiveProperties: sasl.plain.password: 1Y2u3gGvi6VjNHUt cancelTopic: navi.cancel.topic mergerGroupId: navi_async_matrix_merger mergerStatusTopic: navi.merger.status.topic mergerTaskTopic: navi.merger.task.topic attractTopic: navi.attract.status.topic oneToManyTopic: navi.one.to.many.topic vrpStatusTopic: navi.tsp.message.bus.topic findPlatformTopic: navi.find.platform.status.topic # для маршрутов на общественном транспорте maxMessageSizeBytes: 1048576 taskTopicRules: - topic: navi.task.topic default: true type: car - topic: navi.ctx.task.topic # для маршрутов на общественном транспорте type: public-transport default: true attractTopicRules: - topic: navi.attract.task.topic default: true type: car # Для маршрутов на общественном транспорте findPlatformTopicRules: - topic: navi.find.platform.task.topic default: true type: public-transport keys: url: http://keys-service-api/service/v1/keys token: DISTANCE_MATRIX_TOKEN ingress: enabled: true className: nginx hosts: - host: navi-async-matrix.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - navi-async-matrix.example.com # secretName: secret.tls customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- dm: настройки сервиса Distance Matrix Async API.
  - citiesUrl: URL информации о городах, предоставляемой сервисом Navi-Castle.
  - merger: настройки сервиса Distance Matrix Async Merger.
- serviceAccount.create: создать ли сервисный аккаунт.
- s3: настройки доступа к S3-совместимому хранилищу.
  - host: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - bucket: имя бакета S3 для хранения данных запросов. По умолчанию Distance Matrix Async API удаляет все файлы старше 14 дней в бакете.
  - accessKey: идентификатор ключа для доступа к бакету S3.
  - secretKey: секретный ключ для доступа к бакету S3.
  - region: регион S3-совместимого хранилища.
- db: настройки доступа к серверу PostgreSQL.
  - host: имя хоста или IP-адрес сервера.
  - port: порт, на котором слушает сервер.
  - name: имя базы данных.
  - user и password: реквизиты для доступа к базе данных, указанной в параметре name. Пользователь должен быть либо владельцем этой базы данных, либо суперпользователем.
  - schema: используемая схема PostgreSQL. Значение по умолчанию - public.
  - tls: настройки mTLS-соединения с базой данных.
    - enabled: включено ли mTLS-соединение с сервером PostgreSQL.
    - rootCert: файл корневого сертификата.
    - cert: сертификат сервера PostgreSQL.
    - key: ключ сервера PostgreSQL.
    - mode: уровень защиты, один из следующих:
      - verify-full (рекомендуется): обеспечивается защита от прослушивания и атаки посредника.
      - verify-ca: обеспечивается защита от прослушивания, защита от атаки посредника зависит от политики центра сертификации.
      - require: обеспечивается защита от прослушивания.
      - prefer: возможна защита от прослушивания, если это поддерживает сервер.
      - allow: возможна защита от прослушивания, если этого требует сервер.
      - disable: защита не обеспечивается.
- kafka: настройки доступа к брокеру Apache Kafka. Подробную схему взаимодействия сервисов через Apache Kafka см. в разделе Архитектура сервисов навигации.
  - groupId: идентификатор группы, которой принадлежит сервис Distance Matrix Async API.
  - properties: параметры для доступа к серверу Kafka:
    
    Варианты подключения к серверу Kafka
    В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.
    - bootstrap.servers: URL сервера Kafka.
    - sasl.plain.username: имя пользователя Kafka.
  - sensitiveProperties.sasl.plain.password: пароль для пользователя Kafka.
  - cancelTopic: название топика для отмены задач или получения информации об их завершении. Этот топик общий для Navi-Back и Navi-Attractor.
  - mergerGroupId: идентификатор группы, которой принадлежит сервис Distance Matrix Async Merger.
  - mergerStatusTopic: название топика для получения информации о статусе задач Distance Matrix Async Merger. Distance Matrix Async Merger записывает данные, а Distance Matrix Async API считывает их.
  - mergerTaskTopic: название топика для получения задач Distance Matrix Async Merger. Distance Matrix Async API записывает данные, а Distance Matrix Async Merger считывает их.
  - attractTopic: название топика для получения результатов задач от Navi-Attractor. Navi-Attractor записывает данные, а Distance Matrix Async API считывает их.
  - oneToManyTopic: название топика для обмена информацией о статусах задач. Navi-Back записывает данные, а Distance Matrix Async API считывает их.
  - vrpStatusTopic: название топика для обмена сообщениями с сервисом VRP Task Manager.
  - findPlatformTopic: название топика для данных об остановочных платформах общественного транспорта.
  - maxMessageSizeBytes: максимальный размер сообщений в байтах, которые можно передавать через Apache Kafka. Стандартное значение — 1 Мб. Если сообщение превышает этот порог, оно сохраняется и передаётся через S3-совместимое хранилище. При настройке параметра учитывайте время хранения данных в Apache Kafka (retention_time), размер очереди и политику очистки базы данных.
  - taskTopicRules: информация о топиках, в которые сервис будет направлять запросы. Задаётся как список, в каждом элементе которого должны присутствовать два параметра:
    - topic: название топика Navi-Back. Distance Matrix Async API записывает данные, а Navi-Back считывает их.
    - projects или default: параметры, определяющие, какие запросы направлять в этот топик.
      
      Distance Matrix Async API распределяет запросы по топикам в зависимости от проекта, к которому они относятся. Для всех топиков, кроме топика по умолчанию, должна быть указана настройка projects, содержащая список проектов (см. файл правил). Для топика по умолчанию должна быть указана настройка default: true. В топик по умолчанию будут направляться запросы, относящиеся к проектам, не упомянутым в projects для других топиков.
      
      В конфигурации должен быть задан один и только один топик с настройкой default: true.
    - type: тип транспорта для построения маршрутов.
  - attractTopicRules: правила для соотнесения типов запросов с топиками.
    - topic: название топика Navi-Attractor. Distance Matrix Async API записывает данные, а Navi-Attractor считывает их.
    - projects или default: параметры, определяющие, какие запросы направлять в этот топик.
      
      Distance Matrix Async API распределяет запросы по топикам в зависимости от проекта, к которому они относятся. Для всех топиков, кроме топика по умолчанию, должна быть указана настройка projects, содержащая список проектов (см. файл правил). Для топика по умолчанию должна быть указана настройка default: true. В топик по умолчанию будут направляться запросы, относящиеся к проектам, не упомянутым в projects для других топиков.
      
      В конфигурации должен быть задан один и только один топик с настройкой default: true.
    - type: тип транспорта для построения маршрутов.
  - findPlatformTopicRules: правила для соотнесения типов запросов с топиками.
    - topic: название топика для данных об остановочных платформах общественного транспорта.
    - projects или default: параметры, определяющие, какие запросы направлять в этот топик.
      
      Distance Matrix Async API распределяет запросы по топикам в зависимости от проекта, к которому они относятся. Для всех топиков, кроме топика по умолчанию, должна быть указана настройка projects, содержащая список проектов (см. файл правил). Для топика по умолчанию должна быть указана настройка default: true. В топик по умолчанию будут направляться запросы, относящиеся к проектам, не упомянутым в projects для других топиков.
      
      В конфигурации должен быть задан только один топик с настройкой default: true.
    - type: тип транспорта для построения маршрутов.
- keys: настройки сервиса ключей.
  - url: URL сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - token: сервисный токен (см. Установка сервиса API-ключей).
- ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-navi-async-matrix.yaml.
```
helm upgrade --install --version=VERSION --atomic --values ./values-navi-async-matrix.yaml navi-async-matrix 2gis-on-premise/navi-async-matrix
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис Navi Async gRPC proxy (опционально)

Установка Navi Async gRPC proxy обязательна, если запросы к Distance Matrix Async API будут приходить в формате gRPC.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-navi-async-grpc-proxy.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] dm: url: http://navi-async-matrix.host port: 80
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- dm: настройки доступа к сервису Distance Matrix Async API.
  - url: URL хоста.
  - port: порт, на котором слушает сервер.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-navi-async-grpc-proxy.yaml.
```
helm upgrade --install --version=VERSION --atomic --values ./values-navi-async-grpc-proxy.yaml navi-async-grpc-proxy 2gis-on-premise/navi-async-grpc-proxy
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис VRP Solver (опционально)

Установка VRP Solver обязательна, если вы планируете использовать TSP API.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-vrp-solver.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] resources: limits: cpu: 1000m memory: 2Gi requests: cpu: 3000m memory: 8Gi kafka: groupId: navi_vrp_solver properties: bootstrap.servers: kafka.example.local:9092 security.protocol: SASL_PLAINTEXT sasl.mechanism: SCRAM-SHA-512 sasl.plain.username: kafka-async-matrix sensitiveProperties: sasl.plain.password: 1Y2u3gGvi6VjNHUt taskTopic: navi.tsp.task.topic statusTopic: navi.tsp.status.topic s3: url: http://navi-async-matrix-s3.storage.example.local:80 dm: bucket: navi-async-matrix-bucket accessKey: TRVR4ESNMDDSIXLB3ISV secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK vrp: bucket: navi-vrp-bucket accessKey: TRVR4ESNMDDSIXLB3ISV secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK # Для автомобильных и грузовых маршрутов naviFront: url: http://navi-front/carrouting/6.0.1/global key: key
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- kafka: настройки доступа к брокеру Apache Kafka.
  - groupId: идентификатор группы, которой принадлежит сервис VRP Solver.
  - properties: параметры для доступа к серверу Kafka:
    
    Варианты подключения к серверу Kafka
    В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.
    - bootstrap.servers: URL сервера Kafka.
    - sasl.plain.username: имя пользователя Kafka.
  - sensitiveProperties.sasl.plain.password: пароль для пользователя Kafka.
  - taskTopic: название топика для получения задач от VRP Task Manager.
  - statusTopic: название топика для отправки запросов к VRP Task Manager.
- s3: настройки доступа к S3-совместимому хранилищу.
  - url: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - dm: настройки доступа для хранения результатов расчётов матриц расстояний.
    - bucket: имя бакета S3 для сервиса Distance Matrix Async API.
    - accessKey: идентификатор ключа для доступа к бакету S3.
    - secretKey: секретный ключ для доступа к бакету S3.
  - vrp: настройки доступа для хранения результатов расчётов VRP.
    - bucket: имя бакета S3.
    - accessKey: идентификатор ключа для доступа к бакету S3.
    - secretKey: секретный ключ для доступа к бакету S3.
- naviFront: настройки доступа к сервису Navi-Front для автомобильных и грузовых маршрутов.
  - url: URL сервиса Navi-Front.
  - key: API-ключ для доступа к сервису Navi-Front.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-vrp-solver.yaml.
```
helm upgrade --install --version=VERSION --atomic --values ./values-vrp-solver.yaml navi-vrp-solver 2gis-on-premise/navi-vrp-solver
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис VRP Task Manager (опционально)

Установка VRP Task Manager обязательна, если вы планируете использовать TSP API.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-vrp-task-manager.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] resources: limits: cpu: 1000m memory: 2Gi requests: cpu: 3000m memory: 8Gi kafka: solver: groupId: navi_vrp_task_manager properties: bootstrap.servers: kafka.example.local:9092 security.protocol: SASL_PLAINTEXT sasl.mechanism: SCRAM-SHA-512 sasl.plain.username: kafka-async-matrix sensitiveProperties: sasl.plain.password: 1Y2u3gGvi6VjNHUt dm: groupId: navi_vrp_task_manager properties: bootstrap.servers: kafka.example.local:9092 security.protocol: SASL_PLAINTEXT sasl.mechanism: SCRAM-SHA-512 sasl.plain.username: kafka-async-matrix sensitiveProperties: sasl.plain.password: 1Y2u3gGvi6VjNHUt taskTopic: navi.tsp.task.topic statusTopic: navi.tsp.status.topic messageBusTopic: navi.tsp.message.bus.topic s3: url: http://navi-async-matrix-s3.storage.example.local:80 publicUrl: http://navi-async-matrix-s3.storage.example.local:80 vrp: bucket: navi-vrp-bucket accessKey: TRVR4ESNMDDSIXLB3ISV secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK db: host: navi-vrp-postgresql.storage.example.local port: 5432 name: onpremise_navi_vrp user: dbuser_navi_vrp password: wNgJamrIym8UAcdX keys: url: http://keys-service-api/service/v1/keys token: TSP_TOKEN dm: url: http://navi-async-matrix.host key: key cities: linkToCitiesFile: http://castle.svc/cities.conf
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
- kafka: настройки доступа к брокеру Apache Kafka.
  - solver: настройки для сервиса VRP Task Manager.
    - groupId: идентификатор группы, которой принадлежит сервис VRP Task Manager.
    - properties: параметры для доступа к серверу Kafka:
      
      Варианты подключения к серверу Kafka
      В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.
      - bootstrap.servers: URL сервера Kafka.
      - sasl.plain.username: имя пользователя Kafka.
    - sensitiveProperties.sasl.plain.password: пароль пользователя Kafka.
  - dm: настройки для сервиса Distance Matrix Async API.
    - groupId: идентификатор группы, которой принадлежит сервис VRP Task Manager.
    - properties: параметры для доступа к серверу Kafka:
      
      Варианты подключения к серверу Kafka
      В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.
      - bootstrap.servers: URL сервера Kafka.
      - sasl.plain.username: имя пользователя Kafka.
    - sensitiveProperties.sasl.plain.password: пароль пользователя Kafka.
  - taskTopic: название топика для отправки задач сервису VRP Solver.
  - statusTopic: название топика для получения результатов решения задач от VRP Solver.
  - messageBusTopic: название топика для обмена сообщениями с сервисом Distance Matrix Async API.
- s3: настройки доступа к S3-совместимому хранилищу.
  - url: endpoint S3-совместимого хранилища в формате HOST:PORT.
  - publicUrl: проксируемый адрес для доступа к S3-совместимому хранилищу.
  - vrp: настройки доступа для хранения результатов расчётов VRP.
    - bucket: имя бакета S3.
    - accessKey: идентификатор ключа для доступа к бакету S3.
    - secretKey: секретный ключ для доступа к бакету S3.
- db: настройки доступа к серверу PostgreSQL.
  - host: имя хоста или IP-адрес сервера.
  - port: порт, на котором слушает сервер.
  - name: имя базы данных.
  - user и password: реквизиты для доступа к базе данных, указанной в параметре name. Пользователь должен быть либо владельцем этой базы данных, либо суперпользователем.
- keys: настройки доступа к сервису API-ключей.
  - url: URL сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
  - token: сервисный токен (см. Установка сервиса API-ключей).
- dm: настройки доступа к Distance Matrix Async API.
  - url: URL сервиса Distance Matrix Async API.
  - key: API-ключ для доступа к сервису. См. инструкцию Управление доступом к API.
- cities.linkToCitiesFile: URL файла cities.conf c информацией о городах, доступных для VRP Task Manager.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-vrp-task-manager.yaml.
```
helm upgrade --install --version=VERSION --atomic --values ./values-vrp-task-manager.yaml navi-vrp-task-manager 2gis-on-premise/navi-vrp-task-manager
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

Установите сервис Restrictions API (опционально)

Установка Restrictions API обязательна, если вы планируете использовать только собственную информацию о дорожных перекрытиях. Одновременное использование Restrictions API и поставляемых данных 2ГИС приведёт к некорректной работе: подробнее см. в разделе Работа с дорожными перекрытиями.

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-restrictions.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] naviBackHost: 'navi-back-directions-car' naviCastleHost: 'navi-castle' postgres: host: navi-restrictions-postgresql.storage.example.local port: 5432 name: onpremise_restrictions user: dbuser_restrictions password: jwbK65iFrCCcNrkg api: key: '' ingress: enabled: true className: nginx hosts: - host: navi-restrictions.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - navi-restrictions.example.com # secretName: secret.tls cron: enabled: true schedule: '1 * * * *' concurrencyPolicy: Forbid successfulJobsHistoryLimit: 3 failedJobsHistoryLimit: 3 projects: - moscow maxAttributesFetcherRps: 25 customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- naviBackHost: имя хоста любого установленного сервиса Navi-Back.
- naviCastleHost: имя хоста Navi-Castle.
- postgres: настройки доступа к серверу PostgreSQL.
  - host: имя хоста или IP-адрес сервера.
  - port: порт, на котором слушает сервер.
  - name: имя базы данных.
  - user and password: реквизиты для доступа к базе данных, указанной в параметре name. Пользователь должен быть либо владельцем этой базы данных, либо суперпользователем.
- api: настройки API сервиса.
  - key: API-ключ для взаимодействия с сервисами навигации. Должен совпадать с настройкой restrictions.key сервиса Navi-Castle.
  - ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
- cron: настройки cron-заданий (Kubernetes CronJob) для получения информации от сервисов навигации.
  - enabled: флаг, определяющий, включено ли задание.
  - schedule: расписание выполнения заданий в cron-формате.
  - concurrencyPolicy: политика одновременного выполнения (concurrency policy) для задания.
  - successfulJobsHistoryLimit: ограничение на размер истории выполненных заданий.
  - failedJobsHistoryLimit: ограничение на размер истории невыполненных заданий.
  - projects: список проектов Navi-Back (см. Файл правил).
  - maxAttributesFetcherRps: максимальное количество запросов к edgeAttributesUrlTemplate в секунду.
- customCAs: настройки пользовательских сертификатов.
  - bundle: текстовое представление сертификата в формате X.509 PEM public-key.
  - certsPath: директория для монтирования сертификата внутри контейнера.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-restrictions.yaml:
```
helm upgrade --install --version=VERSION --atomic --wait-for-jobs --values ./values-restrictions.yaml navi-restrictions 2gis-on-premise/navi-restrictions
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

предупреждение
Версии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
В конфигурационном файле Navi-Castle отредактируйте настройки castle.restrictions и cron следующим образом:
```
castle:
  restrictions:
    key: secret
    url: http://navi-restrictions.example.local

cron:
  enabled:
    import: true
    restriction: true
  schedule:
    import: '*/10 * * * *'
    restriction: '*/10 * * * *'
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
```
Где:
- castle: настройки Navi-Castle.
  - restrictions.key: ключ для взаимодействия с сервисом Restrictions API. Любая строка.
  - restrictions.url: URL сервиса Restrictions API. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
- cron: настройки cron-заданий (Kubernetes CronJob) для импорта данных. Cron-задание получает актуальные данные из хранилища артефактов установки и затем обновляет их на реплике Navi-Castle. Эти настройки одинаковы для всех реплик сервиса Navi-Castle.
  - enabled.import, enabled.restriction: флаги, определяющие, включены ли задания для импорта данных о дорожных перекрытиях из сервиса Restrictions API. Если задания выключены, то ни одна из реплик Navi-Castle не будет получать обновления данных.
  - schedule.import, schedule.restriction: расписания выполнения заданий в cron-формате.
Обновите сервис Navi-Castle, используя отредактированный конфигурационный файл values-castle.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-castle.yaml navi-castle 2gis-on-premise/navi-castle
```
В параметре --version укажите ту же версию API-платформы, что и при прошлом выполнении команды.

8.5. Проверьте работоспособность сервисов навигации

Проверьте сервис Navi-Castle

Чтобы проверить работу сервиса Navi-Castle:

Пробросьте порт сервиса с помощью kubectl:
```
kubectl port-forward navi-castle-0 7777:8080
```

Отправьте GET-запрос на корневой endpoint (/) с использованием cURL или аналогичного инструмента:

curl -Lv 'http://127.0.0.1:7777/'

Вы должны получить в ответ HTML-страницу со списком всех файлов и папок, подобную этой:

<html>
    <head>
        <title>Index of /</title>
    </head>
    <body>
        <h1>Index of /</h1>
        <hr />
        <pre>
            <a href="../">../</a>
            <a href="lost%2Bfound/">lost+found/</a>          09-Mar-2022 13:33        -
            <a href="packages/">packages/</a>                09-Mar-2022 13:33        -
            <a href="index.json">index.json</a>              09-Mar-2022 13:33      634
            <a href="index.json.zip">index.json.zip</a>      09-Mar-2022 13:33      357
        </pre>
        <hr />
    </body>
</html>

Проверьте сервис Navi-Back

Чтобы проверить работу инстанса Navi-Back:

Пробросьте порт сервиса с помощью kubectl:
```
kubectl port-forward service/navi-back-<service> 7777:8080
```
Где navi-back-<service> — имя инстанса, который вы указывали на этапе установки Navi-Back (например, navi-back-directions-car).
Создайте файл data.json с телом запроса к API навигации. Примеры запросов вы можете найти в документации сервисов навигации:
- Directions API: маршруты для автомобилей, такси, велосипедов, самокатов, мотоциклов, экстренных служб и пешеходов.
- Truck Directions API: маршруты для грузового транспорта.
- Routing API: маршруты для общественного транспорта.
- Isochrone API: достижимые области на автомобиле.
- Distance Matrix API: матрицы расстояний.
Проверку сервиса Distance Matrix Async API см. ниже.

Пример ниже содержит тело запроса к Directions API для построения автомобильного маршрута (приведён пример для Москвы):

data.json
```
{
    "alternative": 1,
    "locale": "en",
    "point_a_name": "start",
    "point_b_name": "finish",
    "type": "jam",
    "points": [
        {
            "start": true,
            "type": "walking",
            "x": 37.616489,
            "y": 55.751225
        },
        {
            "start": false,
            "type": "walking",
            "x": 37.418451,
            "y": 55.68355
        }
    ]
}
```
Отправьте запрос с использованием cURL или аналогичного инструмента (пример для Directions API):
```
curl -Lv 'http://127.0.0.1:7777/carrouting/6.0.0/global' -d @data.json
```
Вы должны получить ответ со следующей структурой (пример для Directions API):
```
{
  "query": {..},
  "result": [{..}, {..}]
  "type": "result"
}
```
Примеры ответов для других сервисов навигации вы можете найти в их документации.

Проверьте сервис Navi-Splitter

Чтобы проверить работу сервиса Navi-Splitter:

Создайте файл data.json с телом запроса к Distance Matrix API. Пример:

{
    "points": [
        {
            "lon": 37.5833,
            "lat": 55.7404
        },
        {
            "lon": 37.5803,
            "lat": 55.7696
        },
        {
            "lon": 37.6539,
            "lat": 55.7692
        },
        {
            "lon": 37.6546,
            "lat": 55.7415
        }
    ],
    "sources": [0, 1],
    "targets": [2, 3]
}

Отправьте запрос с использованием cURL или аналогичного инструмента:
```
curl -Lv 'http://127.0.0.1:7777/get_dist_matrix' -d @data.json
```
Вы должны получить ответ со следующей структурой:
```
{
    "generation_time": 1111,
    "routes":  [{..}, {..}]
}
```

Проверьте сервис Navi-Router

Чтобы проверить работу сервиса Navi-Router:

Сгенерируйте API-ключ в сервисе API-ключей. Подробнее см. в разделе Ключи и токены.
Пробросьте порт сервиса с помощью kubectl:
```
kubectl port-forward navi-router-6864944c7-vrpns 7777:8080
```
Создайте файл data.json с телом запроса к сервису навигации, идентичный файлу из раздела Проверка работоспособности Navi-Back.
Отправьте запрос с использованием cURL или аналогичного инструмента (пример для Directions API):
```
curl -Lv 'http://127.0.0.1:7777/carrouting/6.0.0/global?key=API_KEY' -d @data.json
```
Где API_KEY — API-ключ для доступа к сервисам навигации.

Вы должны получить ответ, содержащий имя правила, например:
```
directions-car
```

Проверьте сервис Navi-Front

Чтобы проверить работу сервиса Navi-Front:

Сгенерируйте API-ключ в сервисе API-ключей. Подробнее см. в разделе Ключи и токены.
Создайте файл data.json с телом запроса к сервису навигации, идентичный файлу из раздела Проверка работоспособности Navi-Back.
Отправьте запрос с использованием cURL или аналогичного инструмента (пример для Directions API):
```
curl -Lv 'http://navi-front.example.com/carrouting/6.0.0/global?key=API_KEY' -d @data.json
```
Где API_KEY — API-ключ для доступа к сервисам навигации.

Вы должны получить ответ со следующей структурой:
```
{
  "query": {..},
  "result": [{..}, {..}]
  "type": "result"
}
```

Проверьте сервис Distance Matrix Async API

Чтобы проверить работу сервиса Distance Matrix Async API:

Сгенерируйте API-ключ в сервисе API-ключей. Подробнее см. в разделе Ключи и токены.

Создайте файл data.json с телом запроса (приведён пример для Москвы):

{
    "points": [
        {
            "lon": 37.573289,
            "lat": 55.699926
        },
        {
            "lon": 37.614402,
            "lat": 55.706847
        },
        {
            "lon": 37.552182,
            "lat": 55.675928
        },
        {
            "lon": 37.620315,
            "lat": 55.669625
        }
    ],
    "sources": [0, 1],
    "targets": [2, 3]
}

Отправьте запрос с использованием cURL или аналогичного инструмента:
```
curl -Lv 'https://navi-async-matrix.example.com/create_task/get_dist_matrix?key=API_KEY' --header 'Content-Type: application/json' -d @data.json
```
Где API_KEY — API-ключ для доступа к сервисам навигации.

Вы должны получить ответ со следующей структурой:
```
{
    "task_id": "{TASK_ID}",
    "message": "success add task",
    "status ": "success"
}
```
Выполните запрос статуса задачи, подставив в URL параметр TASK_ID, полученный в ответе на предыдущем шаге:
```
curl -Lv 'https://navi-async-matrix.example.com/result/get_dist_matrix/{TASK_ID}'
```
При необходимости выполните запрос несколько раз, пока задача будет выполняться. Спустя какое-то время в ответ на очередной запрос вы должны получить ответ со следующей структурой:
```
{
    "task_id": "{TASK_ID}",
    "status": "TASK_DONE",
    "code": 200,
    "message": "1670066296399691644\ncalc_time_ms=485\nattract_time=21\nbuild_time=58\npoints_count=4\nsource_count=2\ntarget_count=2",
    "result_link": "http://artifacts.example.com/navi-async-matrix/{TASK_ID}.response.json"
}
```

Скачайте результат вычислений по URL, полученному в поле result_link на предыдущем шаге. Убедитесь, что результат представляет собой валидный JSON-файл. Пример:

{
    "generation_time": 94.0,
    "routes": [
    {
    "status": "OK",
    "source_id": 0,
    "target_id": 2,
    "distance": 7996,
    "duration": 728,
    "reliability": 1.0
    },
    ...
    ],
    "attract_time": 21.0,
    "build_matrix_time": 58.0
}

Проверьте сервис Restrictions API

Чтобы проверить работу сервиса Restrictions API:

Создайте файл data.json с телом запроса (приведён пример для Москвы):

{
    "start_time": "2022-07-03T20:30:00.000Z",
    "end_time": "2029-08-28T23:59:00.000Z",
    "lat": 55.75291,
    "lon": 37.6113,
    "is_whole_road": false
}

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

curl -Lv 'http://navi-restrictions:7777/points/' --header 'Content-Type: application/json' -d @data.json

Вы должны получить ответ со следующей структурой:

[
    {
        "edge_geometry": "LINESTRING(37.610827 55.752269, 37.610958 55.752424, 37.611215 55.752690, 37.611287 55.752790, 37.611356
        55.752894, 37.611798 55.753816)",
        "restriction_id": "{RESTRICTION_ID}",
        "start_time": "2022-07-05T14:13:35.936000+00:00",
        "end_time": "2029-08-28T23:59:00+00:00",
        "is_2gis": false
    }
]

Проверьте, что перекрытие появилось в системе:
```
curl -Lv 'http://navi-restrictions:7777/restrictions/'
```
Удалите перекрытие:
```
curl --request DELETE 'http://navi-restrictions:7777/restrictions/{RESTRICTION_ID}'
```
Где {RESTRICTION_ID} — значение поля restriction_id в ответе на запрос в шаге 2.

9. Установка Менеджера Платформы

9.1. Перед установкой

Ознакомьтесь с:
Убедитесь, что выполнены предварительные шаги:

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

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

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

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

Используйте подходящий чарт
Содержание Helm-чарта, описанное в данном разделе, актуально для последней версии API-платформы (см. Релизы API-платформы). Чтобы изучить параметры для предыдущих версий, откройте values.yaml в GitHub и в списке тегов слева выберите тег Platform-<версия>.
Определите доменное имя для сервиса Менеджер Платформы. Например, platform.example.com.

9.2. Установите Менеджер Платформы

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

Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-platform.yaml
dgctlDockerRegistry: docker.registry.example.com imagePullSecrets: [onpremise-registry-creds] ui: playgrounds: mapgl,geocoder,directions,static brand: 2gis pages: "profile,signup,status,playground,map_styles,users,keys,statistics,license" oauth: wellknownUrl: https://keycloak.example.com/realms/platform/.well-known/openid-configuration clientId: platform clientSecret: secret scope: '' codeUrl: https://platform.ingress.host/api/auth/code safeHosts: '.*' secure: true status: mapgl: "MapGL JS=http://mapgl-js-api,Tiles API=http://tiles-api/healthcheck" search: "Catalog API=http://catalog-api,Search API=http://search-api/v2/status" navi: "Castle=http://navi-castle/cities.conf,Back=http://navi-back-directions-car/about,Routing=http://navi-front/healthcheck" pro: "PRO UI=http://pro-ui:3000/api/healthcheck/app,PRO API=http://pro-api/health/live,PRO Permissions API=http://pro-api-permissions" keys: "Keys UI=http://keys-admin,Keys Service API=http://keys-service-api/healthcheck,Keys API=http://keys-api/healthcheck" mapStyles: "http://styles-api/healthcheck" platform: api: url: 'https://keys-api.example.com' license: url: 'http://license.example.com' mapgl: url: 'https://mapgl-js-api.example.com' scriptPath: /api.js key: 'MAPGL_KEY' initCenter: '' catalog: url: 'https://catalog.example.com' key: 'CATALOG_KEY' navi: url: 'https://navi.example.com' key: 'NAVI_KEY' static: url: 'https://static.example.com' key: 'STATIC_KEY' resources: requests: cpu: 300m memory: 384Mi limits: cpu: 1100m memory: 512Mi ingress: enabled: true className: nginx hosts: - host: platform.example.com paths: - path: / pathType: Prefix tls: [] # - hosts: # - platform.example.com # secretName: secret.tls
Где:
- dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в формате HOST:PORT.
- imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
- ui: базовые настройки приложения.
  - playgrounds: список доступных песочниц в приложении. Возможные значения: mapgl (дополнительно укажите параметр ui.mapgl.url), geocoder (дополнительно укажите параметр ui.catalog.url), directions (дополнительно укажите параметр ui.navi.url), static (дополнительно укажите параметр ui.static.url). Значения записываются одной строкой через запятую и без пробелов, например, 'mapgl,geocoder'.
  - brand: брендирование внутри приложения. Возможные значения: 2gis, urbi.
  - pages: список доступных страниц в приложении. Значения записываются одной строкой через запятую и без пробелов, например, 'status,playground'. Первое значение в списке — страница по умолчанию. Минимально необходимые значения: map_styles (если вы устанавливаете Styles API), status и playground. Полный список возможных значений см. здесь.
  - oauth: настройки интеграции с поставщиком OIDC. Требуется для аутентификации пользователей и работы со статистикой по API-ключам.
    - wellknownUrl: URL до конфигурации OIDC.
    - clientId: идентификатор клиента OIDC.
    - clientSecret: секрет клиента OIDC для обмена кода авторизации на токен.
    - scope: области видимости (scopes) OIDC.
    - codeUrl: URL для обмена кода авторизации на токен. Формируется на основе фактического хоста приложения: https://<host>/api/auth/code.
    - safeHosts: регулярное выражение для валидации хоста, на который выполняется перенаправление после обмена токена.
    - secure: используется ли HTTPS для токенов аутентификации.
  - status: перечень статусов для сервисов On-Premise.
    
    Значение — строка, содержащая пары из названия сервиса и URL до его healthcheck. Пары записываются через запятую. Значения внутри пары соединяются символом "=". Например, mapgl: 'MapGL JS=https://example.com/healthcheck'. URL должен быть абсолютным. Можно указать только URL, например, mapgl: 'https://example.com/healthcheck'.
    - mapgl: статус сервиса MapGL JS API.
    - search: статус сервисов Поиска.
    - navi: статус сервисов Навигации.
    - pro: статус сервисов 2ГИС Про.
    - keys: статус Сервиса ключей.
    - mapStyles: статус Styles API.
  - platform: настройки доступа к сервису API-ключей:
    - api.url: хост сервиса в формате HTTP(S)://HOST.
  - license: настройки доступа к сервису лицензий:
    - url: хост сервиса в формате HTTP://HOST.
  - mapgl: настройки доступа к сервису MapGL JS API:
    - url: хост сервиса в формате HTTP(S)://HOST.
    - scriptPath: путь до скрипта инициализации сервиса. Путь строится относительно ui.mapgl.url. Возможные значения: /api.js.
    - key: API-ключ для сервиса.
    - initCenter: координаты карты по умолчанию. Состоят из двух чисел в массиве: [lng, lat]. Например: [55.27, 25.2] для Дубая, [37.64, 55.74] для Москвы.
  - catalog: настройки доступа к сервису Catalog APIs:
    - url: хост сервиса в формате HTTP(S)://HOST.
    - key: API-ключ для сервиса.
  - navi: настройки доступа к сервису API навигации:
    - url: хост сервиса в формате HTTP(S)://HOST.
    - key: API-ключ для сервиса.
  - static: настройки доступа к сервису Static API:
    - url: хост сервиса в формате HTTP(S)://HOST.
    - key: API-ключ для сервиса.
  - resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
  - ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-platform.yaml:
```
helm upgrade --install --version=VERSION --atomic --values ./values-platform.yaml platform 2gis-on-premise/platform
```
В параметре --version укажите нужную версию API-платформы. Список версий см. в разделе Релизы API-платформы.

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

9.3. Проверьте работоспособность Менеджера Платформы

Чтобы проверить работу Менеджера Платформы, перейдите по адресу https://platform.example.com в браузере. Должен открыться веб-интерфейс.

В Менеджере Платформы вы можете проверить статус работы установленных сервисов, загрузить пользовательские стили и протестировать работу ключевых API: подробнее см. в инструкции Работа с Менеджером Платформы.

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

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

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

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

Определите обязательные утверждения (claims) о данных пользователя. Следующие данные гарантированно должны быть заполнены в ответе user-info:
- sub — идентификатор пользователя.
- email — email пользователя.
- email_verified — флаг, указывающий на то, был ли email подтверждён пользователем.
- name — полное имя пользователя.
- phone_number — номер телефона пользователя.
Настройте области видимости (scopes), по которым можно получать заданные утверждения (claims). Стандартно используются следующие scopes:
- openid — обязательный параметр, указывающий на использование OpenID Connect для аутентификации пользователя.
- email — email пользователя.
- profile — ссылка на профиль пользователя.
- phone — номер телефона пользователя.
Создайте клиента в вашем поставщике 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/post_sign_out.
3. Настройте работу клиента с заданными на предыдущем шаге scopes.

10. Установка мобильного SDK

Доступность версий

Для использования в закрытом контуре доступен мобильный SDK для iOS, Android и Flutter до версии 12.10 включительно.

10.1. Перед установкой

Ознакомьтесь с:
Обратитесь в службу поддержки On-Premise, чтобы получить необходимые данные:
- Файл ключа для использования SDK. При обращении в поддержку уточните:
  - Ключ должен быть настроен на использование в режиме On-Premise.
  - App ID ключа должен соответствовать applicationId/bundleId приложения, в котором подключается мобильный SDK.
  Также вы можете запросить включение Wildcard в ключе для использования каскадного App ID. Например, если в ключе включен Wildcard и установлено значение com.geo.app для App ID, то с этим ключом мобильный SDK можно использовать в приложениях с applicationId/bundleId типа com.geo.app.testing, com.geo.app.staging, com.geo.app.dev и другими.
- Конфигурационный файл vendor-config.jsonx с настроенными сервисами On-Premise.
  
  В этом файле помимо URL сервисов указан идентификатор ключа из Сервиса API-ключей в поле dgis/native-sdk/keys/user_web_api_key_for_on_premise. Этот идентификатор пользователь сервиса может задавать самостоятельно на основе ключей из Сервиса API-ключей.

10.2. Установите мобильный SDK

Установите мобильный SDK, следуя инструкциям:
- для Android-платформы,
- для iOS-платформы.
При инициализации SDK в своём приложении подключите vendor-config.jsonx, следуя инструкциям:
- для Android-платформы,
- для iOS-платформы.

1. Подготовка к установке
2. Установка сервиса лицензий
3. Установка сервиса API-ключей
4. Установка сервиса сбора статистики
5. Установка прокси для API пробок
6. Установка API карт
7. Установка API поиска
8. Установка API навигации
9. Установка Менеджера Платформы
10. Установка мобильного SDK
- 10.1. Перед установкой
- 10.2. Установите мобильный SDK

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

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

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

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

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

docker.registry.example.com​

artifacts.example.com​

example.com​

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

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

2. Установка сервиса лицензий​

2.1. Перед установкой​

2.2. Установите сервис лицензий​

2.3. Получите лицензию​

2.4. Проверьте статус лицензии​

3. Установка сервиса API-ключей​

3.1. Перед установкой​

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

Настройте PostgreSQL​

Настройте LDAP​

Настройте Apache Kafka​

Настройте Redis​

3.3. Установите сервис API-ключей​

3.4. Получите сервисные токены​

3.5. Проверьте работоспособность сервиса API-ключей​

3.6. Создайте API-ключ​

4. Установка сервиса сбора статистики​

4.1. Перед установкой​

4.2. Установите сервис сбора статистики​

Установите сервис Stat Receiver​

Установите сервис Stat API (опционально)​

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

5. Установка прокси для API пробок​

5.1. Перед установкой​

5.2. Установите прокси для API пробок​

Для использования сервисами навигации​

Для использования сервисами карт​

5.3. Проверьте работоспособность прокси для API пробок​

Для использования сервисами навигации​

1. Проверьте работу прокси для API пробок​

2. Проверьте получение данных пробок сервисом навигации​

Для использования сервисами карт​

1. Проверьте работу прокси для API пробок​

2. Проверьте получение данных пробок сервисом MapGL JS API​

6. Установка API карт​

6.1. Перед установкой​

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

Для установки Tiles API​

Для установки Styles API​

6.3. Установите сервисы карт​

Установите сервис Tiles API​

Установите сервис MapGL JS API​

Установите сервис Static API (опционально)​

Установите сервис Styles API (опционально)​

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

Проверьте сервис Tiles API​

Проверьте сервис MapGL JS API​

Проверьте сервис Static API​

Проверьте сервис Styles API​

7. Установка API поиска​

7.1. Перед установкой​

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

Настройте PostgreSQL​

Создайте API-ключ​

7.3. Установите сервисы поиска​

Установите сервис Search API​

Установите сервис Catalog APIs​

7.4. Проверьте работоспособность сервисов поиска​

8. Установка API навигации​

8.1. Перед установкой​

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

Для установки Distance Matrix Async API​

Для установки TSP API​

Для установки Restrictions API​

8.3. Создайте файл правил​

Структура правила​

Пример файла правил​

8.4. Установите сервисы навигации​

Установите сервис Navi-Castle​

Установите сервис Navi-Attractor​

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

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

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

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

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

docker.registry.example.com

artifacts.example.com

example.com

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

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

2. Установка сервиса лицензий

2.1. Перед установкой

2.2. Установите сервис лицензий

2.3. Получите лицензию

2.4. Проверьте статус лицензии

3. Установка сервиса API-ключей

3.1. Перед установкой

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

Настройте PostgreSQL

Настройте LDAP

Настройте Apache Kafka

Настройте Redis

3.3. Установите сервис API-ключей

3.4. Получите сервисные токены

3.5. Проверьте работоспособность сервиса API-ключей

3.6. Создайте API-ключ

4. Установка сервиса сбора статистики

4.1. Перед установкой

4.2. Установите сервис сбора статистики

Установите сервис Stat Receiver

Установите сервис Stat API (опционально)

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

5. Установка прокси для API пробок

5.1. Перед установкой

5.2. Установите прокси для API пробок

Для использования сервисами навигации

Для использования сервисами карт

5.3. Проверьте работоспособность прокси для API пробок

Для использования сервисами навигации

1. Проверьте работу прокси для API пробок

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

Для использования сервисами карт

1. Проверьте работу прокси для API пробок

2. Проверьте получение данных пробок сервисом MapGL JS API

6. Установка API карт

6.1. Перед установкой

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

Для установки Tiles API

Для установки Styles API

6.3. Установите сервисы карт

Установите сервис Tiles API

Установите сервис MapGL JS API

Установите сервис Static API (опционально)

Установите сервис Styles API (опционально)

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

Проверьте сервис Tiles API

Проверьте сервис MapGL JS API

Проверьте сервис Static API

Проверьте сервис Styles API

7. Установка API поиска

7.1. Перед установкой

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

Настройте PostgreSQL

Создайте API-ключ

7.3. Установите сервисы поиска

Установите сервис Search API

Установите сервис Catalog APIs

7.4. Проверьте работоспособность сервисов поиска

8. Установка API навигации

8.1. Перед установкой

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

Для установки Distance Matrix Async API

Для установки TSP API

Для установки Restrictions API

8.3. Создайте файл правил

Структура правила

Пример файла правил

8.4. Установите сервисы навигации

Установите сервис Navi-Castle

Установите сервис Navi-Attractor