Installing navigation API

Important note:

All passwords and keys in this section are given for illustration purposes.

During a real installation, it is recommended to use more complex and reliable passwords.

1. Before installing

1. Consider getting familiar with:

   • Navigation services documentation
   • On-Premise solution architecture

2. Make sure the necessary preparation steps are completed:

   1. Preparation for installation
   2. Fetching installation artifacts
   3. Installing License service
   4. Installing API Keys service
   5. (Optional) Installing Traffic API Proxy

3. Collect the necessary information that was set or retrieved on previous steps:

   Object	Example value	How to get value
   Docker Registry mirror endpoint	docker.storage.example.local:5000	See Fetching installation artifacts
   Kubernetes secret for accessing Docker Registry	onpremise-registry-creds	See Fetching installation artifacts
   Installation artifacts S3 storage domain name	artifacts.example.com	See Fetching installation artifacts
   Bucket name for installation artifacts	onpremise-artifacts	See Fetching installation artifacts
   Installation artifacts access key	AKIAIOSFODNN7EXAMPLE	See Fetching installation artifacts
   Installation artifacts secret key	wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY	See Fetching installation artifacts
   Path to the manifest file	manifests/1640661259.json	See Fetching installation artifacts
   License service endpoint	https://license	See Installing License service
   API Keys service endpoint	http://keys-api	See Installing API Keys service
   Traffic API Proxy endpoint	http://traffic-proxy	See Installing Traffic API Proxy
   Service tokens*	DIRECTIONS_TOKEN TRUCK_DIRECTIONS_TOKEN PUBLIC_TRANSPORT_TOKEN DISTANCE_MATRIX_TOKEN ISOCHRONE_TOKEN MAP_MATCHING_TOKEN TSP_TOKEN ROUTES_PLANNER_TOKEN (for working with CityLens)	See Installing API Keys service

   * For illustration purposes, it is assumed that service tokens for all the navigation products are available.

4. Determine which services you need to install:

   • Basic navigation APIs: Directions API, Distance Matrix API, Truck Directions API, Map Matching API, Isochrone API, and Public Transport API. For more information on these services, see the overview.
   • Distance Matrix Async API for processing large numbers of points. Can be installed separately or together with other APIs. For more information, see the service architecture.
   • TSP API for solving the traveling salesmen problem (building the shortest route to pass through the specified points). For more information, see the service architecture.
   • Restrictions API for obtaining information about road closures. Installed together with other APIs. For more information, see the service architecture.

5. Make sure that the resource requirements specified in the Helm charts are met:

   Service	Required for which APIs
   Navi-Castle	All
   Navi-Attractor	All
   Navi-Back	All
   Navi-Router	Basic APIs
   Navi-Front	Basic APIs
   Navi-Restrictions	Restrictions API
   Navi-Splitter	Distance Matrix API (belongs to basic APIs)
   Distance Matrix Async API	Distance Matrix Async API, TSP API
   Navi Async gRPC proxy	Distance Matrix Async API if requests to the service will be sent in gRPC format
   VRP Task Manager	TSP API
   VRP Solver	TSP API

   For more information on check resource requirements, refer to the System requirements document.

   Note

   Contents of Helm charts described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open the required values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.

6. Choose domain names for the services.

   Example:

   • Domain name for Navi-Front: navi-front.example.com
   • Domain name for Distance Matrix Async API: navi-async-matrix.example.com
   • Domain name for Restrictions API: navi-restrictions.example.com

2. Prepare infrastructure

For installing Distance Matrix Async API

If you plan to install Distance Matrix Async API, additionally configure the following:

1. PostgreSQL.

   1. Place a PostgreSQL cluster with the domain name navi-async-matrix-postgresql.storage.example.local in the private network. It is assumed that the cluster works on the standard port 5432.

   2. Connect to the cluster as a superuser (usually postgres).

   3. Create a database user and set a password for the user:

      create user dbuser_navi_async_matrix password 'wNgJamrIym8UAcdX';

   4. Create a database owned by this user:

      create database onpremise_navi_async_matrix owner dbuser_navi_async_matrix;

2. S3 compatible storage.

   1. Place an S3 compatible storage (e.g., Ceph) with the domain name navi-async-matrix-s3.storage.example.local in the private network. It is assumed that the storage works on the standard port 80.

   2. Create a user that will be used for the service. Remember the credentials for the user.

      Example:

      • Access key: TRVR4ESNMDDSIXLB3ISV
      • Secret key: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK

   3. Choose bucket names that will be used for the service.

      Example: navi-async-matrix-bucket

      Important note

      By default, the Distance Matrix Async API removes all files older than 14 days from the bucket.

3. Apache Kafka message broker.

   1. Place a Apache Kafka storage with the domain name kafka.example.local in the private network. It is assumed that the storage works on the standard port 9092.

   2. Create a user that will be used for the service. Remember the credentials for the user.

      Example:

      • Username: kafka-async-matrix
      • Password: 1Y2u3gGvi6VjNHUt

