Installing maps 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:
-
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 API Keys service endpoint keys.example.local
See Installing API Keys service Traffic API Proxy endpoint traffic-proxy.example.local
See Installing Traffic API Proxy Service tokens TILES_TOKEN
See Installing API Keys service -
Make sure that the following system requirements are met (the requirements are given for the minimal amount of replicas):
-
For testing environment:
Service vCPU RAM Storage MapGL JS API 2 4 GB — Tiles API Backend 2 1 GB Apache Cassandra Apache Cassandra 3 48 GB 500 GB Kubernetes Importer job 1 4 GB — Total amount: 8 57 GB 500 GB -
For production environment:
Service vCPU RAM Storage MapGL JS API 4 4 GB — Tiles API Backend 8 1 GB Apache Cassandra Apache Cassandra 12 48 GB 500 GB Kubernetes Importer job 4 4 GB — Total amount: 28 57 GB 500 GB
Note:
Detailed requirements for each service are listed in the System requirements document.
-
-
Choose domain names for the services.
Example:
- Domain name for Tiles API:
tiles.example.com
- Domain name for MapGL JS API:
mapgl.example.com
- Domain name for Tiles API:
2. Prepare infrastructure required for the service
Configure Apache Cassandra
Place one or multiple instances of an Apache Cassandra in the private network.
It is recommended to allow JMX access to Apache Cassandra to enable removing storage snapshots (see Updating Tiles API service).
Example:
- Hosts:
tiles-cassandra-1.storage.example.local
tiles-cassandra-2.storage.example.local
- Username:
cassandrauser
- Password:
CASSANDRAPASSWORD-DWTYB05URKZJEDDN
- JMX username:
jmxuser
- JMX password:
JMXPASSWORD-MNZLQTFH0MDDHIX8
3. Install Maps services
Install Tiles API service
-
Select which variant of Tiles API you want to install: for vector or raster tiles.
-
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-tiles.yaml
dgctlDockerRegistry: docker.storage.example.local:5000/2gis-on-premise dgctlStorage: host: artifacts.example.com bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/1640661259.json serviceName: tiles-api-raster type: raster cassandra: hosts: - tiles-cassandra-1.storage.example.local - tiles-cassandra-2.storage.example.local replicaFactor: 3 consistencyLevelRead: LOCAL_QUORUM consistencyLevelWrite: LOCAL_QUORUM credentials: user: cassandrauser password: CASSANDRAPASSWORD-DWTYB05URKZJEDDN jmxUser: jmxuser jmxPassword: JMXPASSWORD-MNZLQTFH0MDDHIX8 importer: workerNum: 20 writerNum: 8 workerResources: requests: cpu: 256m memory: 512Mi limits: cpu: 2 memory: 2048Mi cleaner: enabled: true limit: 3 clearSnapshots: true api: imagePullSecrets: [onpremise-registry-creds] pdb: enabled: false ingress: hosts: - host: tiles.example.com proxy: access: enabled: true url: http://tiles-api.example.local token: TILES_TOKEN
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 themanifests/1640661259.json
format. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
-
serviceName
: name of the service:- for Tiles API with vector tiles support —
tiles-api-webgl
. - for Tiles API with raster tiles support —
tiles-api-raster
.
- for Tiles API with vector tiles support —
-
type
: flavor of the service.- for Tiles API with vector tiles support — do not specify this parameter.
- for Tiles API with raster tiles support —
raster
-
cassandra
: the Apache Cassandra data storage settings.hosts
: an array of the one of more IP adresses of the Apache Cassandra installation.replicaFactor
: replication factor. Adjust this setting in accordance with the installation.- If necessary, adjust consistency level settings in accordance with the installation. See the Apache Cassandra documentation for details.
credentials
: authentication credentials. Theuser
andpassword
values are necessary, whilejmxUser
andjmxPassword
are only used for clearing snapshots (see Updating Tiles API service). Default value for each setting iscassandra
.
-
importer
: the Kubernetes Importer job's worker settings.-
workerNum
: number of workers (parallel import processes). -
writerNum
: number of write processes per one worker.Note:
When deploying the Tiles API with raster tiles support, consider to tune down the values of
workerNum
(default:20
) andwriterNum
(default:8
) settings.Import of raster tiles data may take a significant time to complete, and usage of relatively high default settings may result in cancelling the job due to timeout.
-
workerResources
: computational resources settings for workers. See the minimal requirements table for the actual information about recommended values. -
cleaner
andclearSnapshots
: settings for automatic deletion of older data. See Updating Tiles API service for more details.
See the Installation artifacts lifecycle document for details about how the Import job operates.
-
-
api
: the API backend service.imagePullSecrets
: Kubernetes Secrets for accessing the Docker Registry endpoint where On-Premise services' images reside.pdb.enabled
: enables the protection of the service with Pod Disruption Budget.ingress
: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in theapi.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.
-
proxy
: the API Keys service settings. Use these settings if you want to restrict end-user access to the Tiles API service.access.enabled
: flag that controls whether keys checking for access limiting is enabled.access.url
: URL of the API Keys service's endpoint. This URL should be accessible from all the pods within your Kubernetes cluster.access.token
: a dedicated service token for the Tiles API service. Fetch the key by executingkeysctl
utility.
-
-
Deploy the service with Helm using created
values-tiles.yaml
configuration file.Important note:
When doing a deployment, the Kubernetes Importer job will reinitialize the Apache Cassandra keyspace in the Apache Cassandra installation specified in the
values-tiles.yaml
configuration.This means that all data in this keyspace, if exists, will be completely replaced with the data from the Installation Artifacts Storage.
Existing data is preserved for a short amount of time only if you do a update, not initial deployment.
helm upgrade --install --version=1.4.5 --atomic --values ./values-tiles.yaml tiles-api 2gis-on-premise/tiles-api
Kubernetes Importer job will fetch the required data from the Installation Artifacts Storage and do the import of the data into Apache Cassandra. Then Helm will deploy the service.
Install MapGL JS 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-mapgl.yaml
dgctlDockerRegistry: docker.storage.example.local:5000/2gis-on-premise env: MAPGL_HOST: mapgl.example.com MAPGL_TILES_API: tiles.example.com MAPGL_KEYSERVER: keys.example.com MAPGL_TRAFFICSERVER: traffic-proxy.example.com resources: requests: cpu: 30m memory: 32M limits: cpu: 100m memory: 64M ingress: hosts: - host: mapgl.example.com tls: - hosts: - mapgl.example.com secretName: mapgl-js-api
Where:
-
dgctlDockerRegistry
: your Docker Registry endpoint where On-Premise services' images reside. -
imagePullSecrets
: Kubernetes Secrets for accessing the Docker Registry endpoint where On-Premise services' images reside. -
env
: environment variables.MAPGL_HOST
: domain name for the service. Your applications should use this domain name (or IP address) to communicate with the On-Premise Maps service.MAPGL_TILES_API
: domain name of the deployed Tiles API service.MAPGL_KEYSERVER
: domain name of the API Keys service.MAPGL_TRAFFICSERVER
: domain name of the Traffic API Proxy service. Default server istraffic-jams.2gis.com
.
-
resources
: computational resources settings for workers. See the minimal requirements table for the actual information about recommended values. -
ingress
: configuration of the Ingress resource. Adapt it to your Ingress installation. Note that to use TLS, you need to create a secret containing a certificate and a private key.
-
-
Deploy the service with Helm using created
values-mapgl.yaml
configuration file.helm upgrade --install --version=1.4.5 --atomic --values ./values-mapgl.yaml mapgl-js-api 2gis-on-premise/mapgl-js-api
4. Test deployment
Test MapGL JS API service
To test the operability of the MapGL JS API service and Tiles API service for vector tiles, do one of the following:
-
Open the domain name or IP address of the service in your browser:
http://mapgl.example.com
-
Write a code for displaying the sample map, then open it from a browser:
<html> <head> <title>MapGL JS API. On-Premise</title> <style> #map { width: 100%; height: 100%; } </style> </head> <body> <div id="map"></div> <script src="//mapgl.example.com/api.js"></script> <script> const map = new mapgl.Map('map', { center: [55.31878, 25.23584], zoom: 13, style: '//mapgl.example.com/style/', styleOptions: { iconsPath: '//mapgl.example.com/style/images/', fontsPath: '//mapgl.example.com/style/fonts/', }, useRtlTextPlugin: 'always-on', zoom: 13, }); </script> </body> </html>
Note:
This code slightly differs from the code placed in MapGL JS API documentation. If you use the code examples from the documentation, do not forget to adapt them to your On-Premise Maps service deployment, as shown above.
A sample vector map should be displayed. This map uses vector tiles served by the Tiles API service.
Test Tiles API service with raster tiles support
To verify that Tiles API can serve raster tiles, you can open the following URL in your browser (the example is valid for Moscow):
http://tiles.example.com/tiles?x=1237&y=640&z=11&v=1
A sample raster tile should be displayed.
What's next?
-
Find out how to update the service:
-
Install other On-Premise products: