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

Consider getting familiar with:
- Navigation services documentation
- On-Premise solution architecture
Make sure the necessary preparation steps are completed:

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

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.
- Restrictions API for obtaining information about road closures. Installed together with other APIs. For more information, see the service architecture.

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

Service	Required for which APIs
Navi-Castle	All
Navi-Back	All
Navi-Router	Basic APIs
Navi-Front	Basic APIs
Navi-Restrictions	Restrictions API
Navi-Attractor	Distance Matrix Async API
Distance Matrix Async API	Distance Matrix Async 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.

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 required for the service

For installing any navigation APIs

Configure a file storage for Navi-Castle. Choose a path where these files with data will be stored.

Example: /opt/castle/data

For installing Distance Matrix Async API

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

PostgreSQL.
1. Place a PostgreSQL cluster with the domain name navi-async-matrix-postgresql.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port 5432.
2. Connect to the cluster a superuser (usually postgres).
3. Create a database user that will be used for the service. 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;
```
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. This instruction assumes 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.
Apache Kafka message broker.
1. Place a Apache Kafka storage with the domain name kafka.example.local in the private network. This instruction assumes 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 Restrictions API

If you plan to install Restrictions API, additionally configure PostgreSQL:

Place a PostgreSQL cluster with the domain name navi-restrictions-postgresql.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port 5432.
Connect to the cluster a superuser (usually postgres).
Create a database user that will be used for the service. Set a password for the user.
```
create user dbuser_restrictions password 'jwbK65iFrCCcNrkg';
```

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 routes
    - name: directions-bicycle
      queries: ['routing']
      routing: ['bicycle']
    # 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: ['get_hull']
      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']

4. Install navigation API services

Install Navi-Castle service

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

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

persistentVolume:
    enabled: false
    type: pvc
    accessModes: [ReadWriteOnce]
    storageClass: ''
    size: 5Gi

castle:
    castleDataPath: /opt/castle/data/

cron:
    enabled:
        import: true
    schedule:
        import: '*/10 * * * *'
    concurrencyPolicy: Forbid
    successfulJobsHistoryLimit: 3
    failedJobsHistoryLimit: 3

init:
    enabled:
        import: true
        restriction: false
        restrictionImport: false

replicaCount: 1

customCAs:
    bundle: ''
    # bundle: |
    #   -----BEGIN CERTIFICATE-----
    #   ...
    #   -----END CERTIFICATE-----
    certsPath: ''
```
Where:
- dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.
- 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.
- persistentVolume: settings of Kubernetes Persistent Volume Claim (PVC) that is used to store the service data.
  - enabled: flag that controls whether PVC is enabled. If PVC is disabled, a service's replica can lose its data.
  - type: storage type (pvc or ephemeral).
  - accessModes: access mode for the PVC. Available modes are the same as for Persistent Volumes.
  - storageClass: storage class for the PVC.
  - size: storage size.
  Important note:
  
  Navi-Castle is deployed using StatefulSet. This means that every Navi-Castle replica will get its own dedicated Persistent Storage with the specified settings.
  
  For example, if you configure the size setting as 5Gi, then the total storage volume required for 3 replicas will be equal to 15Gi.
- castle: Navi-Castle settings.
  - castleDataPath: path to the Navi-Castle data directory.
- 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.
- replicaCount: number of the Navi-Castle service replicas. Note that each replica's pod will get its own dedicated cron job to fetch the actual data from Installation Artifacts Storage.
- 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.
Deploy the service with Helm using the created values-castle.yaml configuration file.
```
helm upgrade --install --version=1.38.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.
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 Distance Matrix Async API.

Distance Matrix Async API allows you to build routes for two types of transport: cars and trucks. For each transport type you need to install a separate Navi-Attractor entity. Perform the actions below for each navigation type to be installed:

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

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: car_attract_task_topic
        cancelTopic: cancel_topic
        statusTopic: attract_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
    dmSourcesLimit: 4000
    dmTargetsLimit: 4000

resources:
    requests:
        cpu: 100m
        memory: 1024Mi
    limits:
        cpu: 2
        memory: 4000Mi
```
Where:
- dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.
- 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.
    - taskTopic: name of the topic for receiving new tasks.
    - cancelTopic: name of the topic for canceling or finishing tasks.
    - statusTopic: name of the topic for obtaining information on task status.
