mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 17:59:23 -04:00
08432b25ef
# Backport This will backport the following commits from `main` to `8.12`: - [[Docs][EMS] Adding more details about connectivity and link to the stack docs (#175551)](https://github.com/elastic/kibana/pull/175551) <!--- Backport version: 9.4.3 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Jorge Sanz","email":"jorge.sanz@elastic.co"},"sourceCommit":{"committedDate":"2024-01-30T17:34:26Z","message":"[Docs][EMS] Adding more details about connectivity and link to the stack docs (#175551)\n\nRelated to #174716\r\n\r\n* Adds an intro paragraph mentioning the three options regarding EMS and\r\nlimited connectivity: set up a firewall, disable it fully, or install\r\nElastic Maps Server.\r\n* Adds a reference to the Elastic Stack air-gapped guide.\r\n\r\nCo-authored-by: Brandon Morelli <brandon.morelli@elastic.co>","sha":"e69e971fb4a8f09b53ea75c61a22882c2f3ac207","branchLabelMapping":{"^v8.13.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Presentation","release_note:skip","docs","backport:all-open","Feature:Maps","v8.12.0","v8.13.0"],"title":"[Docs][EMS] Adding more details about connectivity and link to the stack docs","number":175551,"url":"https://github.com/elastic/kibana/pull/175551","mergeCommit":{"message":"[Docs][EMS] Adding more details about connectivity and link to the stack docs (#175551)\n\nRelated to #174716\r\n\r\n* Adds an intro paragraph mentioning the three options regarding EMS and\r\nlimited connectivity: set up a firewall, disable it fully, or install\r\nElastic Maps Server.\r\n* Adds a reference to the Elastic Stack air-gapped guide.\r\n\r\nCo-authored-by: Brandon Morelli <brandon.morelli@elastic.co>","sha":"e69e971fb4a8f09b53ea75c61a22882c2f3ac207"}},"sourceBranch":"main","suggestedTargetBranches":["8.12"],"targetPullRequestStates":[{"branch":"8.12","label":"v8.12.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.13.0","branchLabelMappingKey":"^v8.13.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/175551","number":175551,"mergeCommit":{"message":"[Docs][EMS] Adding more details about connectivity and link to the stack docs (#175551)\n\nRelated to #174716\r\n\r\n* Adds an intro paragraph mentioning the three options regarding EMS and\r\nlimited connectivity: set up a firewall, disable it fully, or install\r\nElastic Maps Server.\r\n* Adds a reference to the Elastic Stack air-gapped guide.\r\n\r\nCo-authored-by: Brandon Morelli <brandon.morelli@elastic.co>","sha":"e69e971fb4a8f09b53ea75c61a22882c2f3ac207"}}]}] BACKPORT--> Co-authored-by: Jorge Sanz <jorge.sanz@elastic.co>
262 lines
13 KiB
Text
262 lines
13 KiB
Text
:ems: Elastic Maps Service
|
|
:ems-docker-repo: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8
|
|
:ems-docker-image: {ems-docker-repo}:{version}
|
|
:ems-headers-url: https://deployment-host
|
|
|
|
[[maps-connect-to-ems]]
|
|
== Connect to {ems}
|
|
|
|
https://www.elastic.co/elastic-maps-service[{ems} (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.
|
|
|
|
If you are on a restricted or fully air-gapped environment, you may need to configure your firewall to enable access to EMS resources. Find below details on the domains and HTTP headers used by {ems}. Alternatively, {ems} can be <<disable-ems, disabled>> or <<elastic-maps-server, installed locally>>.
|
|
|
|
[float]
|
|
=== Domains
|
|
|
|
EMS requests are made to the following domains:
|
|
|
|
* Tile Service: `tiles.maps.elastic.co`
|
|
* File Service: `vector.maps.elastic.co`
|
|
|
|
[float]
|
|
=== Headers
|
|
|
|
Find below examples of the request and response headers from Kibana and a minimal `curl` request example showing the response headers sent by each service.
|
|
|
|
WARNING: These headers may change without further notice at anytime and are shared for reference.
|
|
|
|
[float]
|
|
==== EMS Tile Service
|
|
|
|
The EMS Tile Service provides basemaps in three different styles as the default background for Maps visualizations. The basemaps use https://www.openstreetmap.org/about[OpenStreetMap] data following the https://openmaptiles.org/[OpenMapTiles] schema and can be explored at https://maps.elastic.co[maps.elastic.co].
|
|
|
|
Headers for the Tile Service JSON manifest describing the basemaps available.
|
|
|
|
include::headers/tile-json.asciidoc[]
|
|
|
|
Headers for a vector tile asset in _protobuffer_ format from the Tile Service.
|
|
|
|
include::headers/tile-pbf.asciidoc[]
|
|
|
|
Headers for an sprite image asset from the Tile Service
|
|
|
|
include::headers/tile-png.asciidoc[]
|
|
|
|
|
|
[float]
|
|
==== EMS File Service
|
|
|
|
EMS File Service provides the administrative boundaries used for <<maps-add-choropleth-layer,choropleth mapping>> as static assets in GeoJSON or TopoJSON formats and can be explored at https://maps.elastic.co[maps.elastic.co].
|
|
|
|
Headers for the File Service JSON manifest that declares all the datasets available.
|
|
|
|
include::headers/file-json.asciidoc[]
|
|
|
|
Headers for a sample Dataset from the File Service in TopoJSON format.
|
|
|
|
include::headers/file-data.asciidoc[]
|
|
|
|
|
|
[float]
|
|
[id=disable-ems]
|
|
=== Disable {ems}
|
|
|
|
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 <<settings, kibana.yml>> file.
|
|
|
|
. Set `map.includeElasticMapsService` to `false` to turn off the EMS connection.
|
|
. Set `map.tilemap.url` to the URL of your tile server. This configures the default tile layer of Maps.
|
|
|
|
[float]
|
|
[id=elastic-maps-server]
|
|
=== Host {ems} locally
|
|
|
|
NOTE: Find more details about installing Elastic components in an air-gapped environment in the {stack-ref}/air-gapped-install.html[Elastic Stack documentation].
|
|
|
|
If you cannot connect to {ems} from the {kib} server or browser clients, and your cluster has the appropriate license level, you can opt to host the service on your own infrastructure.
|
|
|
|
{hosted-ems} is a self-managed version of {ems} offered as a Docker image that provides both the EMS basemaps and EMS boundaries. The image is bundled with basemaps up to zoom level 8. After connecting it to your {es} cluster for license validation, you have the option to download and configure a more detailed basemaps database.
|
|
|
|
You can use +docker pull+ to download the {hosted-ems} image from the Elastic Docker registry.
|
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
Version {version} of {hosted-ems} has not yet been released, so no Docker image is currently available for this version.
|
|
endif::[]
|
|
|
|
ifeval::["{release-state}"!="unreleased"]
|
|
|
|
["source","bash",subs="attributes"]
|
|
----------------------------------
|
|
docker pull {ems-docker-image}
|
|
----------------------------------
|
|
|
|
Start {hosted-ems} and expose the default port `8080`:
|
|
|
|
["source","bash",subs="attributes"]
|
|
----------------------------------
|
|
docker run --rm --init --publish 8080:8080 \
|
|
{ems-docker-image}
|
|
----------------------------------
|
|
|
|
Once {hosted-ems} is running, follow instructions from the webpage at `localhost:8080` to define a configuration file and optionally download a more detailed basemaps database.
|
|
|
|
[role="screenshot"]
|
|
image::images/elastic-maps-server-instructions.png[Set-up instructions]
|
|
|
|
endif::[]
|
|
|
|
[float]
|
|
[[elastic-maps-server-configuration]]
|
|
==== Configuration
|
|
|
|
{hosted-ems} 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` container environment variable and defaults to `/usr/src/app/server/config/elastic-maps-server.yml`. This environment variable can be changed by making use of the `-e` docker flag of the start command.
|
|
|
|
*General settings*
|
|
|
|
[cols="2*<"]
|
|
|===
|
|
| [[ems-host]]`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 {hosted-ems} container. *Default: _your-hostname_*. <<server-host,Equivalent {kib} setting>>.
|
|
|
|
| `port`
|
|
| Specifies the port used by the backend server. Default: *`8080`*. <<server-port,Equivalent {kib} setting>>.
|
|
|
|
| `basePath`
|
|
| Specify a path at which to mount the server if you are running behind a proxy. This setting cannot end in a slash (`/`). <<server-basePath,Equivalent {kib} setting>>.
|
|
|
|
| `ui`
|
|
| Controls the display of the status page and the layer preview. *Default: `true`*
|
|
|
|
| `logging.level`
|
|
| Verbosity of {hosted-ems} 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`*
|
|
|===
|
|
|
|
|
|
*{es} connection and security settings*
|
|
|
|
[cols="2*<"]
|
|
|===
|
|
|
|
| `elasticsearch.host`
|
|
| URL of the {es} 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 {hosted-ems}. This chain is used by {hosted-ems} to establish trust when connecting to your {es} cluster. <<elasticsearch-ssl-certificateAuthorities,Equivalent {kib} 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 {hosted-ems} to {es} and are required when `xpack.security.http.ssl.client_authentication` in {es} is set to `required`. <<elasticsearch-ssl-cert-key,Equivalent {kib} setting>>.
|
|
|
|
| `elasticsearch.ssl.verificationMode`
|
|
| Controls the verification of the server certificate that {hosted-ems} receives when making an outbound SSL/TLS connection to {es}. 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`*. <<elasticsearch-ssl-verificationMode,Equivalent {kib} setting>>.
|
|
|
|
|===
|
|
|
|
*Server security settings*
|
|
|
|
[cols="2*<"]
|
|
|===
|
|
|
|
| `ssl.enabled`
|
|
| Enables SSL/TLS for inbound connections to {hosted-ems}. When set to `true`, a certificate and its corresponding private key must be provided. *Default: `false`*. <<server-ssl-enabled,Equivalent {kib} setting>>.
|
|
|
|
| `ssl.certificateAuthorities`
|
|
| Paths to one or more PEM-encoded X.509 certificate authority (CA) certificates that make up a trusted certificate chain for {hosted-ems}. This chain is used by the {hosted-ems} to establish trust when receiving inbound SSL/TLS connections from end users. <<server-ssl-certificateAuthorities,Equivalent {kib} 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. <<server-ssl-cert-key,Equivalent {kib} setting>>.
|
|
|
|
| `ssl.supportedProtocols`
|
|
| An array of supported protocols with versions.
|
|
Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2`. *Default: `TLSv1.1`, `TLSv1.2`*. <<server-ssl-supportedProtocols,Equivalent {kib} setting>>.
|
|
|
|
| `ssl.cipherSuites`
|
|
| Details on the format, and the valid options, are available via the
|
|
https://www.openssl.org/docs/man1.1.1/man1/ciphers.html#CIPHER-LIST-FORMAT[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`*. <<server-ssl-cipherSuites,Equivalent {kib} setting>>.
|
|
|===
|
|
|
|
[float]
|
|
[[elastic-maps-server-bind-mount-config]]
|
|
===== Bind-mounted configuration
|
|
|
|
One way to configure {hosted-ems} is to provide `elastic-maps-server.yml` via bind-mounting. With +docker-compose+, the bind-mount can be specified like this:
|
|
|
|
["source","yaml",subs="attributes"]
|
|
--------------------------------------------
|
|
version: '2'
|
|
services:
|
|
{hosted-ems}:
|
|
image: {ems-docker-image}
|
|
volumes:
|
|
- ./elastic-maps-server.yml:/usr/src/app/server/config/elastic-maps-server.yml
|
|
--------------------------------------------
|
|
|
|
[float]
|
|
[[elastic-maps-server-envvar-config]]
|
|
===== Environment variable configuration
|
|
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.
|
|
|
|
WARNING: 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:
|
|
|
|
["source","yaml",subs="attributes"]
|
|
----------------------------------------------------------
|
|
version: '2'
|
|
services:
|
|
{hosted-ems}:
|
|
image: {ems-docker-image}
|
|
environment:
|
|
ELASTICSEARCH_HOST: http://elasticsearch.example.org
|
|
ELASTICSEARCH_USERNAME: 'ems'
|
|
ELASTICSEARCH_PASSWORD: 'changeme'
|
|
----------------------------------------------------------
|
|
|
|
[float]
|
|
[[elastic-maps-server-data]]
|
|
==== Data
|
|
|
|
{hosted-ems} hosts vector layer boundaries and vector tile basemaps for the entire planet. Boundaries include world countries, global administrative regions, and specific country regions. Basemaps up to zoom level 8 are bundled in the Docker image. These basemaps are sufficient for maps and dashboards at the country level. To present maps with higher detail, follow the instructions of the front page to download and configure the appropriate basemaps database. The most detailed basemaps at zoom level 14 are good for street level maps, but require ~90GB of disk space.
|
|
|
|
|
|
[role="screenshot"]
|
|
image::images/elastic-maps-server-basemaps.png[Basemaps download options]
|
|
|
|
TIP: 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.
|
|
|
|
|
|
[float]
|
|
[[elastic-maps-server-kibana]]
|
|
==== Kibana configuration
|
|
|
|
With {hosted-ems} running, add the `map.emsUrl` configuration key in your <<settings, kibana.yml>> file pointing to the root of the service. This setting will point {kib} to request EMS basemaps and boundaries from {hosted-ems}. Typically this will be the URL to the <<ems-host,host and port>> of {hosted-ems}. For example, `map.emsUrl: https://my-ems-server:8080`.
|
|
|
|
|
|
[float]
|
|
[[elastic-maps-server-check]]
|
|
==== Status check
|
|
|
|
{hosted-ems} periodically runs a status check that is exposed in three different forms:
|
|
|
|
* At the root of {hosted-ems}, a web page will render the status of the different services.
|
|
* A JSON representation of {hosted-ems} status is available at the `/status` endpoint.
|
|
* The Docker https://docs.docker.com/engine/reference/builder/#healthcheck[`HEALTHCHECK`] instruction is run by default and will inform about the health of the service, running a process equivalent to the `/status` endpoint.
|
|
|
|
IMPORTANT: {hosted-ems} won't respond to any data request if the license validation is not fulfilled.
|
|
|
|
|
|
[float]
|
|
[[elastic-maps-server-logging]]
|
|
==== Logging
|
|
|
|
Logs are generated in {ecs-ref}[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.
|