Навигация | On-Premise | 2GIS Documentation
On-Premise

Навигация

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

В этой статье описывается, как развернуть и настроить сервисы навигации в вашем окружении. Чтобы узнать, как использовать 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.

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

Общая инфраструктура:

  • Поддержка Kubernetes Persistent Volume и динамических Persistent Volume Claim для хранения данных (необязательно).

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

    Настоятельно рекомендуется настроить функциональность Persistent Volume и Persistent Volume Claim в вашем кластере Kubernetes.

    Без этой функциональности Navi-Castle будет хранить необходимые для работы сервисов навигации данные в разделе emptyDir. Это означает, что если под (pod) Navi-Castle будет убран с узла (node) кластера Kubernetes, на котором он выполняется, то эти данные будут потеряны.

Сервисы:

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

Сервисы:

  • Navi-Castle

Сервисы:

  • 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.

  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-заданием по расписанию.

  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
    
  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
    
  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, выполните следующую команду:

helm upgrade --version=1.0.3 --atomic --values ./values-castle.yaml navi-castle 2gis-on-premise/navi-castle

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

helm upgrade --version=1.0.3 --atomic --values ./values-back.yaml navi-back 2gis-on-premise/navi-back

Чтобы обновить сервис Navi-Router, выполните следующую команду:

helm upgrade --version=1.0.3 --atomic --values ./values-router.yaml navi-router 2gis-on-premise/navi-router

Чтобы обновить сервис Navi-Front, выполните следующую команду:

helm upgrade --version=1.0.3 --atomic --values ./values-front.yaml navi-front 2gis-on-premise/navi-front

Чтобы проверить работоспособность сервиса 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:

  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:

  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:

  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"
    }