Connect to Elastic Maps Serviceedit

Elastic Maps Service (EMS) is a service that hosts tile layers and vector shapes of administrative boundaries. If you are using Kibana’s out-of-the-box settings, Maps is already configured to use EMS.

EMS requests are made to the following domains:

  • tiles.maps.elastic.co
  • vector.maps.elastic.co

Maps makes requests directly from the browser to EMS.

Connect to Elastic Maps Service from an internal networkedit

To connect to EMS when your Kibana server and browser are in an internal network:

  1. Set map.proxyElasticMapsServiceInMaps to true in your kibana.yml file to proxy EMS requests through the Kibana server.
  2. Update your firewall rules to allow connections from your Kibana server to the EMS domains.

Coordinate map and region map visualizations do not support map.proxyElasticMapsServiceInMaps and will not proxy EMS requests through the Kibana server.

Disable Elastic Maps Serviceedit

You might experience EMS connection issues if your Kibana server or browser are on a private network or behind a firewall. If this happens, you can disable the EMS connection to avoid unnecessary EMS requests.

To disable EMS, change your kibana.yml file.

  1. Set map.includeElasticMapsService to false to turn off the EMS connection.
  2. Set map.tilemap.url to the URL of your tile server. This configures the default tile layer of Maps.
  3. (Optional) Set map.regionmap to the vector shapes of the administrative boundaries that you want to use.

Host Elastic Maps Service locallyedit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

If you cannot connect to Elastic Maps Service from the Kibana server or browser clients, and your cluster has the appropriate license level, you can opt to host the service on your own infrastructure.

Elastic Maps Server is a self-managed version of Elastic Maps Service offered as a Docker image that provides both the EMS basemaps and EMS boundaries. You must first download and run the image. After connecting it to your Elasticsearch cluster for license validation, you’re guided to download and configure the basemaps database, which must be retrieved separately.

Elastic Maps Server does not serve raster tiles, needed by Vega, coordinate, and region map visualizations.

You can use docker pull to download the Elastic Maps Server image from the Elastic Docker registry.

docker pull docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:7.11.2

Start Elastic Maps Server and expose the default port 8080:

docker run --rm --init --publish 8080:8080 \
  docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:7.11.2

Once Elastic Maps Server is running, follow instructions from the webpage at localhost:8080 to define a configuration file and download the basemaps database.

Set-up instructions

Configurationedit

Elastic Maps Server reads properties from a configuration file in YAML format that is validated on startup. The location of this file is provided by the EMS_PATH_CONF environment variable and defaults to /usr/src/app/server/config/elastic-maps-server.yml.

General settings

host

Specifies the host of the backend server. To allow remote users to connect, set the value to the IP address or DNS name of the Elastic Maps Server container. Default: your-hostname. Equivalent Kibana setting.

port

Specifies the port used by the backend server. Default: 8080. Equivalent Kibana setting.

ui

Controls the display of the status page and the layer preview. Default: true

logging.level

Verbosity of Elastic Maps Server logs. Valid values are trace, debug, info, warn, error, fatal, and silent. Default: info

path.planet

Path of the basemaps database. Default: /usr/src/app/data/planet.mbtiles

Elasticsearch connection and security settings

elasticsearch.host

URL of the Elasticsearch instance to use for license validation.

elasticsearch.username and elasticsearch.password

Credentials of a user with at least the monitor role.

elasticsearch.ssl.certificateAuthorities

Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates that make up a trusted certificate chain for Elastic Maps Server. This chain is used by Elastic Maps Server to establish trust when connecting to your Elasticsearch cluster. Equivalent Kibana setting.

elasticsearch.ssl.certificate and elasticsearch.ssl.key, and elasticsearch.ssl.keyPassphrase

Optional settings that provide the paths to the PEM-format SSL certificate and key files and the key password. These files are used to verify the identity of Elastic Maps Server to Elasticsearch and are required when xpack.security.http.ssl.client_authentication in Elasticsearch is set to required. Equivalent Kibana setting.

elasticsearch.ssl.verificationMode