- 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.
  - dmSourcesLimit and dmTargetsLimit: matrix size limits.
- resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.

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

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

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

Install Navi-Back service

Installing Navi-Back is a prerequisite for 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:

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

navigroup: routing-car
rules: []

naviback:
    app_rule: directions-car
    castleUrl: navi-castle.svc
    ecaUrl: http://traffic-proxy
    appPort: 443
    app_rule: directions-car
    simpleNetwork:
        emergency: false
    dmSourcesLimit: 4000 # if you use Distance Matrix Async API
    dmTargetsLimit: 4000 # if you use Distance Matrix Async API

replicaCount: 1

resources:
    limits:
        cpu: 2000m
        memory: 16000Mi
    requests:
        cpu: 1000m
        memory: 1024Mi

license:
    url: 'https://license'

# Only if you use 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: car_task_topic
        cancelTopic: cancel_topic
        statusTopic: one_to_many_topic

# Only if you use 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: your Docker Registry endpoint where On-Premise services' images reside.
- 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.
  - dmSourcesLimit and dmTargetsLimit: matrix size limits.
- 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.
    - taskTopic: name of the topic for receiving new tasks from Distance Matrix Async API.
    - cancelTopic: name of the topic for canceling or finishing tasks.
    - statusTopic: name of the topic for exchanging statuses between Navi-Back and Distance Matrix Async API.
- 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.

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

helm upgrade --install --version=1.38.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.38.0 --atomic --values ./rules.yaml --values ./values-back-directions-car.yaml navi-back-directions-car 2gis-on-premise/navi-back

Test Navi-Back deployment following the instruction now (recommended) on in the end of the installation procedure.
Repeat steps above for the next navigation type.

Install Navi-Router service

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

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

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: your Docker Registry endpoint where On-Premise services' images reside.
- 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.

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

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

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 basic navigation APIs.

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

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: your Docker Registry endpoint where On-Premise services' images reside.
- 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.

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

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

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

Install Distance Matrix Async API service

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

dm:
    citiesUrl: http://navi-castle/cities.conf
    archiver:
        enabled: true
        fetchLogs: true
        resources:
            requests:
                cpu: 100m
                memory: 100Mi
            limits:
                cpu: 1
                memory: 1Gi

rbac:
    create: true

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
    statusTopic: status_topic
    cancelTopic: cancel_topic
    archiveTopic: archive_topic
    attractTopic: attract_topic
    oneToManyTopic: one_to_many_topic
    taskTopicRules:
    - topic: car_task_topic
        default: true
        type: car
    attractTopicRules:
    - topic: car_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: your Docker Registry endpoint where On-Premise services' images reside.
- dm: Distance Matrix Async API service settings.
  - citiesUrl: URL of the information about cities provided by the Navi-Castle service.
  - archiver: archiver job settings.
- rbac.create: whether to use RBAC.
- 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: hostname 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.
  - 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.
  - statusTopic: name of the topic for obtaining information on task status.
  - cancelTopic: name of the topic for canceling or obtaining information about finished tasks.
  - attractTopic: name of the topic for obtaining Navi-Attractor task results.
  - oneToManyTopic: name of the topic for Navi-Back and Distance Matrix Async API interaction.
  - 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 topic.
    - 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 topic.
    - 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.

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

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

Install Restrictions API service

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: your Docker Registry endpoint where On-Premise services' images reside.
- naviBackHost: host name of any Navi-Back service deployed.
- naviCastleHost: host name of Navi-Castle.
- postgres: access settings for the PostgreSQL server.
  - host: hostname 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: 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.

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

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

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.

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

helm upgrade --install --version=1.38.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:

Port forward the service using kubectl:

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

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:

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).
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
        }
    ]
}
```
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-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:

Port forward the service using kubectl:

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

Create a data.json file containing the body of a service request, identical to the file from Testing the deployment of Navi-Back.
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:

Create a data.json file containing the body of a service request, identical to the file from Testing the deployment of Navi-Back.
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:

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

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

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

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:

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
}

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

Verify that the road closure has appeared in the system:
```
curl -Lv http://navi-restrictions:7777/restrictions/
```
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 the service:
- Updating navigation API
Install other On-Premise products: