Document new ip_location APIs (#116611)

Author: joegallo

docs/changelog/114548.yaml

@@ -0,0 +1,5 @@
+pr: 114548
+summary: Support IPinfo database configurations
+area: Ingest Node
+type: enhancement
+issues: []

docs/reference/ingest/apis/delete-geoip-database.asciidoc renamed to docs/reference/ingest/apis/delete-ip-location-database.asciidoc

@@ -1,30 +1,30 @@
-[[delete-geoip-database-api]]
-=== Delete geoip database configuration  API
+[[delete-ip-location-database-api]]
+=== Delete IP geolocation database configuration API
 ++++
-<titleabbrev>Delete geoip database configuration</titleabbrev>
+<titleabbrev>Delete IP geolocation database configuration</titleabbrev>
 ++++
 
-Deletes a geoip database configuration.
+Deletes a IP geolocation database configuration.
 
 [source,console]
 ----
-DELETE /_ingest/geoip/database/my-database-id
+DELETE /_ingest/ip_location/database/my-database-id
 ----
 // TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
 
 
-[[delete-geoip-database-api-request]]
+[[delete-ip-location-database-api-request]]
 ==== {api-request-title}
 
-`DELETE /_ingest/geoip/database/<database>`
+`DELETE /_ingest/ip_location/database/<database>`
 
-[[delete-geoip-database-api-prereqs]]
+[[delete-ip-location-database-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the
 `manage` <<privileges-list-cluster,cluster privilege>> to use this API.
 
-[[delete-geoip-database-api-path-params]]
+[[delete-ip-location-database-api-path-params]]
 ==== {api-path-parms-title}
 
 `<database>`::
@@ -35,21 +35,21 @@ DELETE /_ingest/geoip/database/my-database-id
 --
 
 
-[[delete-geoip-database-api-query-params]]
+[[delete-ip-location-database-api-query-params]]
 ==== {api-query-parms-title}
 
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
 
-[[delete-geoip-database-api-example]]
+[[delete-ip-location-database-api-example]]
 ==== {api-examples-title}
 
 
-[[delete-geoip-database-api-specific-ex]]
-===== Delete a specific geoip database configuration
+[[delete-ip-location-database-api-specific-ex]]
+===== Delete a specific IP geolocation database configuration
 
 [source,console]
 ----
-DELETE /_ingest/geoip/database/example-database-id
+DELETE /_ingest/ip_location/database/example-database-id
 ----
 // TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]

docs/reference/ingest/apis/get-geoip-database.asciidoc renamed to docs/reference/ingest/apis/get-ip-location-database.asciidoc

@@ -1,33 +1,33 @@
-[[get-geoip-database-api]]
-=== Get geoip database configuration API
+[[get-ip-location-database-api]]
+=== Get IP geolocation database configuration API
 ++++
-<titleabbrev>Get geoip database configuration</titleabbrev>
+<titleabbrev>Get IP geolocation database configuration</titleabbrev>
 ++++
 
-Returns information about one or more geoip database configurations.
+Returns information about one or more IP geolocation database configurations.
 
 [source,console]
 ----
-GET /_ingest/geoip/database/my-database-id
+GET /_ingest/ip_location/database/my-database-id
 ----
 // TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
 
 
 
-[[get-geoip-database-api-request]]
+[[get-ip-location-database-api-request]]
 ==== {api-request-title}
 
-`GET /_ingest/geoip/database/<database>`
+`GET /_ingest/ip_location/database/<database>`
 
-`GET /_ingest/geoip/database`
+`GET /_ingest/ip_location/database`
 
-[[get-geoip-database-api-prereqs]]
+[[get-ip-location-database-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the
  `manage` <<privileges-list-cluster,cluster privilege>> to use this API.
 
-[[get-geoip-database-api-path-params]]
+[[get-ip-location-database-api-path-params]]
 ==== {api-path-parms-title}
 
 `<database>`::
@@ -38,22 +38,22 @@ supported.
 To get all database configurations, omit this parameter or use `*`.
 
 
-[[get-geoip-database-api-query-params]]
+[[get-ip-location-database-api-query-params]]
 ==== {api-query-parms-title}
 
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
 
 
-[[get-geoip-database-api-example]]
+[[get-ip-location-database-api-example]]
 ==== {api-examples-title}
 
 
-[[get-geoip-database-api-specific-ex]]
-===== Get information for a specific geoip database configuration
+[[get-ip-location-database-api-specific-ex]]
+===== Get information for a specific IP geolocation database configuration
 
 [source,console]
 ----
-GET /_ingest/geoip/database/my-database-id
+GET /_ingest/ip_location/database/my-database-id
 ----
 // TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
 

docs/reference/ingest/apis/index.asciidoc

@@ -25,23 +25,21 @@ Use the following APIs to get statistics about ingest processing:
 the <<geoip-processor,`geoip` processor>>.
 
 [discrete]
-[[ingest-geoip-database-apis]]
-=== Ingest GeoIP Database APIs
-
-preview::["The commercial IP geolocation database download management APIs are in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but this feature is not subject to the support SLA of official GA features."]
+[[ingest-ip-location-database-apis]]
+=== Ingest IP Location Database APIs
 
 Use the following APIs to configure and manage commercial IP geolocation database downloads:
 
-* <<put-geoip-database-api>> to create or update a database configuration
-* <<get-geoip-database-api>> to retrieve a database configuration
-* <<delete-geoip-database-api>> to delete a database configuration
+* <<put-ip-location-database-api>> to create or update a database configuration
+* <<get-ip-location-database-api>> to retrieve a database configuration
+* <<delete-ip-location-database-api>> to delete a database configuration
 
 include::put-pipeline.asciidoc[]
 include::get-pipeline.asciidoc[]
 include::delete-pipeline.asciidoc[]
 include::simulate-pipeline.asciidoc[]
 include::simulate-ingest.asciidoc[]
 include::geoip-stats.asciidoc[]
-include::put-geoip-database.asciidoc[]
-include::get-geoip-database.asciidoc[]
-include::delete-geoip-database.asciidoc[]
+include::put-ip-location-database.asciidoc[]
+include::get-ip-location-database.asciidoc[]
+include::delete-ip-location-database.asciidoc[]

docs/reference/ingest/apis/put-geoip-database.asciidoc

@@ -0,0 +1,92 @@
+[[put-ip-location-database-api]]
+=== Create or update IP geolocation database configuration API
+++++
+<titleabbrev>Create or update IP geolocation database configuration</titleabbrev>
+++++
+
+Creates or updates an IP geolocation database configuration.
+
+IMPORTANT: The Maxmind `account_id` shown below requires a license key. Because the license key is sensitive information,
+it is stored as a <<secure-settings,secure setting>> in {es} named `ingest.geoip.downloader.maxmind.license_key`. Only
+one Maxmind license key is currently allowed per {es} cluster. A valid license key must be in the secure settings in order
+to download from Maxmind. The license key setting does not take effect until all nodes are restarted or a
+<<cluster-nodes-reload-secure-settings, `reload_secure_settings`>> request is executed.
+
+[source,console]
+----
+PUT _ingest/ip_location/database/my-database-1
+{
+  "name": "GeoIP2-Domain",
+  "maxmind": {
+    "account_id": "1234567"
+  }
+}
+----
+// TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
+
+IMPORTANT: The IPinfo configuration shown below requires a token. Because the token is sensitive information,
+it is stored as a <<secure-settings,secure setting>> in {es} named `ingest.ip_location.downloader.ipinfo.token`. Only
+one IPinfo token is currently allowed per {es} cluster. A valid token must be in the secure settings in order
+to download from IPinfo. The token setting does not take effect until all nodes are restarted or a
+<<cluster-nodes-reload-secure-settings, `reload_secure_settings`>> request is executed.
+
+[source,console]
+----
+PUT _ingest/ip_location/database/my-database-2
+{
+  "name": "standard_location",
+  "ipinfo": {
+  }
+}
+----
+// TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
+
+
+[[put-ip-location-database-api-request]]
+==== {api-request-title}
+
+`PUT /_ingest/ip_location/database/<database>`
+
+[[put-ip-location-database-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage` <<privileges-list-cluster,cluster privilege>> to use this API.
+
+
+[[put-ip-location-database-api-path-params]]
+==== {api-path-parms-title}
+
+`<database>`::
++
+__
+(Required, string) ID of the database configuration to create or update.
+
+[[put-ip-location-database-api-query-params]]
+==== {api-query-parms-title}
+
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+[[put-ip-location-database-api-request-body]]
+==== {api-request-body-title}
+
+// tag::ip-location-database-object[]
+`name`::
+(Required, string)
+The provider-assigned name of the IP geolocation database to download.
+
+`<provider>`::
+(Required, a provider object and its associated configuration)
+The configuration necessary to identify which IP geolocation provider to use to download
+the database, as well as any provider-specific configuration necessary for such downloading.
++
+At present, the only supported providers are `maxmind` and `ipinfo`. The maxmind provider
+requires that an `account_id` (string) is configured. The ipinfo provider does not require
+additional configuration in the request body.
+// end::ip-location-database-object[]
+
+[[ip-location-database-configuration-licensing]]
+==== Licensing
+
+Downloading databases from third party providers is a commercial feature that requires an
+appropriate license. For more information, refer to https://www.elastic.co/subscriptions.

docs/reference/ingest/apis/put-ip-location-database.asciidoc

@@ -1926,4 +1926,19 @@ Refer to <<remote-clusters>>.
 [role="exclude",id="remote-clusters-privileges"]
 === Configure roles and users for remote clusters
 
-Refer to <<remote-clusters>>.
+Refer to <<remote-clusters>>.
+
+[role="exclude",id="put-geoip-database-api"]
+=== Create or update geoip database configuration API
+
+Refer to <<put-ip-location-database-api>>.
+
+[role="exclude",id="get-geoip-database-api"]
+=== Get geoip database configuration
+
+Refer to <<get-ip-location-database-api>>.
+
+[role="exclude",id="delete-geoip-database-api"]
+=== Delete geoip database configuration API
+
+Refer to <<delete-ip-location-database-api>>.