For installing TSP API

If you plan to install TSP API, additionally do the following steps:

1. Get an access key to work with TSP API using the API Keys service. See the instruction on Managing API keys.

2. Configure PostgreSQL.

   1. Place a PostgreSQL cluster with the domain name navi-vrp-postgresql.storage.example.local in the private network. It is assumed that the cluster works on the standard port 5432.

   2. Connect to the cluster as a superuser (usually postgres).

   3. Create a database user and set a password for the user:

      create user dbuser_navi_vrp password 'wNgJamrIym8UAcdX';

   4. Create a database owned by this user:

      create database onpremise_navi_vrp owner dbuser_navi_vrp;

3. Configure access to the S3 compatible storage.

   Choose a bucket name that will be used for the service in the storage with the domain name navi-async-matrix-s3.storage.example.local.

   Example: navi-vrp-bucket

4. Configure the Apache Kafka message broker.

   1. Place an Apache Kafka storage with the domain name kafka.example.local in the private network. It is assumed that the storage works on the standard port 9092.

   2. Create a user that will be used for the service. Remember the credentials for the user.

      Example:

      • Username: kafka-vrp
      • Password: 1Y2u3gGvi6VjNHUt

For installing Restrictions API

If you plan to install Restrictions API, additionally do the following steps:

1. Get an access key to work with Restrictions API using the API Keys service. See the instruction on Managing API keys.

2. Configure PostgreSQL.

   1. Place a PostgreSQL cluster with the domain name navi-restrictions-postgresql.storage.example.local in the private network. It is assumed that the cluster works on the standard port 5432.

   2. Connect to the cluster as a superuser (usually postgres).

   3. Create a database user and set a password for the user:

      create user dbuser_restrictions password 'jwbK65iFrCCcNrkg';

   4. Create a database owned by this user:

      create database onpremise_restrictions owner dbuser_restrictions;

3. Create a rules file

Navi-Back uses rules file to specify the type of requests it can serve. This allows a Navi-Back instance to fetch and store a limited set of data from Navi-Castle that is sufficient to serve the specified type of requests.

Rules file is also used by the Navi-Router service to determine which of the several Navi-Back instances can process a request.

Create a rules.yaml file with a set of required rules. Copy only blocks required for your installation from the example below:

rules:
    # free navigation mode without a route
    - name: free-roam
      queries: ['free_roam']
      routing: []
    # car routes
    - name: directions-car
      queries: ['routing']
      routing: ['driving']
    # pedestrian routes
    - name: directions-pedestrian
      queries: ['routing']
      routing: ['pedestrian']
    # bicycle and scooter routes
    - name: directions-bicycle
      queries: ['routing']
      routing: ["bicycle", "scooter"]
    # taxi routes
    - name: directions-taxi
      queries: ['routing']
      routing: ['taxi']
    # routes for emergency services
    - name: directions-emergency
      queries: ['routing']
      routing: ['emergency']
    # public transport routes
    - name: public-transport
      queries: ['public_transport']
      routing: ['public_transport']
    # truck routes
    - name: directions-truck
      queries: ['routing']
      routing: ['truck']
    # areas reachable by car
    - name: isochrone-car
      queries: ['isochrone']
      routing: ['driving']
    # restoring a route by points
    - name: map-matching
      queries: ["map_matching"]
      routing: ["driving"]
    # distance matrix
    - name: distance-matrix
      queries: ['get_dist_matrix']
      routing: ['driving']
    # Distance Matrix Async API for cars
    - name: async-car
      queries: ['routing']
      routing: ['driving']
    # Distance Matrix Async API for trucks
    - name: async-truck
      queries: ['routing']
      routing: ['truck']
    # routes for the CityLens Task Planner
    - name: route-planner
      queries: ["route_planner", "area_clustering"]
      routing: ["driving"]

4. Install navigation API services

Install Navi-Castle service

Installing Navi-Castle is a prerequisite for using any navigation API.

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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/latest.json
       secure: false
       region: ''
   
   resources:
       limits:
           cpu: 1000m
           memory: 512Mi
       requests:
           cpu: 500m
           memory: 128Mi
   
   cron:
       enabled:
           import: true
       schedule:
           import: '*/10 * * * *'
       concurrencyPolicy: Forbid
       successfulJobsHistoryLimit: 3
       failedJobsHistoryLimit: 3
   
   init:
       enabled:
           import: true
           restriction: false
           restrictionImport: false
   
   customCAs:
       bundle: ''
       # bundle: |
       #   -----BEGIN CERTIFICATE-----
       #   ...
       #   -----END CERTIFICATE-----
       certsPath: ''

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • dgctlStorage: Installation Artifacts Storage settings.

     • Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
     • manifest: fill in the path to the manifest file in the manifests/latest.json format. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
     • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
     • region: S3 storage region.

   • resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.

   • cron: the Kubernetes Cron Job settings. These setting are the same for all deployed Navi-Castle service's replicas. This job fetches actual data from Installation Artifacts Storage and updates the data on the Navi-Castle replica.

     • enabled.import, enabled.restriction: flags that control whether the jobs are enabled (default: false). If both jobs are disabled, no Navi-Castle replicas will get data updates.
     • schedule.import, schedule.restriction: schedules of the jobs in cron format.
     • concurrencyPolicy: the job concurrency policy.
     • successfulJobsHistoryLimit: how many completed jobs should be kept.
     • failedJobsHistoryLimit: how many failed jobs should be kept.

   • init: settings of data import during service start.

     • enabled.import: flag that controls whether data import is enabled. If the persistentVolume.enabled flag is disabled, old data will be lost during new import.
     • enabled.restriction, enabled.restrictionImport: flags that control whether Restrictions API or restrictions import is enabled respectively. These flags are incompatible with each other.

   • customCAs: custom certificates settings.

     • bundle: text representation of a certificate in the X.509 PEM public-key format.
     • certsPath: bundle mount directory in the container.

