[Docs] Elastic Maps Server documentation (#85532)
* Elastic Maps Server documentation * Revise product name and docker image * Review feedback * Provide example for map.emsUrl * Update docs/maps/connect-to-ems.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> * Update docs/maps/connect-to-ems.asciidoc Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> Co-authored-by: Nick Peihl <nick.peihl@elastic.co> Co-authored-by: Nick Peihl <nickpeihl@gmail.com> Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
This commit is contained in:
Jorge Sanz
GitHub
parent
755dc7e8ee
commit
84d318e83a
|
|
@ -35,3 +35,188 @@ 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.
|
||||
. (Optional) Set `map.regionmap` to the vector shapes of the administrative boundaries that you want to use.
|
||||
|
||||
[float]
|
||||
[id=elastic-maps-server]
|
||||
=== Host Elastic Maps Service locally
|
||||
|
||||
beta::[]
|
||||
|
||||
If you cannot connect to Elastic Maps Service 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 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 {es} cluster for license validation, you're guided to download and configure the basemaps database, which must be retrieved separately.
|
||||
|
||||
IMPORTANT: {hosted-ems} does not serve raster tiles, needed by Vega, coordinate, and region map visualizations.
|
||||
|
||||
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 download the 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` environment variable and defaults to `/usr/src/app/server/config/elastic-maps-server.yml`.
|
||||
|
||||
*General settings*
|
||||
|
||||
[cols="2*<"]
|
||||
|===
|
||||
| [[ems-hostname]]`hostname`
|
||||
| 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>>.
|
||||
|
||||
| `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`, `TLSv1.3`. *Default: `TLSv1.1`, `TLSv1.2`, `TLSv1.3`*. <<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/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. A minimal basemap is provided with {hosted-ems}. 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 {hosted-ems} to run normally.
|
||||
|
||||
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-hostname,hostname 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.
|
||||
|
|
|
|||
BIN
docs/maps/images/elastic-maps-server-instructions.png
Normal file
BIN
docs/maps/images/elastic-maps-server-instructions.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 102 KiB |
|
|
@ -1,3 +1,7 @@
|
|||
:ems-docker-repo: docker.elastic.co/elastic-maps-service/elastic-maps-server-ubi8
|
||||
:ems-docker-image: {ems-docker-repo}:{version}
|
||||
:hosted-ems: Elastic Maps Server
|
||||
|
||||
[role="xpack"]
|
||||
[[maps]]
|
||||
= Maps
|
||||
|
|
|
|||
|
|
@ -192,7 +192,7 @@ In addition to this setting, trusted certificates may be specified via
|
|||
<<elasticsearch-ssl-truststore-path, `elasticsearch.ssl.truststore.path`>>. If the trust store
|
||||
has no password, leave this as blank. If the trust store has an empty password, set this to `""`.
|
||||
|
||||
| `elasticsearch.ssl.verificationMode:`
|
||||
|[[elasticsearch-ssl-verificationMode]] `elasticsearch.ssl.verificationMode:`
|
||||
| Controls the verification of the server certificate that {kib} receives when
|
||||
making an outbound SSL/TLS connection to {es}. Valid values are `"full"`,
|
||||
`"certificate"`, and `"none"`. Using `"full"` performs hostname verification,
|
||||
|
|
@ -526,7 +526,7 @@ users. If PKI authentication is enabled, this chain is also used by {kib} to ver
|
|||
|
||||
In addition to this setting, trusted certificates may be specified via <<server-ssl-keystore-path, `server.ssl.keystore.path`>> and/or <<server-ssl-truststore-path, `server.ssl.truststore.path`>>.
|
||||
|
||||
| `server.ssl.cipherSuites:`
|
||||
| [[server-ssl-cipherSuites]] `server.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`*.
|
||||
|
|
@ -585,7 +585,7 @@ the trust store has no password, leave this unset. If the trust store has an emp
|
|||
| {kib} binds to this port and redirects
|
||||
all http requests to https over the port configured as <<server-port, `server.port`>>.
|
||||
|
||||
| `server.ssl.supportedProtocols:`
|
||||
| [[server-ssl-supportedProtocols]] `server.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*
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue