Перейти к основному содержимому

Установка API для работы с навигацией

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

Все пароли и ключи в этом разделе приведены в иллюстративных целях.

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

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

  1. По возможности познакомьтесь с:

  2. Убедитесь, что выполнены необходимые предварительные шаги:

    1. Подготовка к установке
    2. Установка сервиса лицензий
    3. Установка сервиса API-ключей
    4. Установка сервиса сбора статистики
    5. (Опционально) Установка прокси для API пробок

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

    ОбъектПример значенияКак получить значение
    Endpoint зеркала реестра Dockerdocker.storage.example.local:5000См. Получение артефактов установки
    Секрет Kubernetes для доступа к зеркалу реестра Dockeronpremise-registry-credsСм. Получение артефактов установки
    Домен S3-хранилища с артефактами установкиartifacts.example.comСм. Получение артефактов установки
    Название бакета с артефактами установкиonpremise-artifactsСм. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установкиAKIAIOSFODNN7EXAMPLEСм. Получение артефактов установки
    Секрет ключа для доступа к артефактам установкиwJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEYСм. Получение артефактов установки
    Путь к файлу манифестаmanifests/api-platform/1640661259.jsonСм. Получение артефактов установки
    Endpoint сервиса лицензийhttps://licenseСм. Установка сервиса лицензий
    API-endpoint сервиса ключейhttp://keys-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-ключей

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

  4. Определите, какие API вам необходимо установить:

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

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

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

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

    Примечание

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

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

    Пример:

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

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

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

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

  1. 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;

  2. S3-совместимое хранилище.

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

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

      Пример:

      • Access key: TRVR4ESNMDDSIXLB3ISV
      • Secret key: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK

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

      Пример: navi-async-matrix-bucket

      Примечание

      По умолчанию Distance Matrix Async API удаляет все файлы старше 14 дней в бакете.

  3. Брокер сообщений Apache Kafka.

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

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

      Пример:

      • Имя пользователя: kafka-async-matrix
      • Пароль: 1Y2u3gGvi6VjNHUt

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

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

  1. Получите ключ доступа для работы с TSP API с помощью сервиса API-ключей. См. инструкцию Управление доступом к API.

  2. Настройте 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;

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

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

    Пример: navi-vrp-bucket

  4. Настройте брокер сообщений Apache Kafka.

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

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

      Пример:

      • Имя пользователя: kafka-vrp
      • Пароль: 1Y2u3gGvi6VjNHUt

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

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

  1. Получите ключ доступа для работы с Restrictions API с помощью сервиса API-ключей. См. инструкцию Управление доступом к API.

  2. Настройте PostgreSQL:

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

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

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

      create user dbuser_restrictions password 'jwbK65iFrCCcNrkg';

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

      create database onpremise_restrictions owner dbuser_restrictions;

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

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

Файл также используется Navi-Router для определения того, какой из нескольких инстансов Navi-Back может обработать запрос.

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