2. Deploy the service with Helm using the created values-castle.yaml configuration file.

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

   On its first start, a Navi-Castle replica will fetch the data from Installation Artifacts Storage. After that, the data will be updated on schedule by the Cron Job.

3. Test Navi-Castle deployment following the instruction now (recommended) on in the end of the installation procedure.

Install Navi-Attractor service

Installing Navi-Attractor is a prerequisite for using any navigation API.

Do the steps below for each navigation type to be installed:

1. Create a Helm configuration file. See here for more details on the available settings. Name the file following the values-attractor-<transport>.yaml pattern (for example, values-attractor-truck.yaml).

   The example is prefilled with the necessary data collected on previous steps.

   values-attractor-TRANSPORT.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   navigroup: dma-car
   rules: []
   
   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
   
   s3:
       enabled: true
       host: navi-async-matrix-s3.storage.example.local:80
       bucket: navi-async-matrix-bucket
       accessKey: TRVR4ESNMDDSIXLB3ISV
       secretKey: 6gejRs5fyRGKIFjwkiBDaowadGLtmWs2XjEH18YK
   
   attractor:
       app_rule: async-car
       castleUrl: http://navi-castle
       ecaUrl: http://traffic-proxy
   
   resources:
       requests:
           cpu: 100m
           memory: 1024Mi
       limits:
           cpu: 2
           memory: 4000Mi

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • navigroup: ID of a routing group. Required if either multiple Navi-Front and Navi-Router instances or separate Navi-Back and Distance Matrix Async API instances are used in the same namespace.

   • rules: list of routing rules from the rules.yaml file to be installed in the current Navi-Attractor instance.

   • kafka: access settings for the Apache Kafka broker for interacting with Distance Matrix Async API.

     • groupId: ID of the group the service belongs to.

     • properties: parameters for accessing the Kafka server:

       Note

       This configuration file example describes the method of accessing the Kafka server using a login and a password. You can also configure SSL authentication or unauthenticated access: see comments on kafka.properties settings on GitHub.

       • bootstrap.servers: URL of the Kafka server.
       • sasl.username: Kafka user name.
       • sasl.password: password for the Kafka user.

     • distanceMatrix: names of the topics for interacting with Distance Matrix Async API. For a detailed diagram of service interactions, see Navigation services architecture.

       • taskTopic: name of the topic for exchanging information on tasks. Distance Matrix Async API writes data and Navi-Attractor reads it.
       • cancelTopic: name of the topic for canceling or finishing tasks. This topic is shared between Navi-Back and Navi-Attractor.
       • statusTopic: name of the Navi-Attractor topic for exchanging information on task statuses. Navi-Attractor writes data and Distance Matrix Async API reads it.

   • s3: access settings for the S3 compatible storage for interacting with Distance Matrix Async API.

     • host: endpoint of the S3 storage.
     • bucket: bucket name for storing the request data.
     • accessKey: S3 access key.
     • secretKey: S3 secret key.

   • attractor: Navi-Attractor service settings.

     • app_rule: name of the rule from the rules list for the navigation type to be installed.
     • castleUrl: URL of Navi-Castle service. This URL should be accessible from all the pods within your Kubernetes cluster.
     • ecaUrl: domain name of the Traffic API Proxy service. This URL should be accessible from all the pods within your Kubernetes cluster.

   • resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.

2. Deploy the service with Helm using the created values-attractor-<transport>.yaml configuration file.

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

3. Repeat steps above for the other transport type, if needed.

Install Navi-Back service

Installing Navi-Back is a prerequisite for using any navigation API.

For each navigation type you need to install a separate Navi-Back entity. Perform the actions below for each navigation type to be installed:

