From 74c5540d4ff096591294aff8591401b750c07fd2 Mon Sep 17 00:00:00 2001 From: Jay Modi Date: Thu, 28 Jan 2021 10:50:16 -0700 Subject: [PATCH] Logstash Pipeline REST api spec and documentation (#67788) This commit adds REST api specifications for the Logstash Pipeline APIs and documentation of the APIs. Closes #67360 --- docs/reference/rest-api/index.asciidoc | 2 + .../logstash/delete-pipeline.asciidoc | 71 ++++++++++++++ .../rest-api/logstash/get-pipeline.asciidoc | 98 +++++++++++++++++++ .../docs/en/rest-api/logstash/index.asciidoc | 14 +++ .../rest-api/logstash/put-pipeline.asciidoc | 61 ++++++++++++ .../api/logstash.delete_pipeline.json | 28 ++++++ .../api/logstash.get_pipeline.json | 28 ++++++ .../api/logstash.put_pipeline.json | 34 +++++++ 8 files changed, 336 insertions(+) create mode 100644 x-pack/docs/en/rest-api/logstash/delete-pipeline.asciidoc create mode 100644 x-pack/docs/en/rest-api/logstash/get-pipeline.asciidoc create mode 100644 x-pack/docs/en/rest-api/logstash/index.asciidoc create mode 100644 x-pack/docs/en/rest-api/logstash/put-pipeline.asciidoc create mode 100644 x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.delete_pipeline.json create mode 100644 x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.get_pipeline.json create mode 100644 x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.put_pipeline.json diff --git a/docs/reference/rest-api/index.asciidoc b/docs/reference/rest-api/index.asciidoc index 8d894e05a9a56..f281cdddf9674 100644 --- a/docs/reference/rest-api/index.asciidoc +++ b/docs/reference/rest-api/index.asciidoc @@ -25,6 +25,7 @@ not be included yet. * <> * <> * <> +* <> * <> * <> * <> @@ -56,6 +57,7 @@ include::{es-repo-dir}/ilm/apis/ilm-api.asciidoc[] include::{es-repo-dir}/ingest/apis/index.asciidoc[] include::info.asciidoc[] include::{es-repo-dir}/licensing/index.asciidoc[] +include::{xes-repo-dir}/rest-api/logstash/index.asciidoc[] include::{es-repo-dir}/ml/anomaly-detection/apis/index.asciidoc[] include::{es-repo-dir}/ml/df-analytics/apis/index.asciidoc[] include::{es-repo-dir}/migration/migration.asciidoc[] diff --git a/x-pack/docs/en/rest-api/logstash/delete-pipeline.asciidoc b/x-pack/docs/en/rest-api/logstash/delete-pipeline.asciidoc new file mode 100644 index 0000000000000..fbd9724546dec --- /dev/null +++ b/x-pack/docs/en/rest-api/logstash/delete-pipeline.asciidoc @@ -0,0 +1,71 @@ +[role="xpack"] +[testenv="basic"] +[[logstash-api-delete-pipeline]] +=== Delete Pipeline API + +This API deletes Pipelines used for Logstash Central Management. + +[[logstash-api-delete-pipeline-request]] +==== {api-request-title} + +`DELETE _logstash/pipeline/` + +[[logstash-api-delete-pipeline-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, you must have the +`manage_logstash_pipelines` cluster privilege to use this API. + +[[logstash-api-delete-pipeline-desc]] +==== {api-description-title} + +Delete a Logstash Pipelines. + +[[logstash-api-delete-pipeline-params]] +==== {api-path-parms-title} + +``:: + (Required, string) Identifier for the Pipeline. + +[[logstash-api-delete-pipeline-example]] +==== {api-examples-title} + +The following example deletes the Pipeline named `my_pipeline`: + +////////////////////////// + +[source,console] +-------------------------------------------------- +PUT _logstash/pipeline/my_pipeline +{ + "description": "Sample Pipeline for illustration purposes", + "last_modified": "2021-01-02T02:50:51.250Z", + "pipeline_metadata": { + "type": "logstash_pipeline", + "version": "1" + }, + "username": "elastic", + "pipeline": "input {}\n filter { grok {} }\n output {}", + "pipeline_settings": { + "pipeline.workers": 1, + "pipeline.batch.size": 125, + "pipeline.batch.delay": 50, + "queue.type": "memory", + "queue.max_bytes.number": 1, + "queue.max_bytes.units": "gb", + "queue.checkpoint.writes": 1024 + } +} +-------------------------------------------------- + +////////////////////////// + +[source,console] +-------------------------------------------------- +DELETE _logstash/pipeline/my_pipeline +-------------------------------------------------- +// TEST[continued] + + +If the request succeeds, you receive an empty response with an appropriate +status code. diff --git a/x-pack/docs/en/rest-api/logstash/get-pipeline.asciidoc b/x-pack/docs/en/rest-api/logstash/get-pipeline.asciidoc new file mode 100644 index 0000000000000..063f6b40f9e5f --- /dev/null +++ b/x-pack/docs/en/rest-api/logstash/get-pipeline.asciidoc @@ -0,0 +1,98 @@ +[role="xpack"] +[testenv="basic"] +[[logstash-api-get-pipeline]] +=== Get Pipeline API + +This API retrieves Pipelines used for Logstash Central Management. + +[[logstash-api-get-pipeline-request]] +==== {api-request-title} + +`GET _logstash/pipeline` + +`GET _logstash/pipeline/` + +[[logstash-api-get-pipeline-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, you must have the +`manage_logstash_pipelines` cluster privilege to use this API. + +[[logstash-api-get-pipeline-desc]] +==== {api-description-title} + +Retrieve one or more Logstash Pipelines. + +[[logstash-api-get-pipeline-params]] +==== {api-path-parms-title} + +``:: + (Optional, string) Comma-separated list of Pipeline identifiers. + +[[logstash-api-get-pipeline-example]] +==== {api-examples-title} + +The following example retrieves the Pipeline named `my_pipeline`: + +////////////////////////// + +[source,console] +-------------------------------------------------- +PUT _logstash/pipeline/my_pipeline +{ + "description": "Sample Pipeline for illustration purposes", + "last_modified": "2021-01-02T02:50:51.250Z", + "pipeline_metadata": { + "type": "logstash_pipeline", + "version": "1" + }, + "username": "elastic", + "pipeline": "input {}\n filter { grok {} }\n output {}", + "pipeline_settings": { + "pipeline.workers": 1, + "pipeline.batch.size": 125, + "pipeline.batch.delay": 50, + "queue.type": "memory", + "queue.max_bytes.number": 1, + "queue.max_bytes.units": "gb", + "queue.checkpoint.writes": 1024 + } +} +-------------------------------------------------- + +////////////////////////// + +[source,console] +-------------------------------------------------- +GET _logstash/pipeline/my_pipeline +-------------------------------------------------- +// TEST[continued] + + +If the request succeeds, the body of the response contains the Pipeline definition: + +[source,console-result] +-------------------------------------------------- +{ + "my_pipeline": { + "description": "Sample Pipeline for illustration purposes", + "last_modified": "2021-01-02T02:50:51.250Z", + "pipeline_metadata": { + "type": "logstash_pipeline", + "version": "1" + }, + "username": "elastic", + "pipeline": "input {}\n filter { grok {} }\n output {}", + "pipeline_settings": { + "pipeline.workers": 1, + "pipeline.batch.size": 125, + "pipeline.batch.delay": 50, + "queue.type": "memory", + "queue.max_bytes.number": 1, + "queue.max_bytes.units": "gb", + "queue.checkpoint.writes": 1024 + } + } +} +-------------------------------------------------- +// TESTRESPONSE diff --git a/x-pack/docs/en/rest-api/logstash/index.asciidoc b/x-pack/docs/en/rest-api/logstash/index.asciidoc new file mode 100644 index 0000000000000..224092c3fa625 --- /dev/null +++ b/x-pack/docs/en/rest-api/logstash/index.asciidoc @@ -0,0 +1,14 @@ +[role="xpack"] +[[logstash-apis]] +== Logstash APIs + +The following APIs are used to manage Pipelines used by Logstash Central +Management: + +* <> +* <> +* <> + +include::delete-pipeline.asciidoc[] +include::get-pipeline.asciidoc[] +include::put-pipeline.asciidoc[] diff --git a/x-pack/docs/en/rest-api/logstash/put-pipeline.asciidoc b/x-pack/docs/en/rest-api/logstash/put-pipeline.asciidoc new file mode 100644 index 0000000000000..908367b1d20bb --- /dev/null +++ b/x-pack/docs/en/rest-api/logstash/put-pipeline.asciidoc @@ -0,0 +1,61 @@ +[role="xpack"] +[testenv="basic"] +[[logstash-api-put-pipeline]] +=== Put Pipeline API + +This API creates or updates Pipelines used for Logstash Central Management. + +[[logstash-api-put-pipeline-request]] +==== {api-request-title} + +`PUT _logstash/pipeline/` + +[[logstash-api-put-pipeline-prereqs]] +==== {api-prereq-title} + +* If the {es} {security-features} are enabled, you must have the +`manage_logstash_pipelines` cluster privilege to use this API. + +[[logstash-api-put-pipeline-desc]] +==== {api-description-title} + +Creates a Logstash Pipeline. If the specified Pipeline exists, the pipeline is +replaced. + +[[logstash-api-put-pipeline-params]] +==== {api-path-parms-title} + +``:: + (Required, string) Identifier for the Pipeline. + +[[logstash-api-put-pipeline-example]] +==== {api-examples-title} + +The following example creates a new Pipeline named `my_pipeline`: + +[source,console] +-------------------------------------------------- +PUT _logstash/pipeline/my_pipeline +{ + "description": "Sample Pipeline for illustration purposes", + "last_modified": "2021-01-02T02:50:51.250Z", + "pipeline_metadata": { + "type": "logstash_pipeline", + "version": "1" + }, + "username": "elastic", + "pipeline": "input {}\n filter { grok {} }\n output {}", + "pipeline_settings": { + "pipeline.workers": 1, + "pipeline.batch.size": 125, + "pipeline.batch.delay": 50, + "queue.type": "memory", + "queue.max_bytes.number": 1, + "queue.max_bytes.units": "gb", + "queue.checkpoint.writes": 1024 + } +} +-------------------------------------------------- + +If the request succeeds, you receive an empty response with an appropriate +status code. diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.delete_pipeline.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.delete_pipeline.json new file mode 100644 index 0000000000000..8650f5f7cac3c --- /dev/null +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.delete_pipeline.json @@ -0,0 +1,28 @@ +{ + "logstash.delete_pipeline":{ + "documentation":{ + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-delete-pipeline.html", + "description":"Deletes Logstash Pipelines used by Central Management" + }, + "stability":"stable", + "visibility":"public", + "headers":{ + "accept": [ "application/json"] + }, + "url":{ + "paths":[ + { + "path":"/_logstash/pipeline/{id}", + "methods":[ "DELETE" ], + "parts":{ + "id":{ + "type":"string", + "description":"The ID of the Pipeline" + } + } + } + ] + }, + "params":{} + } +} diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.get_pipeline.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.get_pipeline.json new file mode 100644 index 0000000000000..061e49e0290b9 --- /dev/null +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.get_pipeline.json @@ -0,0 +1,28 @@ +{ + "logstash.get_pipeline":{ + "documentation":{ + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-get-pipeline.html", + "description":"Retrieves Logstash Pipelines used by Central Management" + }, + "stability":"stable", + "visibility":"public", + "headers":{ + "accept": [ "application/json"] + }, + "url":{ + "paths":[ + { + "path":"/_logstash/pipeline/{id}", + "methods":[ "GET" ], + "parts":{ + "id":{ + "type":"string", + "description":"A comma-separated list of Pipeline IDs" + } + } + } + ] + }, + "params":{} + } +} diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.put_pipeline.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.put_pipeline.json new file mode 100644 index 0000000000000..e8ec9b0d99178 --- /dev/null +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.put_pipeline.json @@ -0,0 +1,34 @@ +{ + "logstash.put_pipeline":{ + "documentation":{ + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/logstash-api-put-pipeline.html", + "description":"Adds and updates Logstash Pipelines used for Central Management" + }, + "stability":"stable", + "visibility":"public", + "headers":{ + "accept": [ "application/json"], + "content_type": ["application/json"] + }, + "url":{ + "paths":[ + { + "path":"/_logstash/pipeline/{id}", + "methods":[ "PUT" ], + "parts":{ + "id":{ + "type":"string", + "description":"The ID of the Pipeline" + } + } + } + ] + }, + "params":{ + }, + "body":{ + "description":"The Pipeline to add or update", + "required":true + } + } +}