Add configuration management topics to the Beats docs (elastic#9054)

* Add initial skeleton for Beats Central Management docs * Add security warning * Add enrollment command details * Edits and additions * Add fixes from review plus xpack role tags
dedemorton · Nov 13, 2018 · 71bc7bd · 71bc7bd
1 parent 2df6560
commit 71bc7bd
Show file tree

Hide file tree

Showing 17 changed files with 188 additions and 0 deletions.
diff --git a/filebeat/docs/configuring-howto.asciidoc b/filebeat/docs/configuring-howto.asciidoc
@@ -37,6 +37,7 @@ The following topics describe how to configure Filebeat:
 * <<configuration-logging>>
 * <<using-environ-vars>>
 * <<configuration-autodiscover>>
+//* <<configuration-central-management>>
 * <<yaml-tips>>
 * <<regexp-support>>
 * <<http-endpoint>>

diff --git a/filebeat/docs/images/configuration-blocks.png b/filebeat/docs/images/configuration-blocks.png
diff --git a/filebeat/docs/images/enrolled-beats-apache.png b/filebeat/docs/images/enrolled-beats-apache.png
diff --git a/filebeat/docs/images/enrolled-beats-dev-prod.png b/filebeat/docs/images/enrolled-beats-dev-prod.png
diff --git a/filebeat/docs/images/enrolled-beats.png b/filebeat/docs/images/enrolled-beats.png
diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc
@@ -36,6 +36,8 @@ include::./how-filebeat-works.asciidoc[]
 
 include::./configuring-howto.asciidoc[]
 
+include::../../libbeat/docs/shared-central-management.asciidoc[]
+
 include::./modules.asciidoc[]
 
 include::./fields.asciidoc[]

diff --git a/libbeat/docs/images/configuration-blocks.png b/libbeat/docs/images/configuration-blocks.png
diff --git a/libbeat/docs/images/enrolled-beats-apache.png b/libbeat/docs/images/enrolled-beats-apache.png
diff --git a/libbeat/docs/images/enrolled-beats-dev-prod.png b/libbeat/docs/images/enrolled-beats-dev-prod.png
diff --git a/libbeat/docs/images/enrolled-beats.png b/libbeat/docs/images/enrolled-beats.png
diff --git a/libbeat/docs/shared-beats-attributes.asciidoc b/libbeat/docs/shared-beats-attributes.asciidoc
@@ -19,6 +19,7 @@
 :ES-version: {stack-version}
 :LS-version: {stack-version}
 :Kibana-version: {stack-version}
+:cm-ui: Central Management
 :beat_monitoring_user: beats_system
 :beat_monitoring_user_version: 6.3.0
 :beat_monitoring_version: 6.2
diff --git a/libbeat/docs/shared-central-management.asciidoc b/libbeat/docs/shared-central-management.asciidoc
@@ -0,0 +1,182 @@
+[[configuration-central-management]]
+[role="xpack"]
+= {beats} central management
+
+++++
+<titleabbrev>Central management</titleabbrev>
+++++
+
+[partintro]
+--
+
+beta[]
+
+[WARNING]
+=======================================
+When you use central management, configurations are stored centrally in {es}. To
+prevent an attacker from leveraging the configurations to attack your
+infrastructure, you must {stack-ov}/elasticsearch-security.html[secure {es} and
+{kib}] before using central management.
+=======================================
+
+{beats} central management provides a way to define and manage configurations in
+a central location in {kib} and quickly deploy configuration changes to all
+{beats} running across your enterprise. 
+
+To learn more, see <<how-central-managment-works>>.
+
+To use central management, <<enroll-beats,enroll your {beats}>>, then use
+the {cm-ui} UI in {kib} to create and apply the configurations.
+
+--
+
+[[how-central-managment-works]]
+[role="xpack"]
+== How central management works
+
+{beats} central management uses a mechanism called configuration tags to group
+related configurations. You define configuration tags in the {cm-ui} UI in {kib}
+after <<enroll-beats,enrolling your first beat.>>
+
+A _configuration tag_ is a group of configuration blocks that you can apply to
+one or more {beats}. A tag can have configuration blocks for different types of
+{beats}. For example, you might have a tag called `development` that you use to
+group all configurations that are valid for running {beats} in your development
+environment. The `development` tag might have:
+
+* Two Metricbeat module configuration blocks: one that reads system metrics and
+another that reads metrics from Apache HTTP servers
+* Two Filebeat module configuration blocks: one that reads Apache HTTP server
+logs and another that reads system logs
+* One Elasticsearch output configuration block that sends the output to your
+{es} development cluster
+
+[role="screenshot"]
+image::./images/configuration-blocks.png[Screen showing configuration blocks in a tag]
+
+You apply the tag to any {beats} that will use the configurations defined in the
+tag.
+
+[role="screenshot"]
+image::./images/enrolled-beats.png[Screen showing {beats} with tags applied]
+
+When the enrolled {beats} run, each Beat uses the configuration blocks that are
+valid for its type.
+
+You can add, modify, or remove configuration blocks from a tag. Any changes that
+you make to the configuration blocks in a tag are automatically applied to all
+{beats} that have that tag.
+
+You can add or remove tags to change the set of configuration blocks applied to
+your {beats}. For example, after you've tested configurations in your
+`development` environment, you can remove the `development` tag and add a
+`production` tag that has an {es} output configuration block for sending the
+data to your production cluster.
+
+[role="screenshot"]
+image::./images/enrolled-beats-dev-prod.png[Screen showing {beats} with development and production tags applied]
+
+You can apply multiple tags to a Beat. For example, instead of defining the
+apache modules under the `development` tag as described earlier, you could
+create a separate tag called `apache` that contains the Apache module
+configurations, then apply the tag to all {beats} running on Apache servers.
+This would enable you to maintain your Apache module configurations under a
+single tag, while also using a `development` tag to send output for some
+instances to your development cluster. 
+
+[role="screenshot"]
+image::./images/enrolled-beats-apache.png[Screen showing {beats} with multiple tags]
+
+You can apply as many tags as you need. Just keep in mind that the
+configurations for all assigned tags are merged, which means that you should not
+specify conflicting configurations. If there are errors in the configuration,
+you'll see an Error status in the {cm-ui} UI and need to look at the logs for
+the Beat to troubleshoot the problem. 
+
+[[enroll-beats]]
+[role="xpack"]
+== Enroll {beats} in central management
+
+You need to enroll {beats} to register them in
+<<configuration-central-management,central management>> and establish
+trust. Enrolled {beats} will have the credentials needed to retrieve
+configurations from {kib}.
+
+During the enrollment process:
+
+ . The Beat contacts {kib} and tries to register
+ . {kib} registers the Beat instance and returns an access token
+ for configuration polling
+ . The enroll command creates a backup of your configuration and then
+ **overwrites the current settings** so they can be managed centrally
+
+To enroll {beats}, use either <<token-based-enrollment,token-based>>
+or <<username-password-enrollment,username and password-based>> enrollment.
+
+
+[float]
+=== Prerequisites
+
+* {kibana-ref}/using-kibana-with-security.html[Enable security] in {kib} to
+ensure that only users with sufficient privileges are able to access {beats}
+configurations. 
+* Assign the `beats_admin` role to any users who need to enroll {beats} or
+manage configuration settings in central management.
+
+[float]
+[[token-based-enrollment]]
+=== Token-based enrollment
+
+Token-based enrollment is recommended if you are enrolling {beats} manually.
+
+To use token-based enrollment, go to {kib} -> Management -> {beats} and click
+`Enroll Beat`. Select the Beat type and operating system, then copy and run the
+command for enrolling the Beat.
+
+The command has this format:
+
+["source","shell",subs="attributes"]
+----------------------------------------------------------------------
+{beatname_lc} enroll KIBANA_URL TOKEN
+----------------------------------------------------------------------
+
+*`KIBANA_URL`*::
+The URL of the {kib} instance you will use for central management.
+
+*`TOKEN`*::
+The enrollment token generated by the {cm-ui} UI. The enrollment token will
+expire as soon as it's used.
+
+Repeat this process to enroll additional {beats}.
+
+[float]
+[[username-password-enrollment]]
+=== Username and password-based enrollment
+
+You can also enroll by specifying a username and password. This is the
+recommended way for scripted deploys:
+
+["source","shell",subs="attributes"]
+----------------------------------------------------------------------
+{beatname_lc} enroll KIBANA_URL --username USER --password METHOD [--force]
+----------------------------------------------------------------------
+
+*`--username USER`*::
+The username to use for password-based enrollment. The default
+username is `elastic`.
+
+*`--password METHOD`*::
+The method to use for getting the password. Available options are:
+
+ * `env:VAR_NAME` gets the password from the environment variable `VAR_NAME`
+ * `stdin` prompts the user for a password. This is the default.
+
+*`--force`*::
+Overwrites the current settings without asking for confirmation.
+
+
+//[[central-management-API]]
+//== Enrollment API (not documented for beta)
+//
+//available.
+
diff --git a/metricbeat/docs/images/configuration-blocks.png b/metricbeat/docs/images/configuration-blocks.png
diff --git a/metricbeat/docs/images/enrolled-beats-apache.png b/metricbeat/docs/images/enrolled-beats-apache.png
diff --git a/metricbeat/docs/images/enrolled-beats-dev-prod.png b/metricbeat/docs/images/enrolled-beats-dev-prod.png
diff --git a/metricbeat/docs/images/enrolled-beats.png b/metricbeat/docs/images/enrolled-beats.png
diff --git a/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc
@@ -34,6 +34,8 @@ include::./how-metricbeat-works.asciidoc[]
 
 include::./configuring-howto.asciidoc[]
 
+include::../../libbeat/docs/shared-central-management.asciidoc[]
+
 include::./modules.asciidoc[]
 
 include::./fields.asciidoc[]