1. Create a Helm configuration file. See here for more details on the available settings. Name the file following the values-back-<service>.yaml pattern (for example, values-back-directions-car.yaml).

   The example is prefilled with the necessary data collected on previous steps.

   values-back-SERVICE.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   navigroup: routing-car
   rules: []
   
   naviback:
       app_rule: directions-car
       castleUrl: navi-castle.svc
       ecaUrl: http://traffic-proxy
       appPort: 443
       simpleNetwork:
           emergency: false
   
       # If this Navi-Back entity works with Distance Matrix API
       behindSplitter: true
       grpcPort: 50051
       dmSourcesLimit: 25
       dmTargetsLimit: 25
   
   # If this Navi-Back entity works with Distance Matrix API
   service:
       headless:
           enabled: true
   
   replicaCount: 1
   
   resources:
       limits:
           cpu: 2000m
           memory: 16000Mi
       requests:
           cpu: 1000m
           memory: 1024Mi
   
   license:
       url: 'https://license'
   
   # If this Navi-Back entity works with 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
   
   # If this Navi-Back entity works with 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: ''

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • navigroup: ID of a routing group. Required if either multiple Navi-Front and Navi-Router instances or separate Navi-Back and Distance Matrix Async API instances are used in the same namespace.

   • rules: list of routing rules from the rules.yaml file to be installed in the current Navi-Attractor instance.

   • naviback: Navi-Back service settings.

     • app_rule: name of the rule from the rules list for the navigation type to be installed.

     • castleUrl: URL of Navi-Castle service. This URL should be accessible from all the pods within your Kubernetes cluster.

     • ecaUrl: domain name of the Traffic API Proxy service. This URL should be accessible from all the pods within your Kubernetes cluster.

     • appPort: HTTP port for the Navi-Back service.

     • simpleNetwork.emergency: enable support for emergency vehicle routes.

       Note that to be able to build such routes, you also need to add the emergency routing type to one of the projects in your rules.yaml file.

     • behindSplitter: whether Navi-Back interacts with the Navi-Splitter service. Set to true only if the Navi-Back entity is used for working with Distance Matrix API (in synchronous mode).

     • grpc: gRPC port. Specify only if the Navi-Back entity is used for working with Distance Matrix API (in synchronous mode).

     • dmSourcesLimit and dmTargetsLimit: matrix size limits for Distance Matrix API.

   • service.headless.enabled: whether to create a secondary Headless Service. Set to true only if the Navi-Back entity is used for working with Distance Matrix API (in synchronous mode).

   • replicaCount: number of the Navi-Back service replicas.

   • resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.

   • license: the License service settings.

     • url: License service URL address. Example: https://license.

   • kafka: access settings for the Apache Kafka broker for interacting with Distance Matrix Async API.

     • groupId: Navi-Back group identifier.

     • properties: parameters for accessing the Kafka server:

       Note

       This configuration file example describes the method of accessing the Kafka server using a login and a password. You can also configure SSL authentication or unauthenticated access: see comments on kafka.properties settings on GitHub.

       • bootstrap.servers: URL of the Kafka server.
       • sasl.username: Kafka user name.
       • sasl.password: password for the Kafka user.

     • distanceMatrix: names of the topics for interacting with Distance Matrix Async API. For a detailed diagram of service interactions, see Navigation services architecture.

       • taskTopic: name of the topic for exchanging information on tasks. Distance Matrix Async API reads it writes data and Navi-Back reads it.
       • cancelTopic: name of the topic for canceling or finishing tasks. This topic is shared between Navi-Back and Navi-Attractor.
       • statusTopic: name of the topic for exchanging information on task statuses. Navi-Back writes data and Distance Matrix Async API reads it.

   • s3: access settings for the S3 compatible storage for interacting with Distance Matrix Async API.

     • host: endpoint of the S3 storage.
     • bucket: bucket name for storing the request data.
     • accessKey: S3 access key.
     • secretKey: S3 secret key.

   • customCAs: custom certificates settings.

     • bundle: text representation of a certificate in the X.509 PEM public-key format.
     • certsPath: bundle mount directory in the container.

2. Deploy the service with Helm using the created values-back-<service>.yaml configuration file.

   helm upgrade --install --version=1.32.0 --atomic --values ./rules.yaml --values ./values-back-<service>.yaml navi-back-<service> 2gis-on-premise/navi-back

   Example of the command for installing Directions API for car routes:

   helm upgrade --install --version=1.32.0 --atomic --values ./rules.yaml --values ./values-back-directions-car.yaml navi-back-directions-car 2gis-on-premise/navi-back

3. Test Navi-Back deployment following the instruction now (recommended) on in the end of the installation procedure.

4. Repeat steps above for the next navigation type.

Install Navi-Splitter service

Installing Navi-Splitter is a prerequisite for using Distance Matrix API (in synchronous mode).

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   values-splitter.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   splitter:
       app_rule:
   
       # If you plan to work with Distance Matrix API for public transport
       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

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • splitter: Navi-Splitter service settings.

     • app_rule: name of the rule from the rules list for the navigation type to be installed.
     • ctxUrl: full URL of the Navi-Back host for working with Distance Matrix API for public transport. Specify if you plan to work with this type of matrices.
     • ctxBaseUrl: base URL of the Navi-Back host for working with Distance Matrix API for public transport. Specify if you plan to work with this type of matrices.

   • attractor.host: host name of the Navi-Attractor service.

   • oneToMany.host: host name of Navi-Back. Specify if you plan to work with Distance Matrix API.

   • passThrough.host: host name of Navi-Back. Specify if you plan to work with other basic APIs besides Distance Matrix API.

