Maps API | Urbi On-Prem | 2GIS Documentation

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. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
    3. Installing API Keys service
    4. 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
    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
  4. 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.

  5. Choose domain names for the services.

    Example:

    • Domain name for Tiles API: tiles.example.com
    • Domain name for MapGL JS API: mapgl.example.com

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
  1. Select which variant of Tiles API you want to install: for vector or raster tiles.

  2. 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 the manifests/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.
    • 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. The user and password values are necessary, while jmxUser and jmxPassword are only used for clearing snapshots (see Updating Tiles API service). Default value for each setting is cassandra.
    • 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) and writerNum (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 and clearSnapshots: 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 the api.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 executing keysctl utility.
  3. 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.

  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-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 is traffic-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.

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

To test the operability of the MapGL JS API service and Tiles API service for vector tiles, do one of the following:

  1. Open the domain name or IP address of the service in your browser:

    http://mapgl.example.com
    
  2. 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.

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?