-
Notifications
You must be signed in to change notification settings - Fork 24.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
- Loading branch information
Showing
8 changed files
with
336 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/<pipeline_id>` | ||
|
|
||
| [[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} | ||
|
|
||
| `<pipeline_id>`:: | ||
| (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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/<pipeline_id>` | ||
|
|
||
| [[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} | ||
|
|
||
| `<pipeline_id>`:: | ||
| (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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| [role="xpack"] | ||
| [[logstash-apis]] | ||
| == Logstash APIs | ||
|
|
||
| The following APIs are used to manage Pipelines used by Logstash Central | ||
| Management: | ||
|
|
||
| * <<logstash-api-put-pipeline>> | ||
| * <<logstash-api-get-pipeline>> | ||
| * <<logstash-api-delete-pipeline>> | ||
|
|
||
| include::delete-pipeline.asciidoc[] | ||
| include::get-pipeline.asciidoc[] | ||
| include::put-pipeline.asciidoc[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/<pipeline_id>` | ||
|
|
||
| [[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} | ||
|
|
||
| `<pipeline_id>`:: | ||
| (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. |
28 changes: 28 additions & 0 deletions
28
x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.delete_pipeline.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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":{} | ||
| } | ||
| } |
28 changes: 28 additions & 0 deletions
28
x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.get_pipeline.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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":{} | ||
| } | ||
| } |
34 changes: 34 additions & 0 deletions
34
x-pack/plugin/src/test/resources/rest-api-spec/api/logstash.put_pipeline.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } | ||
| } | ||
| } |