diff --git a/docs/api.asciidoc b/docs/api.asciidoc index cc89999d5e6a7..dc3aa6be4fbd0 100644 --- a/docs/api.asciidoc +++ b/docs/api.asciidoc @@ -28,6 +28,9 @@ entirely. == APIs * <> +* <> -- -include::api/saved-objects.asciidoc[] \ No newline at end of file +include::api/saved-objects.asciidoc[] +include::api/logstash-configuration-management.asciidoc[] + diff --git a/docs/api/logstash-configuration-management.asciidoc b/docs/api/logstash-configuration-management.asciidoc new file mode 100644 index 0000000000000..d788cfb29d711 --- /dev/null +++ b/docs/api/logstash-configuration-management.asciidoc @@ -0,0 +1,20 @@ +[role="xpack"] +[[logstash-configuration-management-api]] +== Logstash Configuration Management API + +The Logstash configuration management API allows users to programmatically integrate with the +Logstash configuration management feature. + +Traditionally users would perform this integration by accessing the the `.logstash` index +directly. *Do not do this!* The structure of this index is subject to change, which could +cause your integration to break. Instead, use the following API. + +* <> +* <> +* <> +* <> + +include::logstash-configuration-management/create.asciidoc[] +include::logstash-configuration-management/retrieve.asciidoc[] +include::logstash-configuration-management/delete.asciidoc[] +include::logstash-configuration-management/list.asciidoc[] \ No newline at end of file diff --git a/docs/api/logstash-configuration-management/create.asciidoc b/docs/api/logstash-configuration-management/create.asciidoc new file mode 100644 index 0000000000000..e3f8a6260d80a --- /dev/null +++ b/docs/api/logstash-configuration-management/create.asciidoc @@ -0,0 +1,50 @@ +[role="xpack"] +[[logstash-configuration-management-api-create]] +=== Create Pipeline + +experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] + +The Create Pipeline API enables you to create a centrally-managed Logstash pipeline. You can also use +it to update an existing pipeline. + +[float] +==== Request + +`PUT /api/logstash/pipeline/` + +[float] +==== Path Parameters + +`id` (required):: + (string) ID for pipeline. Only alphanumeric characters, hyphens, and underscores may be used. + + +[float] +==== Request Body + +`description` (optional):: + (string) Description for the pipeline + +`pipeline` (required):: + (string) Pipeline definition + +`settings` (optional):: + (object) Pipeline settings. Supported settings, represented as object keys, are `pipeline.workers`, `pipeline.batch.size`, `pipeline.batch.delay`, `queue.type`, `queue.max_bytes`, and `queue.checkpoint.writes` + + +[float] +==== Examples + +[source,js] +-------------------------------------------------- +PUT api/logstash/pipeline/hello-world +{ + "pipeline": "input { stdin {} } output { stdout {} }", + "settings": { + "queue.type": "persistent" + } +} +-------------------------------------------------- +// KIBANA + +A successful call returns an HTTP `204 No Content` response. diff --git a/docs/api/logstash-configuration-management/delete.asciidoc b/docs/api/logstash-configuration-management/delete.asciidoc new file mode 100644 index 0000000000000..e286440f9075f --- /dev/null +++ b/docs/api/logstash-configuration-management/delete.asciidoc @@ -0,0 +1,30 @@ +[role="xpack"] +[[logstash-configuration-management-api-delete]] +=== Delete Pipeline + +experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] + +The Delete Pipeline API enables you to delete a centrally-managed Logstash pipeline. + +[float] +==== Request + +`DELETE /api/logstash/pipeline/` + +[float] +==== Path Parameters + +`id` (required):: + (string) ID for pipeline. + + +[float] +==== Examples + +[source,js] +-------------------------------------------------- +DELETE api/logstash/pipeline/hello-world +-------------------------------------------------- +// KIBANA + +A successful call returns an HTTP `204 No Content` response. \ No newline at end of file diff --git a/docs/api/logstash-configuration-management/list.asciidoc b/docs/api/logstash-configuration-management/list.asciidoc new file mode 100644 index 0000000000000..3f60ab240ed20 --- /dev/null +++ b/docs/api/logstash-configuration-management/list.asciidoc @@ -0,0 +1,44 @@ +[role="xpack"] +[[logstash-configuration-management-api-list]] +=== List Pipelines + +experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] + +The List Pipelines API enables you to list all centrally-managed Logstash pipelines. + +[float] +==== Request + +`GET /api/logstash/pipelines` + +[float] +==== Examples + +[source,js] +-------------------------------------------------- +GET api/logstash/pipelines +-------------------------------------------------- +// KIBANA + +A successful call returns a JSON structure similar to the following example: + +[source,js] +-------------------------------------------------- +{ + "pipelines": [ + { + "id": "hello-world", + "description": "Just a simple pipeline", + "last_modified": "2018-04-14T12:23:29.772Z", + "username": "elastic" <1> + }, + { + "id": "sleepy-pipeline", + "description": "", + "last_modified": "2018-03-24T03:41:30.554Z" + } + ] +} +-------------------------------------------------- + +<1> The username property may or may not be present, depending on whether Elastic Security was enabled when the pipeline was created or last updated. \ No newline at end of file diff --git a/docs/api/logstash-configuration-management/retrieve.asciidoc b/docs/api/logstash-configuration-management/retrieve.asciidoc new file mode 100644 index 0000000000000..894d8f7947d1f --- /dev/null +++ b/docs/api/logstash-configuration-management/retrieve.asciidoc @@ -0,0 +1,42 @@ +[role="xpack"] +[[logstash-configuration-management-api-retrieve]] +=== Retrieve Pipeline + +experimental[This functionality is *experimental* and may be changed or removed completely in a future release.] + +The Retrieve Pipeline API enables you to retrieve a centrally-managed Logstash pipeline. + +[float] +==== Request + +`GET /api/logstash/pipeline/` + +[float] +==== Path Parameters + +`id` (required):: + (string) ID for pipeline. + +[float] +==== Examples + +[source,js] +-------------------------------------------------- +GET api/logstash/pipeline/hello-world +-------------------------------------------------- +// KIBANA + +A successful call returns a JSON structure similar to the following example: + +[source,js] +-------------------------------------------------- +{ + "id": "hello-world", + "description": "Just a simple pipeline", + "username": "elastic", + "pipeline": "input { stdin {} } output { stdout {} }", + "settings": { + "queue.type": "persistent" + } +} +--------------------------------------------------