2. Deploy the service with Helm using the created values-splitter.yaml configuration file.

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

3. Test Navi-Splitter deployment following the instruction now (recommended) on in the end of the installation procedure.

Install Navi-Router service

Installing Navi-Router is a prerequisite for using basic navigation APIs.

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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: '' # for working with CityLens
   
   replicaCount: 2
   
   resources:
       limits:
           cpu: 2000m
           memory: 1024Mi
       requests:
           cpu: 500m
           memory: 128Mi

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • navigroup: ID of a routing group. Required if either multiple Navi-Front and Navi-Router instances or separate Navi-Back and Distance Matrix Async API instances are used in the same namespace.

   • rules: list of routing rules from the rules.yaml file to be installed in the current Navi-Attractor instance.

   • router: Navi-Router service settings.

     • logLevel: logging level, default is Warning. Available levels: Verbose, Info, Warning, Error, Fatal.
     • castleUrl: URL of the Navi-Castle service. This URL must be accessible from all the pods within your Kubernetes cluster.

   • keys: API Keys settings. If this parameter is omitted, the API key verification step will be skipped.

     • enabled: whether API Keys usage is turned on.
     • url: URL of the API Keys service endpoint. This URL must be accessible from all the pods within your Kubernetes cluster.
     • refreshIntervalSec: interval between key updates in seconds.
     • downloadTimeoutSec: timeout of key downloading in seconds.
     • apis: service tokens for sharing usage statistics with the API Keys service (see Fetching the service tokens).

   • replicaCount: number of service replicas.

   • resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.

2. Deploy the service with Helm using the created values-router.yaml configuration file.

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

3. Test Navi-Router deployment following the instruction now (recommended) on in the end of the installation procedure.

Install Navi-Front service

Installing Navi-Front is a prerequisite for using basic navigation APIs.

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.
   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.
   • navigroup: ID of a routing group. Required if either multiple Navi-Front and Navi-Router instances or separate Navi-Back and Distance Matrix Async API instances are used in the same namespace.
   • replicaCount: number of service replicas.
   • resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.
   • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

2. Deploy the service with Helm using the created values-front.yaml configuration file.

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

3. Test Navi-Front deployment following the instruction now (recommended) on in the end of the installation procedure.

