Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document privileges for ILM #10449

Merged
merged 1 commit into from
Feb 11, 2019
Merged

Document privileges for ILM #10449

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions libbeat/docs/security/basic-auth.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ POST _xpack/security/role/{beat_default_index_prefix}_writer
]
}
---------------------------------------------------------------
// CONSOLE
<1> If you use a custom {beatname_uc} index pattern, specify that pattern
instead of the default ++{beat_default_index_prefix}-*++ pattern.
endif::[]
Expand All @@ -65,6 +66,34 @@ instead of the default ++{beat_default_index_prefix}-*++ pattern.
endif::[]
--

ifndef::no_ilm[]
. If you plan to use {ref}/getting-started-index-lifecycle-management.html[index
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to rework these docs to explain that:

  1. ILM is on by default ("if you plan" sounds like it was opted into).
  2. That the additional privileges of manage_index_templates, manage_ilm, and manage are only required during the setup phase.

It seems that maybe we need to add a role here called {beatname_uc}_setup with only these roles, and tell people to add that role temporarily.

Would love feedback from @urso . Is the above all correct?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@andrewvc I will fix the confusion around ILM being on by default in 7.0. However, I think it would be better for you to add your thoughts to the discussion here: #10241.

Out of this discussion, I'd like to identify an authoritative list of the roles that we want users to either create (or use)...and I want that list to encompass all the features we offer.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, in the end it is up to the user to see if they want separate roles or users. ES has a builtin beats_system role and user, but this one is used for monitoring only. Users are not advised to reuse beats_system for more than monitoring.

I'd prefer not to document actual roles in the first place, but the different means how (and when) Beats interact with the Elastic Stack. Interactions roughly encompass:

  • setup
  • publish monitoring
  • publish events

At optimum these roles are separated and setup is executed only once and fully independent from actually running a Beat. If setup is not executed in isolation we need privileges for "publish events" and "setup" to be owned by the same user.

Depending on the Beat, setup can actually entail different tasks (well, to date only filebeat is the exception).
Setup tasks are:

  • Install template. Requires manage_index_templates (cluster)
  • (filebeat only) Install ingest node piplines. Requires manage_ingest_pipelines (cluster). I'm not sure about manage_pipeline (cluster).
  • Configure ILM policy. Requires manage_ilm (cluster)
  • (If ILM is enabled) Create initial index. Requires create_index (index), manage (index)
  • Create Kibana index mapping
  • Upload dashboards via Kibana API
  • (filebeat only) Enable ML modules via Kibana API

TBH. I'm not sure manage (cluster) is even required, but I never tried without.

Writer requires:

  • create_index (index) . If ILM is enabled create_index might not be required, but not sure if that is really the case.
  • write (index).
  • If ILM is enabled we still check if policy and alias is available (I never tried with security enabled, we have to test):
    • view_index_metadata (index)
    • read_ilm (cluster)

In the end this indeed calls for {beatname_uc}_setup, beats_system, and {beatname_uc}_write users + roles.

lifecycle management], create a role that has the following privileges. These
privileges are required to load index lifecycle policies and create and manage
rollover indices:
+
* *Cluster:* `manage_ilm`
* *Index:* `write`, `create_index`, `manage`, and `manage_ilm` on the
{beatname_uc} indices
+
--
["source","sh",subs="attributes"]
---------------------------------------------------------------
POST _xpack/security/role/{beatname_lc}_ilm
{
"cluster": ["manage_ilm"],
"indices": [
{
"names": [ "{beatname_lc}-*","shrink-{beatname_lc}-*"],
"privileges": ["write","create_index","manage","manage_ilm"]
}
]
}
---------------------------------------------------------------
// CONSOLE
--
endif::no_ilm[]

. Assign the writer role to the user that {beatname_uc} will use to connect to
{es}. Make sure you also assign any roles that are required for specific
features. For the list of features and required roles, see <<feature-roles>>.
Expand Down
26 changes: 15 additions & 11 deletions libbeat/docs/security/securing-beats.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,40 +44,44 @@ password, set it up now.
For more information about {security}, see
{xpack-ref}/elasticsearch-security.html[Securing the {stack}].

[float]
[[feature-roles]]
=== {beatname_uc} features that require authorization

After securing {beatname_uc}, make sure your users have the roles (or associated
privileges) required to use these {beatname_uc} features. You must create the
++{beat_default_index_prefix}_writer++ and
++{beat_default_index_prefix}_reader++ roles (see <<beats-basic-auth>> and
<<beats-user-access>>). The other roles are
{xpack-ref}/built-in-roles.html[built-in].
privileges) required to use these {beatname_uc} features. Note that some of the
roles shown here are {xpack-ref}/built-in-roles.html[built-in], and some
are user-defined.

[options="header"]
|=======
|Feature | Role
|Send data to a secured cluster | ++{beat_default_index_prefix}_writer++
|Send data to a secured cluster | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA,These roles are user-defined.]
ifeval::["{beatname_lc}"=="filebeat"]
|Run Filebeat modules | ++{beat_default_index_prefix}_writer++
|Run Filebeat modules | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA]
endif::[]
|Load index templates | ++{beat_default_index_prefix}_writer++ and `kibana_user`
|Load index templates | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA] and `kibana_user`
ifndef::no_dashboards[]
|Load {beatname_uc} dashboards into {kib} | ++{beat_default_index_prefix}_writer++ and `kibana_user`
|Load {beatname_uc} dashboards into {kib} | ++{beat_default_index_prefix}_writer++ footnoteref:[noteA] and `kibana_user`
endif::[]
ifdef::has_ml_jobs[]
|Load machine learning jobs | `machine_learning_admin`
endif::[]
|Read indices created by {beatname_uc} | ++{beat_default_index_prefix}_reader++
|Read indices created by {beatname_uc} | ++{beat_default_index_prefix}_reader++ footnoteref:[noteA]
ifndef::no_dashboards[]
|View {beatname_uc} dashboards in {kib} | `kibana_user`
endif::[]
ifdef::has_central_config[]
|Store and manage configurations in a central location in {kib} | `beats_admin`
endif::[]
ifndef::no_ilm[]
|Load index lifecycle policies and use index lifecycle management | +{beatname_lc}_ilm+ footnoteref:[noteA]
endif::[]
|=======

To create the user-defined roles shown here, see <<beats-basic-auth>> and
<<beats-user-access>>. You may want to define additional roles to provide more
restrictive access.

include::basic-auth.asciidoc[]

include::user-access.asciidoc[]
Expand Down