Навигация | On-Premise | 2GIS Documentation
On-Premise
Карты
Поиск
Навигация
UGC
On-Premise
ру
en

Навигация

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

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

Архитектура

Архитектура сервисов навигации (On-Premise)

Сервисы навигации включают в себя:

  • Navi-Castle - импортирует данные из S3-хранилища и предоставляет их сервису Navi-Back в требуемом формате.
  • Navi-Front - получает входящие запросы от приложений и направляет их к Navi-Router и Navi-Back.
  • Navi-Router - проверяет с помощью сервиса ключей, можно ли выполнить запрос. Затем с помощью системы регионов и правил выполняет маршрутизацию: определяет подходящий сервис Navi-Back, который будет обрабатывать этот запрос.
  • Navi-Back - обрабатывает запрос.

Также используется прокси для пробок для получения данных о пробках в реальном времени с серверов 2GIS. Navi-Back использует эту информацию для построения маршрутов с учётом трафика.

Сервисы навигации используют масштабируемую архитектуру, что позволяет с легкостью распределять обработку входящих запросов между несколькими инстансами Navi-Back:

  1. Navi-Front автоматически обнаруживает развернутые инстансы Navi-Router и Navi-Back, проверяя наличие особых меток (labels) для сервисов, развернутых в том же пространстве имен (namespace) Kubernetes, что и сам Navi-Front.

  2. Может существовать несколько инстансов Navi-Back, каждый из которых обрабатывает свою часть запросов. Соответственно, каждый инстанс запрашивает у Navi-Castle не все доступные данные, а только часть данных, необходимую для работы конкретного инстанса.

    Каждый инстанс Navi-Back имеет назначенное для него «правило»: группу из одного или нескольких регионов карты, в рамках которой будет происходить обработка запросов. Правила настраиваются с помощью файла правил. Таким образом, появляется возможность распределять нагрузку и планировать вычислительные ресурсы инстансов Navi-Back в соответствии с этим файлом. Например, один инстанс Navi-Back с малой производительностью может обрабатывать умеренное количество запросов для некоторого небольшого региона, а другой более производительный инстанс может обрабатывать большое количество запросов для большего по размерам региона.

  3. Когда Navi-Front получает входящий запрос:

    1. Он передает этот запрос сервису Navi-Router.

    2. Navi-Router использует тот же файл правил, что и Navi-Back, и получает все данные от Navi-Castle. Пользуясь этим файлом и имеющимися данными, Navi-Router выполняет маршрутизацию: находит правило, под которое попадает запрос. Другими словами, Navi-Router определяет, существует ли инстанс Navi-Back, который может обработать этот запрос.

      Если запрос успешно проходит проверку в сервисе ключей и существует подходящее для его обработки правило, то Navi-Router отправляет название этого правила Navi-Front.

    3. Navi-Front находит подходящий инстанс Navi-Back, который настроен на работу с правилом, название которого вернул Navi-Router, и передает запрос этому инстансу.

    4. Инстанс Navi-Back обрабатывает запрос и возвращает ответ Navi-Front.

    5. Navi-Front отсылает ответ инициатору запроса.

Сервисы навигации могут быть развернуты в двух разных конфигурациях:

  1. Все четыре сервиса. Это рекомендуемый метод развертывания, обеспечивающий безопасность, масштабируемость и надежность.

  2. Только сервисы 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": [
        <массив типов маршрутизации, которые разрешено обрабатывать для запросов на построение маршрута>
    ]
  }
]

Установка

Выполните следующие шаги:

  1. Выполните общие шаги по развертыванию.

    Примечание:

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

  2. Разверните прокси для пробок, если он еще не развёрнут (см. раздел Требования).

  3. Разверните сервис Navi-Castle.

  4. Разверните сервис Navi-Back.

  5. Разверните сервис Navi-Router.

  6. Разверните сервис Navi-Front.