Install Distance Matrix Async API service

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   values-navi-async-matrix.yaml

   dgctlDockerRegistry: docker.storage.example.local:5000
   
   imagePullSecrets: [onpremise-registry-creds]
   
   dm:
       citiesUrl: http://navi-castle/cities.conf
       taskSplitSize: 5000
       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 # for car routing
       truckToken: TRUCK_DIRECTIONS_TOKEN # for truck routing
   
   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: ''

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • dm: Distance Matrix Async API service settings.

     • citiesUrl: URL of the information about cities provided by the Navi-Castle service.
     • taskSplitSize: minimum size of a distance matrix to get split and handled in sub-requests.
     • merger: Distance Matrix Async Merger service settings.

   • serviceAccount.create: whether to create a service account.

   • s3: access settings for the S3 compatible storage.

     • host: endpoint of the S3 storage.
     • bucket: bucket name for storing the request data. By default, the Distance Matrix Async API removes all files older than 14 days from the bucket.
     • accessKey: S3 access key.
     • secretKey: S3 secret key.
     • region: S3 storage region.

   • db: access settings for the PostgreSQL server.

     • host: host name or IP address of the PostgreSQL server.

     • port: listening port of the PostgreSQL server.

     • name: database name.

     • user and password: credentials for accessing the database specified in the name setting. The user must be the owner of this database or a superuser.

     • schema: PostgreSQL schema to use. Default value is public.

     • tls: settings for the mTLS connection to the database:

       • enabled: whether mTLS connection to a PostgreSQL server is enabled.

       • rootCert: root certificate file.

       • cert: certificate of the PostgreSQL server.

       • key: key of the PostgreSQL server.

       • mode: level of protection, one of the following:

         • verify-full (recommended): eavesdropping and MITM protection.
         • verify-ca: eavesdropping protection is implemented, MITM protection depends on the CA policy.
         • require: eavesdropping protection is implemented.
         • prefer: eavesdropping protection is possible if supported by the server.
         • allow: eavesdropping protection is possible if required by the server.
         • disable: no protection.

   • kafka: access settings for the Apache Kafka broker. For a detailed diagram of service interactions via Apache Kafka, see Navigation services architecture.

     • groupId: Distance Matrix Async API group identifier.

     • properties: parameters for accessing the Kafka server:

       Note

       This configuration file example describes the method of accessing the Kafka server using a login and a password. You can also configure SSL authentication or unauthenticated access: see comments on kafka.properties settings on GitHub.

       • bootstrap.servers: URL of the Kafka server.
       • sasl.plain.username: Kafka user name.

     • sensitiveProperties.sasl.plain.password: password for the Kafka user.

     • cancelTopic: name of the topic for canceling or obtaining information about finished tasks. This topic is shared between Navi-Back and Navi-Attractor.

     • mergerGroupId: identifier of the group to which the Distance Matrix Async Merger service belongs.

     • mergerStatusTopic: name of the topic for obtaining information about the status of Distance Matrix Async Merger tasks. Distance Matrix Async Merger writes data and Distance Matrix Async API reads it.

     • mergerTaskTopic: name of the topic for receiving tasks for Distance Matrix Async Merger. Distance Matrix Async API writes data and Distance Matrix Async Merger reads it.

     • attractTopic: name of the topic for obtaining task results from Navi-Attractor. Navi-Attractor writes data and Distance Matrix Async API reads it.

     • oneToManyTopic: name of the topic for exchanging information on task statuses. Navi-Back writes data and Distance Matrix Async API reads it.

     • taskTopicRules: information about the topics that Distance Matrix Async API will use to send the requests. Defined as a list where each element must have two parameters:

       • topic: name of the Navi-Back topic. Distance Matrix Async API writes data and Navi-Back reads it.

       • projects or default: parameters that define which requests to send to the topic.

         Distance Matrix Async API sends requests to different topics based on their projects. For each topic other than the default one, the projects setting must be defined containing a list of projects (see rules file). For the default topic, the default: true setting must be defined. The default topic will be used to send the requests related to the projects not listed in any other topic's projects.

         The configuration must contain one and only one topic with default: true.

       • type: routing transport type (car or truck).

     • attractTopicRules: rules for mapping request types with topics.

       • topic: name of the Navi-Attractor topic. Distance Matrix Async API writes data and Navi-Attractor reads it.

       • projects or default: parameters that define which requests to send to the topic.

         Distance Matrix Async API sends requests to different topics based on their projects. For each topic other than the default one, the projects setting must be defined containing a list of projects (see rules file). For the default topic, the default: true setting must be defined. The default topic will be used to send the requests related to the projects not listed in any other topic's projects.

         The configuration must contain one and only one topic with default: true.

       • type: routing transport type (car or truck).

   • keys: the API Keys service settings.

     • url: URL of the service. This URL should be accessible from all the pods within your Kubernetes cluster.
     • token or truckToken: service token (see Installing API Keys service). Choose one of the parameter names depending on the required routing type: token - for car routing, truckToken - for truck routing.

   • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

   • customCAs: custom certificates settings.

     • bundle: text representation of a certificate in the X.509 PEM public-key format.
     • certsPath: bundle mount directory in the container.

2. Deploy the service with Helm using the created values-navi-async-matrix.yaml configuration file.

   helm upgrade --install --version=1.32.0 --atomic --values ./values-navi-async-matrix.yaml navi-async-matrix 2gis-on-premise/navi-async-matrix

Install Navi Async gRPC proxy service

Installing Navi Async gRPC proxy is a prerequisite if requests to Distance Matrix Async API will be sent in the gRPC format.

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • dm: settings to access the Distance Matrix Async API service.

     • url: host URL.
     • port: listening port of the server.

2. Deploy the service with Helm using the created values-navi-async-grpc-proxy.yaml configuration file.

   helm upgrade --install --version=1.32.0 --atomic --values ./values-navi-async-grpc-proxy.yaml navi-async-grpc-proxy 2gis-on-premise/navi-async-grpc-proxy

Install VRP Solver service

Installing VRP Solver is a prerequisite for using TSP API.

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • kafka: access settings for the Apache Kafka broker.

     • groupId: VRP Solver group identifier.

     • properties: parameters for accessing the Kafka server:

       Note

       This configuration file example describes the method of accessing the Kafka server using a login and a password. You can also configure SSL authentication or unauthenticated access: see comments on kafka.properties settings on GitHub.

       • bootstrap.servers: URL of the Kafka server.

     • taskTopic: name of the topic for getting tasks from VRP Task Manager.

     • statusTopic: name of the topic for sending requests to VRP Task Manager.

   • s3: access settings for the S3 compatible storage.

     • url: endpoint of the S3 storage.

     • dm: access setting for storing results of distance matrix calculations.

       • bucket: bucket name for the Distance Matrix Async API service.
       • accessKey: S3 access key.
       • secretKey: S3 secret key.

     • vrp: access settings for storing results of VRP calculations.

       • bucket: bucket name.
       • accessKey: S3 access key.
       • secretKey: S3 secret key.

2. Deploy the service with Helm using the created values-vrp-solver.yaml configuration file.

   helm upgrade --install --version=1.32.0 --atomic --values ./values-vrp-solver.yaml navi-vrp-solver 2gis-on-premise/navi-vrp-solver

