From 02528f7d454e904b3d476e9cf045ae6517984ba5 Mon Sep 17 00:00:00 2001 From: Jorge Sanz Date: Tue, 28 Nov 2023 17:59:28 +0100 Subject: [PATCH] [Docs][Maps] Include details about the headers requested and served by EMS (#171659) Fixes #129751 ## Summary Extends the EMS documentation to detail request and response headers the browser sends to EMS resources and includes also a minimal `curl` command to request the response headers for same resource as well. I tried to edit this in a way it does not take the whole page but happy to hear feedback or ideas on how to make this easier to digest. https://github.com/elastic/kibana/assets/188264/27e83a5f-4d01-47a8-af2c-3739576bf56e Also, I am not sure if this is something worth adding to our release notes :thinking: (cherry picked from commit 0a7299b0ac2aadfe47aa374002636341a032a6ed) --- docs/maps/connect-to-ems.asciidoc | 47 +++++++++- docs/maps/headers/file-data.asciidoc | 131 ++++++++++++++++++++++++++ docs/maps/headers/file-json.asciidoc | 132 +++++++++++++++++++++++++++ docs/maps/headers/tile-json.asciidoc | 120 ++++++++++++++++++++++++ docs/maps/headers/tile-pbf.asciidoc | 121 ++++++++++++++++++++++++ docs/maps/headers/tile-png.asciidoc | 117 ++++++++++++++++++++++++ 6 files changed, 665 insertions(+), 3 deletions(-) create mode 100644 docs/maps/headers/file-data.asciidoc create mode 100644 docs/maps/headers/file-json.asciidoc create mode 100644 docs/maps/headers/tile-json.asciidoc create mode 100644 docs/maps/headers/tile-pbf.asciidoc create mode 100644 docs/maps/headers/tile-png.asciidoc diff --git a/docs/maps/connect-to-ems.asciidoc b/docs/maps/connect-to-ems.asciidoc index 8db34ee3f61bf..8fac6a6d95c15 100644 --- a/docs/maps/connect-to-ems.asciidoc +++ b/docs/maps/connect-to-ems.asciidoc @@ -3,17 +3,58 @@ :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 https://www.elastic.co/elastic-maps-service[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. +[float] +=== Domains + EMS requests are made to the following domains: -* tiles.maps.elastic.co -* vector.maps.elastic.co +* 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 <> 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[] -Maps makes requests directly from the browser to EMS. [float] === Disable Elastic Maps Service diff --git a/docs/maps/headers/file-data.asciidoc b/docs/maps/headers/file-data.asciidoc new file mode 100644 index 0000000000000..62b47ed714d0a --- /dev/null +++ b/docs/maps/headers/file-data.asciidoc @@ -0,0 +1,131 @@ + +++++ +
+
+ + + +
+
+++++ +[%collapsible] +==== +[source,bash,subs="attributes"] +---------------------------------- +curl -I 'https://vector.maps.elastic.co/files/world_countries_v7.topo.json?elastic_tile_service_tos=agree&my_app_name=kibana&my_app_version={version}' \ +-H 'User-Agent: curl/7.81.0' \ +-H 'Accept: */*' \ +-H 'Accept-Encoding: gzip, deflate, br' +---------------------------------- + +Server response + +[source,regex] +---------------------------------- +HTTP/2 200 +x-guploader-uploadid: ABPtcPpmMffchVgfHIr-SSC00WORo145oV-1q0asjqRvjLV_7cIgyfLRfofXV-BG7huMYABFypblcgdgXRBARhpo2c88ow +x-goog-generation: 1689593325442971 +x-goog-metageneration: 1 +x-goog-stored-content-encoding: gzip +x-goog-stored-content-length: 587241 +content-encoding: gzip +x-goog-hash: crc32c=OcROeg== +x-goog-hash: md5=8KKIwD6wbKa3YYXTnnFcZw== +x-goog-storage-class: MULTI_REGIONAL +accept-ranges: bytes +content-length: 587241 +access-control-allow-origin: * +access-control-expose-headers: Authorization, Content-Length, Content-Type, Date, Server, Transfer-Encoding, X-GUploader-UploadID, X-Google-Trace, accept, elastic-api-version, kbn-name, kbn-version, origin +server: UploadServer +date: Tue, 21 Nov 2023 14:22:16 GMT +expires: Tue, 21 Nov 2023 15:22:16 GMT +cache-control: public, max-age=3600,no-transform +age: 2202 +last-modified: Mon, 17 Jul 2023 11:28:45 GMT +etag: "f0a288c03eb06ca6b76185d39e715c67" +content-type: application/json +alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 +---------------------------------- +==== +++++ +
+ + +
+++++ diff --git a/docs/maps/headers/file-json.asciidoc b/docs/maps/headers/file-json.asciidoc new file mode 100644 index 0000000000000..8e08508da14fc --- /dev/null +++ b/docs/maps/headers/file-json.asciidoc @@ -0,0 +1,132 @@ + +++++ +
+
+ + + +
+
+++++ +[%collapsible] +==== +[source,bash,subs="attributes"] +---------------------------------- +curl -I 'https://vector.maps.elastic.co/v{minor-version}/manifest?elastic_tile_service_tos=agree&my_app_name=kibana&my_app_version={version}' \ +-H 'User-Agent: curl/7.81.0' \ +-H 'Accept: */*' \ +-H 'Accept-Encoding: gzip, deflate, br' +---------------------------------- + +Server response + +[source,regex] +---------------------------------- +HTTP/2 200 +x-guploader-uploadid: ABPtcPp_BvMdBDO5jVlutETVHmvpOachwjilw4AkIKwMrOQJ4exR9Eln4g0LkW3V_LLSEpvjYLtUtFmO0Uwr61XXUhoP_A +x-goog-generation: 1689593295246576 +x-goog-metageneration: 1 +x-goog-stored-content-encoding: gzip +x-goog-stored-content-length: 108029 +content-encoding: gzip +x-goog-hash: crc32c=T5gVpw== +x-goog-hash: md5=6F8KWV8VTdx8FsN2iFehow== +x-goog-storage-class: MULTI_REGIONAL +accept-ranges: bytes +content-length: 108029 +access-control-allow-origin: * +access-control-expose-headers: Authorization, Content-Length, Content-Type, Date, Server, Transfer-Encoding, X-GUploader-UploadID, X-Google-Trace, accept, elastic-api-version, kbn-name, kbn-version, origin +server: UploadServer +date: Tue, 21 Nov 2023 14:25:07 GMT +expires: Tue, 21 Nov 2023 15:25:07 GMT +cache-control: public, max-age=3600,no-transform +age: 2170 +last-modified: Mon, 17 Jul 2023 11:28:15 GMT +etag: "e85f0a595f154ddc7c16c3768857a1a3" +content-type: application/json +alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 +---------------------------------- +==== +++++ +
+ + +
+++++ diff --git a/docs/maps/headers/tile-json.asciidoc b/docs/maps/headers/tile-json.asciidoc new file mode 100644 index 0000000000000..b34e82dcab3cd --- /dev/null +++ b/docs/maps/headers/tile-json.asciidoc @@ -0,0 +1,120 @@ + +++++ +
+
+ + + +
+
+++++ +[%collapsible] +==== +[source,bash,subs="attributes"] +---------------------------------- +curl -I 'https://tiles.maps.elastic.co/v{minor-version}/manifest?elastic_tile_service_tos=agree&my_app_name=kibana&my_app_version={version}' \ +-H 'User-Agent: curl/7.81.0' \ +-H 'Accept: */*' \ +-H 'Accept-Encoding: gzip, deflate, br' +---------------------------------- + +Server response + +[source,regex] +---------------------------------- +HTTP/2 200 +server: BaseHTTP/0.6 Python/3.11.4 +date: Mon, 20 Nov 2023 15:08:46 GMT +content-type: application/json; charset=utf-8 +elastic-api-version: 2023-10-31 +access-control-allow-origin: * +access-control-allow-methods: GET, OPTIONS, HEAD +access-control-allow-headers: Origin, Accept, Content-Type, kbn-version, elastic-api-version +access-control-expose-headers: etag +content-encoding: gzip +vary: Accept-Encoding +x-varnish: 844076 5416505 +accept-ranges: bytes +varnish-age: 85285 +cache-control: private, max-age=86400 +via: 1.1 varnish (Varnish/7.0), 1.1 google +alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 +---------------------------------- +==== +++++ +
+ + +
+++++ diff --git a/docs/maps/headers/tile-pbf.asciidoc b/docs/maps/headers/tile-pbf.asciidoc new file mode 100644 index 0000000000000..52215a714cda1 --- /dev/null +++ b/docs/maps/headers/tile-pbf.asciidoc @@ -0,0 +1,121 @@ + +++++ +
+
+ + + +
+
+++++ +[%collapsible] +==== +[source,bash,subs="attributes"] +---------------------------------- +$ curl -I 'https://tiles.maps.elastic.co/data/v3/1/1/0.pbf?elastic_tile_service_tos=agree&my_app_name=kibana&my_app_version={version}' \ +-H 'User-Agent: curl/7.81.0' \ +-H 'Accept: */*' \ +-H 'Accept-Encoding: gzip, deflate, br' +---------------------------------- + +Server response + +[source,regex] +---------------------------------- +HTTP/2 200 +content-encoding: gzip +content-length: 144075 +access-control-allow-origin: * +access-control-allow-methods: GET, OPTIONS, HEAD +access-control-allow-headers: Origin, Accept, Content-Type, kbn-version, elastic-api-version +access-control-expose-headers: etag +x-varnish: 3269455 5976667 +accept-ranges: bytes +varnish-age: 9045 +via: 1.1 varnish (Varnish/7.0), 1.1 google +date: Mon, 20 Nov 2023 15:08:19 GMT +age: 78827 +last-modified: Thu, 16 Sep 2021 17:14:41 GMT +etag: W/"232cb-zYEfNgd8rzHusLotRFzgRDSDDGA" +content-type: application/x-protobuf +vary: Accept-Encoding +cache-control: public,max-age=3600 +alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 +---------------------------------- +==== +++++ +
+ + +
+++++ diff --git a/docs/maps/headers/tile-png.asciidoc b/docs/maps/headers/tile-png.asciidoc new file mode 100644 index 0000000000000..9d972b1ce8c01 --- /dev/null +++ b/docs/maps/headers/tile-png.asciidoc @@ -0,0 +1,117 @@ + +++++ +
+
+ + + +
+
+++++ +[%collapsible] +==== +[source,bash] +---------------------------------- +curl -I 'https://tiles.maps.elastic.co/styles/osm-bright-desaturated/sprite.png' \ +-H 'User-Agent: curl/7.81.0' \ +-H 'Accept: image/avif,image/webp,*/*' \ +-H 'Accept-Encoding: gzip, deflate, br' +---------------------------------- + +Server response + +[source,regex] +---------------------------------- +HTTP/2 200 +content-length: 17181 +access-control-allow-origin: * +access-control-allow-methods: GET, OPTIONS, HEAD +access-control-allow-headers: Origin, Accept, Content-Type, kbn-version, elastic-api-version +access-control-expose-headers: etag +x-varnish: 8769943 4865354 +accept-ranges: bytes +varnish-age: 250 +via: 1.1 varnish (Varnish/7.0), 1.1 google +date: Tue, 21 Nov 2023 14:44:36 GMT +age: 592 +etag: W/"431d-/dqE/W5Q3FqkHikyDQtCuQqAdlY" +content-type: image/png +cache-control: public,max-age=3600 +alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 +---------------------------------- +==== +++++ +
+ + +
+++++