Навигация
Сервисы навигации позволяют строить маршруты, а также получать информацию о расстоянии и времени в пути между точками на карте. Все это может делаться с учётом или без учёта текущей ситуации с пробками на дорогах.
В этой статье описывается, как развернуть и настроить сервисы навигации в вашем окружении. Чтобы узнать, как использовать RESTful API, предоставляемые сервисами навигации, обратитесь к документации соответствующих API (можно найти в основном меню сверху на вкладке «Навигация»).
Архитектура

Сервисы навигации включают в себя:
Navi-Castle
- импортирует данные из S3-хранилища и предоставляет их сервису Navi-Back в требуемом формате.Navi-Front
- получает входящие запросы от приложений и направляет их к Navi-Router и Navi-Back.Navi-Router
- проверяет с помощью сервиса ключей, можно ли выполнить запрос. Затем с помощью системы регионов и правил выполняет маршрутизацию: определяет подходящий сервис Navi-Back, который будет обрабатывать этот запрос.Navi-Back
- обрабатывает запрос.
Также используется прокси для пробок для получения данных о пробках в реальном времени с серверов 2GIS. Navi-Back использует эту информацию для построения маршрутов с учётом трафика.
Сервисы навигации используют масштабируемую архитектуру, что позволяет с легкостью распределять обработку входящих запросов между несколькими инстансами Navi-Back:
-
Navi-Front автоматически обнаруживает развернутые инстансы Navi-Router и Navi-Back, проверяя наличие особых меток (labels) для сервисов, развернутых в том же пространстве имен (namespace) Kubernetes, что и сам Navi-Front.
-
Может существовать несколько инстансов Navi-Back, каждый из которых обрабатывает свою часть запросов. Соответственно, каждый инстанс запрашивает у Navi-Castle не все доступные данные, а только часть данных, необходимую для работы конкретного инстанса.
Каждый инстанс Navi-Back имеет назначенное для него «правило»: группу из одного или нескольких регионов карты, в рамках которой будет происходить обработка запросов. Правила настраиваются с помощью файла правил. Таким образом, появляется возможность распределять нагрузку и планировать вычислительные ресурсы инстансов Navi-Back в соответствии с этим файлом. Например, один инстанс Navi-Back с малой производительностью может обрабатывать умеренное количество запросов для некоторого небольшого региона, а другой более производительный инстанс может обрабатывать большое количество запросов для большего по размерам региона.
-
Когда Navi-Front получает входящий запрос:
-
Он передает этот запрос сервису Navi-Router.
-
Navi-Router использует тот же файл правил, что и Navi-Back, и получает все данные от Navi-Castle. Пользуясь этим файлом и имеющимися данными, Navi-Router выполняет маршрутизацию: находит правило, под которое попадает запрос. Другими словами, Navi-Router определяет, существует ли инстанс Navi-Back, который может обработать этот запрос.
Если запрос успешно проходит проверку в сервисе ключей и существует подходящее для его обработки правило, то Navi-Router отправляет название этого правила Navi-Front.
-
Navi-Front находит подходящий инстанс Navi-Back, который настроен на работу с правилом, название которого вернул Navi-Router, и передает запрос этому инстансу.
-
Инстанс Navi-Back обрабатывает запрос и возвращает ответ Navi-Front.
-
Navi-Front отсылает ответ инициатору запроса.
-
Сервисы навигации могут быть развернуты в двух разных конфигурациях:
-
Все четыре сервиса. Это рекомендуемый метод развертывания, обеспечивающий безопасность, масштабируемость и надежность.
-
Только сервисы Navi-Castle и Navi-Back. В этом случае все входящие запросы обрабатываются непосредственно Navi-Back. Этапы проверки и маршрутизации запроса пропускаются. Рекомендуется использовать такую конфигурацию только в целях тестирования.
Примечание:
Без Navi-Router Navi-Back способен обрабатывать только те запросы, которые попадают под единственное правило, на работу с которым настроен Navi-Back. При распределенных развертываниях для работы сервисов навигации необходимы сервисы Navi-Front и Navi-Router.
Требования
Детальные требования для каждого сервиса описаны в обзорном документе. Дополнительную информацию можно найти в разделе Что нужно учесть перед развертыванием этого документа.
Navi-Castle
Общая инфраструктура:
-
Поддержка Kubernetes Persistent Volume и динамических Persistent Volume Claim для хранения данных (необязательно).
Важное примечание:
Настоятельно рекомендуется настроить функциональность Persistent Volume и Persistent Volume Claim в вашем кластере Kubernetes.
Без этой функциональности Navi-Castle будет хранить необходимые для работы сервисов навигации данные в разделе emptyDir. Это означает, что если под (pod) Navi-Castle будет убран с узла (node) кластера Kubernetes, на котором он выполняется, то эти данные будут потеряны.
Navi-Back
Сервисы:
- Прокси для пробок, настроенный на использование серверов обновлений, предоставляющих данные о пробках в формате, который подходит для использования сервисами навигации.
- Navi-Castle
Navi-Router
Сервисы:
- Navi-Castle
Navi-Front
Сервисы:
- Navi-Castle
- Navi-Router
- Navi-Back
Файл правил
Navi-Back использует файл правил, чтобы указать, какие типы запросов он может обрабатывать. Это позволяет инстансу Navi-Back запрашивать и хранить минимальный набор данных от Navi-Castle, достаточный для обработки указанных типов запросов.
Файл также используется Navi-Router для определения того, какой из нескольких инстансов Navi-Back может обработать запрос.
Файл правил имеет следующую структуру:
[
{
"name": "<имя правила>",
"router_projects": [
"<имя проекта для Navi-Router>"
],
"moses_projects": [
"<имя проекта для Navi-Back>"
],
"projects": [
"<имя региона>"
],
"queries": [
<массив типов запросов, которые разрешено обрабатывать>
],
"routing": [
<массив типов маршрутизации, которые разрешено обрабатывать для запросов на построение маршрута>
]
}
]
Установка
Выполните следующие шаги:
-
Выполните общие шаги по развертыванию.
Примечание:
Не забудьте записать путь к файлу с манифестом, эта информация необходима для развертывания сервисов.
-
Разверните прокси для пробок, если он еще не развёрнут (см. раздел Требования).
Navi-Castle
-
Создайте конфигурационный файл
values-castle.yaml
:values-castle.yaml
dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise dgctlStorage: host: <Deployment Artifacts Storage endpoint> bucket: <Deployment Artifacts Storage bucket> accessKey: <The bucket access key> secretKey: <The bucket secret key> manifest: <Path to the manifest file> resources: limits: cpu: 1000m memory: 512Mi requests: cpu: 500m memory: 128Mi persistentVolume: enabled: false accessModes: <volume access mode> storageClass: <volume storage class> size: <volume size> castle: castle_data_path: '/opt/castle/data/' cron: enabled: <true or false> schedule: <schedule string> concurrencyPolicy: <concurrency policy> successfulJobsHistoryLimit: <history depth> replicaCount: <number of the Castle service replicas>
Где:
-
dgctlDockerRegistry
: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise. -
dgctlStorage
: настройки хранилища артефактов развертывания.- Укажите общие настройки для доступа к хранилищу: эндпоинт, имя бакета, реквизиты для доступа.
manifest
: укажите путь до файла с манифестом в форматеmanifests/1640661259.json
. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы.
-
resources
: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями. -
persistentVolume
: настройки для Kubernetes Persistent Volume Claim (PVC), который используется для хранения данных сервиса.enabled
: флаг, определяющий, включен ли PVC (по умолчанию:false
). Если PVC выключен, то реплика сервиса может потерять свои данные.accessModes
: режим доступа к PVC (по умолчанию не задан). Доступные режимы такие же, как и для persistent volumes.storageClass
: класс хранилища для PVC.size
: размер хранилища.
Важное примечание:
Navi-Castle развертывается с использованием StatefulSet. Это означает, что каждая реплика Navi-Castle получит своё выделенное хранилище Persistent Storage с указанными настройками.
Например, если вы задали настройку
size
со значением5Gi
, то общий объем хранилища для трёх реплик будет равен15Gi
. -
castle.castle_data_path
: путь до директории с данными Navi-Castle. -
cron
: настройки cron-заданий (Kubernetes Cron Job). Эти настройки одинаковы для все реплик сервиса Navi-Castle. Такое cron-задание получает актуальные данные из хранилища артефактов развертывания и затем обновляет данные на реплике Navi-Castle.enabled
: флаг, определяющий, включено ли задание (по умолчанию:false
). Если задание выключено, то ни одна из реплик Navi-Castle не будет получать обновления данных.schedule
: расписание выполнения задания в cron-формате. Например,*/10 * * * *
.concurrencyPolicy
: политика одновременного выполнения (concurrency policy) для задания.successfulJobsHistoryLimit
: ограничение на размер истории выполненных заданий.
-
replicaCount
: число реплик сервиса Navi-Castle. Обратите внимание, что под каждой реплики получит своё выделенное cron-задание для получения актуальных данных из хранилища артефактов развертывания.
-
-
Разверните сервис с помощью Helm, используя подготовленный конфигурационный файл
values-castle.yaml
:helm upgrade --install --version=1.0.3 --atomic --values ./values-castle.yaml navi-castle 2gis-on-premise/navi-castle
При первом запуске реплика Navi-Castle получит данные из хранилища артефактов развертывания. В дальнейшем, эти данные будут обновляться cron-заданием по расписанию.
Navi-Back
-
Создайте файл правил rules.conf с требуемым набором правил.
-
Создайте конфигурационный файл
values-back.yaml
:values-back.yaml
dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise affinity: <affinity rules> autoscaling: enabled: <true or false> maxReplicas: <max replicas number> minReplicas: <min replicas number> scaleDownWindowsSeconds: <scale-down window> scaleUpWindowSeconds: <scale-up window> targetCPUUtilizationPercentage: <target CPU utilization> naviback: app_castle_host: <URL of Navi-Castle service> eca_host: <Domain name of the Traffic Proxy service> forecast_host: <URL of Traffic Jam forecast service> rules_filename: <rules file name> app_rule: <rule name from the rules file to apply> type: <routing type: taxi or carrouting> replicaCount: <number of the Navi-Back service replicas> resources: limits: cpu: 2000m memory: 16000Mi requests: cpu: 1000m memory: 1024Mi
Где:
-
dgctlDockerRegistry
: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise. -
affinity
: настройки node affinity. -
autoscaling
: настройки автомасштабирования (autoscaling). -
naviback
: настройки сервиса Navi-Back.app_castle_host
: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.eca_host
: доменное имя прокси для пробок. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.forecast_host
: URL сервиса прогноза пробок. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.rules_filename
: имя файла правил. Используйте имя файла, который вы создали на предыдущем шаге.app_rule
: имя правила из файла правил, которое нужно применять.type
: тип маршрутизации, который разрешено обрабатывать этому Navi-Back:taxi
илиcarrouting
.
-
replicaCount
: число реплик сервиса Navi-Back. -
resources
: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
-
-
Разверните сервис с помощью Helm, используя подготовленный конфигурационный файл
values-back.yaml
:helm upgrade --install --version=1.0.3 --atomic --values ./values-back.yaml navi-back 2gis-on-premise/navi-back
Navi-Router
-
Создайте файл правил rules.conf с требуемым набором правил.
-
Создайте конфигурационный файл
values-router.yaml
:values-router.yaml
dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise router: app_castle_host: http://navi-castle.host additional_sections: |- "key_management_service" : { "service_remote_address" : "http://keys-api.host", "service_apis" : [ {"type" : "directions", "token" : "DIRECTIONS_API_KEY"}, {"type" : "distance-matrix", "token" : "DISTANCE_MATRIX_API_KEY"}, {"type" : "pairs-directions", "token" : "PAIRS_DIRECTIONS_API_KEY"}, {"type" : "truck-directions", "token" : "TRUCK_DIRECTIONS_API_KEY"}, {"type" : "public-transport", "token" : "PUBLIC_TRANSPORT_API_KEY"}, {"type" : "isochrone", "token" : "ISOCHRONE_API_KEY"}, {"type" : "map-matching", "token" : "MAP_MATCHING_API_KEY"} ] } replicaCount: 2 resources: limits: cpu: '2000m' memory: '1024Mi' requests: cpu: '500m' memory": '128Mi'
Где:
-
dgctlDockerRegistry
: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise. -
app_castle_host
: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes. -
key_management_service
: настройки сервиса ключей. Если не задавать эти настройки, то проверка API-ключа для запроса будет пропущена.service_remote_address
: URL API-эндпоинта сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.service_apis
: ключи для отдельных API, заданные через веб-интерфейс администратора сервиса ключей.
-
replicaCount
: число реплик сервиса Navi-Router. -
resources
: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
-
-
Разверните сервис с помощью Helm, используя подготовленный конфигурационный файл
values-router.yaml
:helm upgrade --install --version=1.0.3 --atomic --values ./values-router.yaml navi-router 2gis-on-premise/navi-router
Navi-Front
-
Создайте конфигурационный файл
values-front.yaml
:values-front.yaml
dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise affinity: <affinity rules> autoscaling: enabled: 'true' maxReplicas: 6 minReplicas: 2 scaleDownWindowsSeconds: 600 scaleUpWindowSeconds: 300 targetCPUUtilizationPercentage: 90 replicaCount: 2 resources: limits: cpu: 100m memory: 128Mi requests: cpu: 100m memory: 128Mi
Где:
dgctlDockerRegistry
: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.affinity
: настройки node affinity.autoscaling
: настройки автомасштабирования (autoscaling).replicaCount
: число реплик сервиса Navi-Front.resources
: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.
-
Разверните сервис с помощью Helm, используя подготовленный конфигурационный файл
values-front.yaml
:helm upgrade --install --version=1.0.3 --atomic --values ./values-front.yaml navi-front 2gis-on-premise/navi-front
Обновление
Navi-Castle
Чтобы обновить сервис Navi-Castle, выполните следующую команду:
helm upgrade --version=1.0.3 --atomic --values ./values-castle.yaml navi-castle 2gis-on-premise/navi-castle
Navi-Back
Чтобы обновить сервис Navi-Back, выполните следующую команду:
helm upgrade --version=1.0.3 --atomic --values ./values-back.yaml navi-back 2gis-on-premise/navi-back
Navi-Router
Чтобы обновить сервис Navi-Router, выполните следующую команду:
helm upgrade --version=1.0.3 --atomic --values ./values-router.yaml navi-router 2gis-on-premise/navi-router
Navi-Front
Чтобы обновить сервис Navi-Front, выполните следующую команду:
helm upgrade --version=1.0.3 --atomic --values ./values-front.yaml navi-front 2gis-on-premise/navi-front
Проверка работоспособности
Navi-Castle
Чтобы проверить работоспособность сервиса Navi-Castle:
-
Пробросьте порт сервиса с помощью
kubectl
:kubectl port-forward navi-castle-0 7777:8080
-
Отправьте GET-запрос на корневой эндпоинт (
/
) с использованием cURL или аналогичного инструмента:curl -Lv http://NAVI_CASTLE_HOST: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 navi-back-6864944c7-vrpns 7777:8080
-
Создайте следующий файл с телом запроса:
data.json
{ "locale": "en", "points": [ { "type": "walking", "x": 50.061144, "y": 26.409866 }, { "type": "walking", "x": 50.044684, "y": 26.377784 } ], "type": "jam" }
-
Отправьте запрос с использованием cURL или аналогичного инструмента:
curl -Lv http://NAVI_BACK_HOST:7777/carrouting/6.0.0/global -d @data.json
Вы должны получить ответ со следующей структурой:
{ "query": {..}, "result": [{..}, {..}] "type": "result" }
См. документацию сервисов навигации для получения примеров запросов и ответов.
Navi-Router
Чтобы проверить работоспособность сервиса Navi-Router:
-
Пробросьте порт сервиса с помощью
kubectl
:kubectl port-forward navi-router-6864944c7-vrpns 7777:8080
-
Создайте следующий файл с телом запроса:
data.json
{ "locale": "en", "points": [ { "type": "walking", "x": 50.061144, "y": 26.409866 }, { "type": "walking", "x": 50.044684, "y": 26.377784 } ], "type": "jam" }
-
Отправьте запрос с использованием cURL или аналогичного инструмента:
curl -Lv http://NAVI_ROUTER_HOST:7777/carrouting/6.0.0/global -d @data.json
Вы должны получить ответ, содержащий имя правила:
dammam_cr
Navi-Front
Чтобы проверить работоспособность сервиса Navi-Front:
-
Пробросьте порт сервиса с помощью
kubectl
:kubectl port-forward navi-front-6864944c7-vrpns 7777:8080
-
Создайте следующий файл с телом запроса:
data.json
{ "locale": "en", "points": [ { "type": "walking", "x": 50.061144, "y": 26.409866 }, { "type": "walking", "x": 50.044684, "y": 26.377784 } ], "type": "online5" }
-
Отправьте запрос с использованием cURL или аналогичного инструмента:
curl -Lv http://NAVI_FRONT_HOST:7777/carrouting/6.0.0/global -d @data.json
Вы должны получить ответ со следующей структурой:
{ "query": {..}, "result": [{..}, {..}] "type": "result" }