rules:
    # режим свободной навигации без маршрута
    - name: free-roam
      queries: ['free_roam']
      routing: []
    # маршруты для автомобилей
    - name: directions-car
      queries: ['routing']
      routing: ['driving']
    # маршруты для пешеходов
    - name: directions-pedestrian
      queries: ['routing']
      routing: ['pedestrian']
    # маршруты для велосипедов и самокатов
    - name: directions-bicycle
      queries: ["routing"]
      routing: ["bicycle", "scooter"]
    # маршруты для такси
    - name: directions-taxi
      queries: ['routing']
      routing: ['taxi']
    # маршруты для экстренных служб
    - name: directions-emergency
      queries: ['routing']
      routing: ['emergency']
    # маршруты для мотоциклов
    - name: directions-motorcycle
      queries: ["routing"]
      routing: ["motorcycle"]
    # маршруты на общественном транспорте
    - name: public-transport
      queries: ['ctx', 'public_transport']
      routing: ['ctx', 'public_transport']
    # маршруты для грузовиков
    - name: directions-truck
      queries: ['routing']
      routing: ['truck']
    # несколько маршрутов за раз для автомобилей
    - name: pairs-car
      queries: ["get_pairs"]
      routing: ["driving"]
    # несколько маршрутов за раз для пешеходов
    - name: pairs-pedestrian
      queries: ["get_pairs"]
      routing: ["pedestrian"]
    # несколько маршрутов за раз для такси
    - name: pairs-taxi
      queries: ["get_pairs"]
      routing: ["taxi"]
    # несколько маршрутов за раз для велосипедов
    - name: pairs-bicycle
      queries: ["get_pairs"]
      routing: ["bicycle"]
    # достижимые области на автомобиле
    - name: isochrone-car
      queries: ['isochrone']
      routing: ['driving']
    # восстановление маршрута по точкам
    - name: map-matching
      queries: ["map_matching"]
      routing: ["driving"]
    # матрица расстояний для автомобилей
    - name: distance-matrix
      queries: ['get_dist_matrix']
      routing: ['driving']
    # матрица расстояний для грузовиков
    - name: distance-matrix-truck
      queries: ["get_dist_matrix"]
      routing: ["truck"]
    # асинхронная матрица расстояний для автомобилей
    - name: async-car
      queries: ['routing']
      routing: ['driving']
    # асинхронная матрица расстояний для грузовиков
    - name: async-truck
      queries: ['routing']
      routing: ['truck']
    # асинхронная матрица расстояний для велосипедов и самокатов
    - name: async-bicycle
      queries: ["get_dist_matrix"]
      routing: ["bicycle", "scooter"]
    # асинхронная матрица расстояний для пешеходов
    - name: async-pedestrian
      queries: ["get_dist_matrix"]
      routing: ["pedestrian"]
    # маршруты для Планировщика 2ГИС Ситискан
    - name: route-planner
      queries: ["route_planner", "area_clustering"]
      routing: ["driving"]

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

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

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

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

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

    values-castle.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    imagePullSecrets: [onpremise-registry-creds]

    dgctlStorage:
        host: artifacts.example.com
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/api-platform/latest.json
        secure: false
        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ГИС.

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

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

      • Укажите общие настройки для доступа к хранилищу: endpoint, имя бакета, реквизиты для доступа.
      • manifest: укажите путь до файла с манифестом в формате manifests/api-platform/latest.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • 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: директория для монтирования сертификата внутри контейнера.

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

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

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

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

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

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

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

    values-attractor-TRANSPORT.yaml
     dgctlDockerRegistry: docker.storage.example.local:5000

     imagePullSecrets: [onpremise-registry-creds]

     navigroup: dma-car
     rules: []

     # Если эта сущность 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
         castleUrlProxy: http://traffic-proxy/navi-castle

     resources:
         requests:
             cpu: 100m
             memory: 1024Mi
         limits:
             cpu: 2
             memory: 4000Mi

    Где:

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

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

    • navigroup: идентификатор группы для построения маршрутов. Этот параметр необходим, если в одном пространстве имён используются либо несколько сущностей Navi-Front и Navi-Router, либо отдельные сущности Navi-Back и Distance Matrix Async API для расчёта асинхронных матриц.

    • rules: список правил из файла rules.yaml для установки в текущей сущности Navi-Attractor.

    • kafka: настройки доступа к брокеру Apache Kafka для взаимодействия с Distance Matrix Async API. Укажите, только если сущность Navi-Attractor используется для работы с Distance Matrix Async API.

      • groupId: идентификатор группы, которой принадлежит сервис.

      • properties: параметры для доступа к серверу 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-хранилища.
      • bucket: имя бакета для хранения данных запросов.
      • accessKey: идентификатор ключа (S3 access key).
      • secretKey: секретный ключ (S3 secret key).

    • attractor: настройки сервиса Navi-Attractor.

      • appRule: имя правила из списка rules для устанавливаемого типа навигации.
      • castleUrl: URL сервиса Navi-Castle. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • castleUrlProxy: URL прокси для получения дорожных перекрытий. Имеет больший приоритет, чем castleUrl.

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

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

    helm upgrade --install --version=VERSION --atomic --values ./rules.yaml --values ./values-attractor-<transport>.yaml navi-attractor-<transport> 2gis-on-premise/navi-attractor

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

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

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

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

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

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

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

    values-back-SERVICE.yaml
     dgctlDockerRegistry: docker.storage.example.local:5000

     imagePullSecrets: [onpremise-registry-creds]

     navigroup: routing-car
     rules: []

     naviback:
         appRule: directions-car
         castleUrl: navi-castle.svc

         ecaUrl: http://traffic-proxy/eca
         castleUrlProxy: http://traffic-proxy/navi-castle
         forecastUrl: http://traffic-proxy/forecast
         longForecastUrl: http://traffic-proxy/long-forecast

         indices:
           etaCorrectionCores:
             enabled: true
             proxy: true
           forecastedLongSpeeds:
             enabled: true
           forecastedLongSpeedsIndex:
             enabled: true
           forecastedSpeeds:
             enabled: true
           forecastedSpeedsIndex:
             enabled: true
           onlineSpeeds:
             enabled: true
           speedIndex:
             enabled: true

         appPort: 443
         simpleNetwork:
             emergency: false

         # Если эта сущность Navi-Back работает с Distance Matrix API
         behindSplitter: true
         grpcPort: 50051
         dmSourcesLimit: 25
         dmTargetsLimit: 25

         bss:
             enabled: false
             client:
               serviceRemoteAddress: 'http://stat-receiver/bss/3'

     # Если эта сущность Navi-Back не работает с Distance Matrix Async API
     transmitter:
         enabled: true
         host: http://navi-attractor.svc

     # Если эта сущность Navi-Back не работает с Distance Matrix Async API
     envoy:
         resources:
             requests:
                 cpu: 0.1
                 memory: 128Mi
             limits:
                 cpu: 0.1
                 memory: 128Mi

     # Если эта сущность Navi-Back работает с Distance Matrix API
     service:
         headless:
             enabled: true

     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
         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.task.topic
             cancelTopic: navi.cancel.topic
             statusTopic: navi.status.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ГИС.

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

    • navigroup: идентификатор группы для построения маршрутов. Этот параметр необходим, если в одном пространстве имён используются либо несколько сущностей Navi-Front и Navi-Router, либо отдельные сущности Navi-Back и Distance Matrix Async API для расчёта асинхронных матриц.

    • rules: список правил из файла rules.yaml для установки в текущей сущности Navi-Back.

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

      • appRule: имя правила из списка rules для устанавливаемого типа навигации.

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

      • ecaUrl: URL прокси для получения скоростей.

      • castleUrlProxy: URL прокси для получения дорожных перекрытий. Имеет больший приоритет, чем castleUrl.

      • forecastUrl: URL прокси для получения краткосрочных прогнозов скоростей.

      • longForecastUrl: URL прокси для получения долгосрочных прогнозов скоростей.

      • indices: подключение данных для скачивания файлов. Если вы получаете данные через прокси, параметры ниже обязательны и должны иметь значение true:

        • etaCorrectionCores: коэффициенты коррекции времени в пути.

          • enabled: включать ли получение данных о коэффициентах коррекции времени в пути.

          • proxy: использовать URL прокси naviback.castleUrlProxy вместо naviback.castleUrl или naviback.castleHost.

        • forecastedLongSpeeds.enabled: долгосрочный прогноз скоростей (от часа до суток).

        • forecastedLongSpeedsIndex.enabled: получение индекса долгосрочных прогнозов скоростей.

        • forecastedSpeeds.enabled: краткосрочный прогноз скоростей (до 1 часа).

        • forecastedSpeedsIndex.enabled: получение индекса краткосрочных прогнозов скоростей.

        • onlineSpeeds.enabled: текущие скорости, могут обновляться раз в минуту.

        • speedIndex.enabled: получение индекса текущих скоростей.

      • appPort: HTTP-порт для сервиса Navi-Back.

      • simpleNetwork.emergency: включить поддержку построения маршрутов для экстренных служб.

        Обратите внимание, что для построения таких маршрутов необходимо также добавить тип маршрутизации emergency в один из проектов в вашем файле правил.

      • behindSplitter: взаимодействует ли Navi-Back с сервисом Navi-Splitter. Укажите значение true, только если сущность Navi-Back используется для работы Distance Matrix API (в синхронном режиме).

      • grpc: gRPC-порт. Укажите, только если сущность Navi-Back используется для работы Distance Matrix API (в синхронном режиме).

      • dmSourcesLimit и dmTargetsLimit: ограничение размера матрицы для Distance Matrix API.

      • bss: настройки взаимодействия с сервисом сбора статистики.

        • enabled: включите, чтобы отправлять статистику использования ключей.
        • client.serviceRemoteAddress: URL сервиса сбора статистики.

    • transmitter: настройки взаимодействия Navi-Attractor. Укажите, только если сущность Navi-Back не используется для работы с Distance Matrix Async API.

      • enabled: требуется ли взаимодействие с Navi-Attractor.
      • host: URL сервиса Navi-Attractor.

    • envoy: настройки балансировщика. Укажите, только если сущность Navi-Back не используется для работы с Distance Matrix Async API.

    • service.headless.enabled: создать ли второстепенный Headless Service. Укажите значение true, только если сущность Navi-Back используется для работы Distance Matrix API (в синхронном режиме).

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

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

    • license: настройки сервиса лицензий.

      • url: URL-адрес сервиса лицензий. Пример: https://license.

    • kafka: настройки доступа к брокеру Apache Kafka для взаимодействия с Distance Matrix Async API.

      • groupId: идентификатор группы, которой принадлежит сервис.

      • properties: параметры для доступа к серверу 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 считывает их.
        • cancelTopic: название топика для отмены или завершения задач. Этот топик общий для Navi-Back и Navi-Attractor.
        • statusTopic: название топика для обмена информацией о статусах задач. Navi-Back записывает данные о статусах, а Distance Matrix Async API считывает их.

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

      • host: endpoint S3-хранилища.
      • bucket: имя бакета для хранения данных запросов.
      • accessKey: идентификатор ключа (S3 access key).
      • secretKey: секретный ключ (S3 secret key).

    • customCAs: настройки пользовательских сертификатов.

      • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
      • certsPath: директория для монтирования сертификата внутри контейнера.

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

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

  4. Повторите шаги выше для следующего типа навигации.

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

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

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

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

    values-splitter.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    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

    attractor:
        host: navi-attractor.svc

    oneToMany:
        host: navi-back-headless.svc

    passThrough:
        host: navi-back.svc

    Где:

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

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

    • splitter: настройки сервиса Navi-Splitter.

      • appRule: имя правила из списка rules для устанавливаемого типа навигации.
      • ctxUrl: полный URL хоста Navi-Back для работы с Distance Matrix API для общественного транспорта. Укажите, если планируете работать с таким типом матриц.
      • ctxBaseUrl: базовый URL хоста Navi-Back для работы с Distance Matrix API для общественного транспорта. Укажите, если планируете работать с таким типом матриц.

    • attractor.host: имя хоста сервиса Navi-Attractor.

    • oneToMany.host: имя хоста Navi-Back. Укажите, если вы планируете работать с Distance Matrix API.

    • passThrough.host: имя хоста Navi-Back. Укажите, если вы планируете работать с другими базовыми API кроме Distance Matrix API.

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

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

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

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

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

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

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

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

    values-router.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    imagePullSecrets: [onpremise-registry-creds]

    navigroup: routing-car
    rules: []

    router:
        logLevel: Warning
        castleUrl: http://navi-castle.svc

    keys:
        enabled: true
        url: http://keys-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ГИС.

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

    • navigroup: идентификатор группы для построения маршрутов. Этот параметр необходим, если в одном пространстве имён используются либо несколько сущностей Navi-Front и Navi-Router, либо отдельные сущности Navi-Back и Distance Matrix Async API для расчёта асинхронных матриц.

    • rules: список правил из файла rules.yaml для установки в текущей сущности Navi-Back.

    • 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: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.

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

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

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

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

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

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

    values-front.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    imagePullSecrets: [onpremise-registry-creds]

    navigroup: routing-car

    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ГИС.
    • imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.
    • navigroup: идентификатор группы для построения маршрутов. Этот параметр необходим, если в одном пространстве имён используются либо несколько сущностей Navi-Front и Navi-Router, либо отдельные сущности Navi-Back и Distance Matrix Async API для расчёта асинхронных матриц.
    • replicaCount: число реплик сервиса Navi-Front.
    • resources: настройки вычислительных ресурсов для сервиса. Чтобы узнать рекомендуемые значения ресурсов, см. Вычислительные ресурсы.
    • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

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

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

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

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

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

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

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

    values-navi-async-matrix.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    imagePullSecrets: [onpremise-registry-creds]

    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
        taskTopicRules:
        - topic: navi.task.topic
            default: true
            type: car
        attractTopicRules:
        - topic: navi.attract.task.topic
            default: true
            type: car

    keys:
        url: http://keys-api/service/v1/keys
        token: DISTANCE_MATRIX_TOKEN # для автомобильных маршрутов
        truckToken: TRUCK_DIRECTIONS_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ГИС.

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

    • dm: настройки сервиса Distance Matrix Async API.

      • citiesUrl: URL информации о городах, предоставляемой сервисом Navi-Castle.
      • merger: настройки сервиса Distance Matrix Async Merger.

    • serviceAccount.create: создать ли сервисный аккаунт.

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

      • host: endpoint S3-хранилища.
      • bucket: имя бакета для хранения данных запросов. По умолчанию Distance Matrix Async API удаляет все файлы старше 14 дней в бакете.
      • accessKey: идентификатор ключа (S3 access key).
      • secretKey: секретный ключ (S3 secret key).
      • 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: идентификатор группы, которой принадлежит сервис.

      • properties: параметры для доступа к серверу 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 считывает их.

      • 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: тип транспорта для построения маршрутов.

    • keys: настройки сервиса ключей.

      • url: URL сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • token или truckToken: сервисный токен (см. Установка сервиса API-ключей). Выберите название параметра в зависимости от типа необходимых маршрутов: token — для автомобильных маршрутов, truckToken — для грузовых.

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

    • customCAs: настройки пользовательских сертификатов.

      • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
      • certsPath: директория для монтирования сертификата внутри контейнера.

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

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

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

    values-navi-async-grpc-proxy.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    imagePullSecrets: [onpremise-registry-creds]

    dm:
        url: http://navi-async-matrix.host
        port: 80

    Где:

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

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

    • dm: настройки доступа к сервису Distance Matrix Async API.

      • url: URL хоста.
      • port: порт, на котором слушает сервер.

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

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

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

    values-vrp-solver.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    imagePullSecrets: [onpremise-registry-creds]

    kafka:
        groupId: navi_vrp_solver
        properties:
            bootstrap.servers: kafka.example.local:9092
        taskTopic: tsp_task_topic
        statusTopic: 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

    Где:

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

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

    • kafka: настройки доступа к брокеру Apache Kafka.

      • groupId: идентификатор группы, которой принадлежит сервис VRP Solver.

      • properties: параметры для доступа к серверу Kafka:

        Примечание

        В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.

        • bootstrap.servers: URL сервера Kafka.

      • taskTopic: название топика для получения задач от VRP Task Manager.

      • statusTopic: название топика для отправки запросов к VRP Task Manager.

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

      • url: endpoint S3-хранилища.

      • dm: настройки доступа для хранения результатов расчётов матриц расстояний.

        • bucket: имя бакета для сервиса Distance Matrix Async API.
        • accessKey: идентификатор ключа (S3 access key).
        • secretKey: секретный ключ (S3 secret key).

      • vrp: настройки доступа для хранения результатов расчётов VRP.

        • bucket: имя бакета.
        • accessKey: идентификатор ключа (S3 access key).
        • secretKey: секретный ключ (S3 secret key).

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

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

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

    values-vrp-task-manager.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    imagePullSecrets: [onpremise-registry-creds]

    kafka:
        solver:
            groupId: navi_vrp_task_manager
            properties:
                bootstrap.servers: kafka.example.local:9092
        dm:
            groupId: navi_vrp_task_manager
            properties:
                bootstrap.servers: kafka.example.local:9092
        taskTopic: tsp_task_topic
        statusTopic: tsp_status_topic
        messageBusTopic: message_bus_topic

    s3:
        url: 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-api/service/v1/keys
        token: TSP_TOKEN

    dm:
        url: http://navi-async-matrix.host
        key: ''

    Где:

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

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

    • kafka: настройки доступа к брокеру Apache Kafka.

      • solver: настройки для сервиса VRP Task Manager.

        • groupId: идентификатор группы, которой принадлежит сервис VRP Task Manager.

        • properties: параметры для доступа к серверу Kafka:

          Примечание

          В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.

          • bootstrap.servers: URL сервера Kafka.

      • dm: настройки для сервиса Distance Matrix Async API.

        • groupId: идентификатор группы, которой принадлежит сервис VRP Task Manager.

        • properties: параметры для доступа к серверу Kafka:

          Примечание

          В этом примере конфигурационного файла описан способ подключения к серверу Kafka по логину и паролю. Вы также можете настроить аутентификацию по SSL или подключение без аутентификации: см. пояснения к блоку параметров kafka.properties на GitHub.

          • bootstrap.servers: URL сервера Kafka.

      • taskTopic: название топика для отправки задач сервису VRP Solver.

      • statusTopic: название топика для получения результатов решения задач от VRP Solver.

      • messageBusTopic: название топика для обмена сообщениями с сервисом Distance Matrix Async API.

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

      • url: endpoint S3-хранилища.

      • vrp: настройки доступа для хранения результатов расчётов VRP.

        • bucket: имя бакета.
        • accessKey: идентификатор ключа (S3 access key).
        • secretKey: секретный ключ (S3 secret key).

    • db: настройки доступа к серверу PostgreSQL.

      • host: имя хоста или IP-адрес сервера.
      • port: порт, на котором слушает сервер.
      • name: имя базы данных.
      • user и password: реквизиты для доступа к базе данных, указанной в параметре name. Пользователь должен быть либо владельцем этой базы данных, либо суперпользователем.

    • keys: настройки доступа к сервису API-ключей.

      • url: URL сервиса ключей. Этот URL должен быть доступен из всех подов вашего кластера Kubernetes.
      • token: сервисный токен (см. Установка сервиса API-ключей).

    • dm: настройки доступа к Distance Matrix Async API.

  2. Установите сервис с помощью 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ГИС приведёт к некорректной работе: подробнее см. в разделе Работа с дорожными перекрытиями.

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

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

    values-restrictions.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000
    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ГИС.

    • 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: директория для монтирования сертификата внутри контейнера.

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

  3. В конфигурационном файле 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-формате.

  4. Обновите сервис Navi-Castle, используя отредактированный конфигурационный файл values-castle.yaml:

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

    В параметре --version укажите ту же версию API-платформы, что и при прошлом выполнении команды.

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

