Add documentation for required privileges and unsupported processors. #72
Conversation
docs/index.asciidoc
Outdated
| [id="plugins-{type}s-{plugin}-unsupported_ingest_processors"] | ||
| ==== Unsupported Ingest Processors | ||
|
|
||
| Currently, following ingest processors are not supported due to limited {ls} ability to access {es} internal assets/processes. |
There was a problem hiding this comment.
As I have expressed with @roaksoax on tickets and in private chat, I strongly believe that we will be better off highlighting which integrations ARE supported by this plugin than attempting to provide an exhaustive list of which processors aren't included. A negative list will frequently become obsolete.
Even if we only look at Elasticsearch source for implementations of org.elasticsearch.ingest.IngestPlugin and org.elasticsearch.ingest.Processor, we find that we are already missing:
IngestAttachmentPluginprovidesattachmentprocessorIngestUserAgentPluginprovidesuser_agentprocessorRedactPluginprovidesredactprocessor (apparently extracted from IngestCommon since 8.8.0)SpatialPluginprovidescircleandgeo_gridprocessorsIngestCommonPluginprovidesrerouteprocessor in 8.8+, which we will need to work to add support for (see: Logstash Ingest Pipelines - support for "reroute" processor #67).
It also doesn't include user-installable first-party or third-party IngestPlugin implementations, none of which are included in this plugin.
Maintaining an exhaustive list of what processors we do NOT support is simply not practical.
There was a problem hiding this comment.
The most dangerous part is, we need to guess which integration uses which ingest pipeline and this may change time-by-time.
I went through the list of integrations and docs do not mention about ingest pipelines and processors.
Do you mean to split into PRs privilege and unsupported processors separately? If not, can you please clarify? |
Yes. I think we solve one easily and would prefer to merge the privilege docs while we continue to find an approach that makes it easy for users to form accurate expectations about the processors and integrations this plugin supports. |
Remove unsupported contents and update privileges content. Co-authored-by: Ry Biesemeyer <[email protected]>
docs/index.asciidoc
Outdated
|
|
||
| NOTE: When either connecting to an {es} cluster that has security features disabled or when not providing credentials, this plugin can not pre-verify that the anonymous user has the required privileges to use the necessary APIs. | ||
| In this case the plugin will start in an unsafe mode in which insufficient API permissions will be a runtime error that prevents events from being processed by their ingest pipeline. | ||
| Enabling security in {es} and using user authentication is recommended. |
There was a problem hiding this comment.
Checked locally, view is okay.
There was a problem hiding this comment.
@karenzone does this make sense to you?
Co-authored-by: Karen Metts <[email protected]>
There was a problem hiding this comment.
@mashhurs Your work in this PR looks good, and so I will approve it.
However, there are some pre-existing problems, and this doc as it is now will not pass docs-CI when it is hooked up. I opened #74 to track and resolve some doc issues that pre-date this PR.
Please go ahead and merge this PR when you get all of the approvals you need so that this content will be part of the baseline for the next round of cleanup and edits.
Description
Documentation doesn't mention about privileges the plugin requires but when Logstash runs with insufficient privileges, it raises an error. End users should have information about what privileges are required when running the plugin.