Navi-Castle

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

    Где:

    1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.

    2. dgctlStorage: настройки хранилища артефактов развертывания.

      1. Укажите общие настройки для доступа к хранилищу: эндпоинт, имя бакета, реквизиты для доступа.
      2. manifest: укажите путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы.

    3. resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

    4. persistentVolume: настройки для Kubernetes Persistent Volume Claim (PVC), который используется для хранения данных сервиса.

      1. enabled: флаг, определяющий, включен ли PVC (по умолчанию: false). Если PVC выключен, то реплика сервиса может потерять свои данные.
      2. accessModes: режим доступа к PVC (по умолчанию не задан). Доступные режимы такие же, как и для persistent volumes.
      3. storageClass: класс хранилища для PVC.
      4. size: размер хранилища.

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

      Navi-Castle развертывается с использованием StatefulSet. Это означает, что каждая реплика Navi-Castle получит своё выделенное хранилище Persistent Storage с указанными настройками.

      Например, если вы задали настройку size со значением 5Gi, то общий объем хранилища для трёх реплик будет равен 15Gi.

    5. castle.castle_data_path: путь до директории с данными Navi-Castle.

    6. cron: настройки cron-заданий (Kubernetes Cron Job). Эти настройки одинаковы для все реплик сервиса Navi-Castle. Такое cron-задание получает актуальные данные из хранилища артефактов развертывания и затем обновляет данные на реплике Navi-Castle.

      1. enabled: флаг, определяющий, включено ли задание (по умолчанию: false). Если задание выключено, то ни одна из реплик Navi-Castle не будет получать обновления данных.
      2. schedule: расписание выполнения задания в cron-формате. Например, */10 * * * *.
      3. concurrencyPolicy: политика одновременного выполнения (concurrency policy) для задания.
      4. successfulJobsHistoryLimit: ограничение на размер истории выполненных заданий.

    7. replicaCount: число реплик сервиса Navi-Castle. Обратите внимание, что под каждой реплики получит своё выделенное cron-задание для получения актуальных данных из хранилища артефактов развертывания.

  2. Разверните сервис с помощью 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

  1. Создайте файл правил rules.conf с требуемым набором правил.

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

    Где:

    1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.

    2. affinity: настройки node affinity.

    3. autoscaling: настройки автомасштабирования (autoscaling).

    4. naviback: настройки сервиса Navi-Back.

      1. app_castle_host: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      2. eca_host: доменное имя прокси для пробок. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      3. forecast_host: URL сервиса прогноза пробок. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      4. rules_filename: имя файла правил. Используйте имя файла, который вы создали на предыдущем шаге.
      5. app_rule: имя правила из файла правил, которое нужно применять.
      6. type: тип маршрутизации, который разрешено обрабатывать этому Navi-Back: taxi или carrouting.

    5. replicaCount: число реплик сервиса Navi-Back.

    6. resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

  3. Разверните сервис с помощью 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

  1. Создайте файл правил rules.conf с требуемым набором правил.

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

    Где:

    1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.

    2. app_castle_host: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.

    3. key_management_service: настройки сервиса ключей. Если не задавать эти настройки, то проверка API-ключа для запроса будет пропущена.

      1. service_remote_address: URL API-эндпоинта сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      2. service_apis: ключи для отдельных API, заданные через веб-интерфейс администратора сервиса ключей.

    4. replicaCount: число реплик сервиса Navi-Router.

    5. resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

  3. Разверните сервис с помощью 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

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

    Где:

    1. dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов On-Premise.
    2. affinity: настройки node affinity.
    3. autoscaling: настройки автомасштабирования (autoscaling).
    4. replicaCount: число реплик сервиса Navi-Front.
    5. resources: настройки вычислительных ресурсов для сервиса. Для получения актуальной информации о рекомендуемых значениях настроек в этой секции см. таблицу с минимальными системными требованиями.

  2. Разверните сервис с помощью 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:

  1. Пробросьте порт сервиса с помощью kubectl:

    kubectl port-forward navi-castle-0 7777:8080

  2. Отправьте 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:

  1. Пробросьте порт сервиса с помощью kubectl:

    kubectl port-forward navi-back-6864944c7-vrpns 7777:8080

  2. Создайте следующий файл с телом запроса:

    data.json

    {
    "locale": "en",
    "points": [
        {
            "type": "walking",
            "x": 50.061144,
            "y": 26.409866
        },
        {
            "type": "walking",
            "x": 50.044684,
            "y": 26.377784
        }
    ],
    "type": "jam"
}

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

    curl -Lv http://NAVI_BACK_HOST:7777/carrouting/6.0.0/global -d @data.json

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

    {
  "query": {..},
  "result": [{..}, {..}]
  "type": "result"
}

    См. документацию сервисов навигации для получения примеров запросов и ответов.

Navi-Router

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

  1. Пробросьте порт сервиса с помощью kubectl:

    kubectl port-forward navi-router-6864944c7-vrpns 7777:8080

  2. Создайте следующий файл с телом запроса:

    data.json

    {
    "locale": "en",
    "points": [
        {
            "type": "walking",
            "x": 50.061144,
            "y": 26.409866
        },
        {
            "type": "walking",
            "x": 50.044684,
            "y": 26.377784
        }
    ],
    "type": "jam"
}

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

    curl -Lv http://NAVI_ROUTER_HOST:7777/carrouting/6.0.0/global -d @data.json

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

    dammam_cr

Navi-Front

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

  1. Пробросьте порт сервиса с помощью kubectl:

    kubectl port-forward navi-front-6864944c7-vrpns 7777:8080

  2. Создайте следующий файл с телом запроса:

    data.json

    {
    "locale": "en",
    "points": [
        {
            "type": "walking",
            "x": 50.061144,
            "y": 26.409866
        },
        {
            "type": "walking",
            "x": 50.044684,
            "y": 26.377784
        }
    ],
    "type": "online5"
}

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

    curl -Lv http://NAVI_FRONT_HOST:7777/carrouting/6.0.0/global -d @data.json

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

    {
  "query": {..},
  "result": [{..}, {..}]
  "type": "result"
}