Проверка сервиса Navi-Castle​

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

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

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

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

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

    kubectl port-forward service/navi-back-<service> 7777:8080

    Где navi-back-<service> — имя инстанса, который вы указывали на этапе установки Navi-Back (например, navi-back-directions-car).

  2. Создайте файл data.json с телом запроса к API навигации. Примеры запросов мы можете найти в документации сервисов навигации:

    • Directions API: маршруты для автомобилей, велосипедов, такси, экстренных служб и пешеходов.
    • Truck Directions API: маршруты для грузового транспорта.
    • Public Transport 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
            }
        ]
    }

  3. Отправьте запрос с использованием 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​

  1. Создайте файл 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]
    }

  2. Отправьте запрос с использованием cURL или аналогичного инструмента (пример для Directions API):

    curl -Lv http://127.0.0.1:7777/get_dist_matrix -d @data.json

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

    {
        "generation_time": 1111,
        "routes":  [{..}, {..}]
    }

Проверка сервиса Navi-Router​

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

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

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

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

  2. Создайте файл data.json с телом запроса к сервису навигации, идентичный файлу из раздела Проверка работоспособности Navi-Back.

  3. Отправьте запрос с использованием 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​

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

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

  1. Создайте файл data.json с телом запроса к сервису навигации, идентичный файлу из раздела Проверка работоспособности Navi-Back.

  2. Отправьте запрос с использованием cURL или аналогичного инструмента (пример для Directions API):

    curl -Lv http://navi-front.example.com:7777/carrouting/6.0.0/global?key=API_KEY -d @data.json

    Где API_KEY — API-ключ для доступа к сервисам навигации.

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

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

Проверка сервиса Distance Matrix Async API​

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

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

  1. Создайте файл 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]
    }

  2. Отправьте запрос с использованием 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"
    }

  3. Выполните запрос статуса задачи, подставив в 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"
    }

  4. Скачайте результат вычислений по 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:

  1. Создайте файл 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
    }

  2. Отправьте запрос с использованием 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
        }
    ]

  3. Проверьте, что перекрытие появилось в системе:

    curl -Lv http://navi-restrictions:7777/restrictions/

  4. Удалите перекрытие:

    curl --request "DELETE" http://navi-restrictions:7777/restrictions/{RESTRICTION_ID}

    Где {RESTRICTION_ID} — значение поля restriction_id в ответе на запрос в шаге 2.

Что дальше?​