Controls the verification of the server certificate that Elastic Maps Server receives when making an outbound SSL/TLS connection to Elasticsearch. Valid values are "full", "certificate", and "none". Using "full" performs hostname verification, using "certificate" skips hostname verification, and using "none" skips verification entirely. Default: full. Equivalent Kibana setting.

Server security settings

ssl.enabled

Enables SSL/TLS for inbound connections to Elastic Maps Server. When set to true, a certificate and its corresponding private key must be provided. Default: false. Equivalent Kibana setting.

ssl.certificateAuthorities

Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates that make up a trusted certificate chain for Elastic Maps Server. This chain is used by the Elastic Maps Server to establish trust when receiving inbound SSL/TLS connections from end users. Equivalent Kibana setting.

ssl.key, ssl.certificate, and ssl.keyPassphrase

Location of yor SSL key and certificate files and the password that decrypts the private key that is specified via ssl.key. This password is optional, as the key may not be encrypted. Equivalent Kibana setting.

ssl.supportedProtocols

An array of supported protocols with versions. Valid protocols: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. Default: TLSv1.1, TLSv1.2, TLSv1.3. Equivalent Kibana setting.

ssl.cipherSuites

Details on the format, and the valid options, are available via the OpenSSL cipher list format documentation. Default: TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 TLS_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-GCM-SHA384, DHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, DHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, DHE-RSA-AES256-SHA384, ECDHE-RSA-AES256-SHA256, DHE-RSA-AES256-SHA256, HIGH,!aNULL, !eNULL, !EXPORT, !DES, !RC4, !MD5, !PSK, !SRP, !CAMELLIA. Equivalent Kibana setting.

Bind-mounted configurationedit

One way to configure Elastic Maps Server is to provide elastic-maps-server.yml via bind-mounting. With docker-compose, the bind-mount can be specified like this:

version: '2'
services:
  Elastic Maps Server:
    image: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:7.11.2
    volumes:
      - ./elastic-maps-server.yml:/usr/src/app/config/elastic-maps-server.yml
Environment variable configurationedit

All configuration settings can be overridden by environment variables that are named with all uppercase letters and by replacing YAML periods with underscores. For example elasticsearch.ssl.certificate could be overridden by the environment variable ELASTICSEARCH_SSL_CERTIFICATE. Boolean variables must use the true or false strings.

All information that you include in environment variables is visible through the ps command, including sensitive information.

These variables can be set with docker-compose like this:

version: '2'
services:
  Elastic Maps Server:
    image: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8:7.11.2
    environment:
      ELASTICSEARCH_HOST: http://elasticsearch.example.org
      ELASTICSEARCH_USERNAME: 'ems'
      ELASTICSEARCH_PASSWORD: 'changeme'

Dataedit

Elastic Maps Server hosts vector layer boundaries and vector tile basemaps for the entire planet. Boundaries include world countries, global administrative regions, and specific country regions. A minimal basemap is provided with Elastic Maps Server. This can be used for testing environments but won’t be functional for normal operations. The full basemap (around 90GB file) needs to be mounted on the Docker container for Elastic Maps Server to run normally.

The available basemaps and boundaries can be explored from the /maps endpoint in a web page that is your self-managed equivalent to https://maps.elastic.co

Kibana configurationedit

With Elastic Maps Server running, add the map.emsUrl configuration key in your kibana.yml file pointing to the root of the service. This setting will point Kibana to request EMS basemaps and boundaries from Elastic Maps Server. Typically this will be the URL to the host and port of Elastic Maps Server. For example, map.emsUrl: https://my-ems-server:8080.

Status checkedit

Elastic Maps Server periodically runs a status check that is exposed in three different forms:

  • At the root of Elastic Maps Server, a web page will render the status of the different services.
  • A JSON representation of Elastic Maps Server status is available at the /status endpoint.
  • The Docker HEALTHCHECK instruction is run by default and will inform about the health of the service, running a process equivalent to the /status endpoint.

Elastic Maps Server won’t respond to any data request if the license validation is not fulfilled.

Loggingedit

Logs are generated in ECS JSON format and emitted to the standard output and to /var/log/elastic-maps-server/elastic-maps-server.log. The server won’t rotate the logs automatically but the logrotate tool is installed in the image. Mount /dev/null to the default log path if you want to disable the output to that file.