Install VRP Task Manager

Installing VRP Task Manager is a prerequisite for using TSP API.

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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: ''

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • kafka: access settings for the Apache Kafka broker.

     • sovler: setting for the VRP Task Manager service.

       • groupId: VRP Task Manager group identifier.

       • properties: parameters for accessing the Kafka server:

         Note

         This configuration file example describes the method of accessing the Kafka server using a login and a password. You can also configure SSL authentication or unauthenticated access: see comments on kafka.properties settings on GitHub.

       • bootstrap.servers: URL of the Kafka server.

     • dm: settings for the Distance Matrix Async API service.

       • groupId: VRP Task Manager group identifier.

       • properties: parameters for accessing the Kafka server:

         Note

         This configuration file example describes the method of accessing the Kafka server using a login and a password. You can also configure SSL authentication or unauthenticated access: see comments on kafka.properties settings on GitHub.

       • bootstrap.servers: URL of the Kafka server.

     • taskTopic: name of the topic for sending tasks to VRP Solver.

     • statusTopic: name of the topic for getting task solving results from VRP Solver.

     • messageBusTopic: name of the topic for communicating with the Distance Matrix Async API service.

   • s3: access settings for the S3 compatible storage.

     • url: endpoint of the S3 storage.

     • vrp: access settings for storing results of VRP calculations.

       • bucket: bucket name.
       • accessKey: S3 access key.
       • secretKey: S3 secret key.

   • db: access settings for the PostgreSQL server.

     • host: host name or IP address of the server.
     • port: listening port of the server.
     • name: database name.
     • user and password: credentials for accessing the database specified in the name setting. The user must be the owner of this database or a superuser.

   • keys: access settings for the API Keys service.

     • url: URL of the API Keys service endpoint. This URL must be accessible from all the pods within your Kubernetes cluster.
     • token: service token (see Installing API Keys service).

   • dm: access settings for the Distance Matrix Async API service.

     • url: URL of the Distance Matrix Async API service.
     • key: API key to access the service. See the instruction on Managing API keys.

2. Deploy the service with Helm using the created values-vrp-task-manager.yaml configuration file.

   helm upgrade --install --version=1.32.0 --atomic --values ./values-vrp-task-manager.yaml navi-vrp-task-manager 2gis-on-premise/navi-vrp-task-manager

Install Restrictions API service

1. Create a Helm configuration file. See here for more details on the available settings.

   The example is prefilled with the necessary data collected on previous steps.

   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
       failedJobsHistory: 3
       projects:
           - moscow
       maxAttributesFetcherRps: 25
   
   customCAs:
       bundle: ''
       # bundle: |
       #   -----BEGIN CERTIFICATE-----
       #   ...
       #   -----END CERTIFICATE-----
       certsPath: ''

   Where:

   • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

   • imagePullSecrets: Kubernetes Secrets to access the Docker Registry with the images of the On-Premise services.

   • naviBackHost: host name of any Navi-Back service deployed.

   • naviCastleHost: host name of Navi-Castle.

   • postgres: access settings for the PostgreSQL server.

     • host: host name or IP address of the PostgreSQL server.
     • port: listening port of the PostgreSQL server.
     • name: database name.
     • user and password: credentials for accessing the database specified in the name setting. The user must be the owner of this database or a superuser.

   • api: API service settings.

     • key: API key that will be used to interact with Navigation services. The value of this setting must match the value of the restrictions.key setting of the Navi-Castle service.
     • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

   • cron: settings for retrieving information from Navigation services.

     • successfulJobsHistoryLimit: how many completed jobs should be kept.
     • failedJobsHistoryLimit: how many failed jobs should be kept.
     • projects: list of Navi-Back projects (see Rules file).
     • maxAttributesFetcherRps: maximum amount of requests to edgeAttributesUrlTemplate per second.

   • customCAs: custom certificates settings.

     • bundle: text representation of a certificate in the X.509 PEM public-key format.
     • certsPath: bundle mount directory in the container.

2. Deploy the service with Helm using the created values-restrictions.yaml configuration file:

   helm upgrade --install --version=1.32.0 --atomic --wait-for-jobs --values ./values-restrictions.yaml navi-restrictions 2gis-on-premise/navi-restrictions

3. Edit castle.restrictions and cron settings in the Navi-Castle configuration file as follows:

   castle:
       restrictions:
           key: secret
           host: http://navi-restrictions.example.local
   
   cron:
       enabled:
           import: true
           restriction: true
       schedule:
           import: '*/10 * * * *'
           restriction: '*/10 * * * *'
       concurrencyPolicy: Forbid
       successfulJobsHistoryLimit: 3
       failedJobsHistoryLimit: 3

   Where:

   • castle: Navi-Castle configuration.

     • restrictions.key: key that will be used to interact with the Restrictions API service. An arbitrary string.
     • restrictions.host: URL of the Restrictions API service. This URL should be accessible from all the pods within your Kubernetes cluster.

   • cron: the (Kubernetes Cron Job) settings. These settings are the same for all deployed Navi-Castle service's replicas. This job fetches actual data from Installation Artifacts Storage and updates the data on the Navi-Castle replica.

     • enabled.import, enabled.restriction: flags that control whether the jobs are enabled (default: false). If both jobs are disabled, no Navi-Castle replicas will get data updates.
     • schedule.import, schedule.restriction: schedules of the jobs in cron format.

4. Update the Navi-Castle service using the edited values-castle.yaml configuration file:

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

5. Test deployment

Test Navi-Castle service

To test that the Navi-Castle service is working, you can do the following:

1. Port forward the service using kubectl:

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

2. Send a GET request to the root endpoint (/) using cURL or a similar tool:

   curl -Lv http://localhost:7777/

   You should receive an HTML listing of all files and folders similar to the following:

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

Test Navi-Back service

To test that the Navi-Back instance is working, you can do the following:

1. Port forward the service using kubectl:

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

   Where navi-back-<service> is the instance name that you specified during Navi-Back installation (for example, navi-back-directions-car).

2. Create the data.json file containing the body of a navigation API request. You can find request examples in the documentation for navigation services:

   • Directions API: routes for cars, bicycles, taxi, emergency services, and pedestrians.

   • Truck Directions API: routes for trucks.

   • Public Transport API: routes for public transport.

   • Isochrone API: areas reachable by car.

   • Distance Matrix API: distance matrices.

   Testing of the Distance Matrix Async API is described below.

   The example below contains a request to Directions API for building a car route (the example is valid for Moscow):

   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. Send the request using cURL or a similar tool (example for Directions API):

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

   You should receive a response with the following structure (example for Directions API):

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

   You can find response examples for other services in their documentation.

Test Navi-Splitter service

1. Create the data.json file containing the body of a request to Distance Matrix API. Example:

   {
       "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. Send the request using cURL or a similar tool:

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

   You should receive a response with the following structure:

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

Test Navi-Router service

Sending a request to the service requires an API key generated using the API Keys service. For more information, see Keys and tokens.

To test that the Navi-Router service is working, you can do the following:

1. Port forward the service using kubectl:

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

2. Create a data.json file containing the body of a service request, identical to the file from Testing the deployment of Navi-Back.

3. Send the request using cURL or a similar tool (example for Directions API):

   curl -Lv http://127.0.0.1:7777/carrouting/6.0.0/global?key=API_KEY -d @data.json

   Where API_KEY is your API key to access navigation services.

   You should receive a response containing the rule name:

   directions-car

Test Navi-Front service

Sending a request to the service requires an API key generated using the API Keys service. For more information, see Keys and tokens.

To test that the Navi-Front service is working, you can do the following:

1. Create a data.json file containing the body of a service request, identical to the file from Testing the deployment of Navi-Back.

2. Send the request using cURL or a similar tool:

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

   Where API_KEY is your API key to access navigation services.

   You should receive a response with the following structure:

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

Test Distance Matrix Async API service

Sending a request to the service requires an API key generated using the API Keys service. For more information, see Keys and tokens.

To test that the Distance Matrix Async API service is working, you can do the following:

1. Create a data.json file containing the body of the request (the example is valid for Moscow):

   {
       "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. Send the request using cURL or a similar tool:

   curl -Lv https://navi-async-matrix.example.com/create_task/get_dist_matrix?key=API_KEY --header 'Content-Type: application/json' -d @data.json

   Where API_KEY is your API key to access navigation services.

   You should receive a response with the following structure:

   {
       "task_id": "{TASK_ID}",
       "message": "success add task",
       "status ": "success"
   }

3. Request the task status using the TASK_ID parameter received on the previous step.

   curl -Lv https://navi-async-matrix.example.com/result/get_dist_matrix/{TASK_ID}

   Perform the request multiple times if necessary, while the task is running. Eventually, you should receive a response with the following structure:

   {
       "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. Download the calculation results using the URL received in the result_link field on the previous step. Make sure that the result is a valid JSON file. Example:

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

Test Restrictions API service

To test that the Restrictions API service is working, you can do the following:

1. Create a data.json file containing the body of the request (the example is valid for Moscow):

   {
       "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. Send the request using cURL or a similar tool:

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

   You should receive a response with the following structure:

   [
       {
           "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. Verify that the road closure has appeared in the system:

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

4. Remove the closure:

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

   Where {RESTRICTION_ID} is the value of the restriction_id field from the request response obtained on step 2.

What's next?

• Find out how to update navigation API.

• Install other On-Premise products:

  • maps API
  • search API
  • Urbi Pro
  • CityLens
  • mobile SDK
  • GIS Platform
  • Traffic API proxy
  • Platform Manager

• Learn recommendations on serving the installation:

  • backing up infrastructure databases
  • monitoring service health
  • collecting and sending logs