Merge pull request #676 from michaelbaamonde/cluster-administration

Formatting fixes for the Cluster Administration chapter

Author: michaelbaamonde

500_Cluster_Admin/10_intro.asciidoc

@@ -1,15 +1,16 @@
 
-Elasticsearch is often deployed as a cluster of nodes.((("clusters", "administration")))  A variety of
-APIs let you manage and monitor the cluster itself, rather than interact
-with the data stored within the cluster.
+Elasticsearch is often deployed as a cluster of nodes. A variety of APIs let you
+manage and monitor the cluster itself, rather than interact with the data stored
+within the cluster.
 
 As with most functionality in Elasticsearch, there is an overarching design goal
 that tasks should be performed through an API rather than by modifying static
-configuration files.  This becomes especially important as your cluster scales.
-Even with a provisioning system (such as Puppet, Chef, and Ansible), a single HTTP API call
-is often simpler than pushing new configurations to hundreds of physical machines.
+configuration files. This becomes especially important as your cluster scales.
+Even with a provisioning system (such as Puppet, Chef, and Ansible), a single
+HTTP API call is often simpler than pushing new configurations to hundreds of
+physical machines.
 
 To that end, this chapter presents the various APIs that allow you to
-dynamically tweak, tune, and configure your cluster.  It also covers a
-host of APIs that provide statistics about the cluster itself so you can
-monitor for health and performance.
+dynamically tweak, tune, and configure your cluster. It also covers a host of
+APIs that provide statistics about the cluster itself so you can monitor for
+health and performance.

500_Cluster_Admin/20_health.asciidoc

@@ -1,13 +1,14 @@
 
 === Cluster Health
 
-An Elasticsearch cluster may consist of a single node with a single index.  Or it((("cluster health")))((("clusters", "administration", "Cluster Health API")))
-may have a hundred data nodes, three dedicated masters, a few dozen client nodes--all operating on a thousand indices (and tens of thousands of shards).
+An Elasticsearch cluster may consist of a single node with a single index. Or it
+may have a hundred data nodes, three dedicated masters, a few dozen client
+nodes--all operating on a thousand indices (and tens of thousands of shards).
 
 No matter the scale of the cluster, you'll want a quick way to assess the status
-of your cluster.  The `Cluster Health` API fills that role.  You can think of it
-as a 10,000-foot view of your cluster.  It can reassure you that everything
-is all right, or alert you to a problem somewhere in your cluster.
+of your cluster. The `Cluster Health` API fills that role. You can think of it
+as a 10,000-foot view of your cluster. It can reassure you that everything is
+all right, or alert you to a problem somewhere in your cluster.
 
 Let's execute a `cluster-health` API and see what the response looks like:
 
@@ -45,7 +46,7 @@ operational.
 
 `yellow`::
     All primary shards are allocated, but at least one replica is missing.
-No data is missing, so search results will still be complete. However,  your 
+No data is missing, so search results will still be complete. However,  your
 high availability is compromised to some degree.  If _more_ shards disappear, you
 might lose data.  Think of `yellow` as a warning that should prompt investigation.
 
@@ -66,10 +67,10 @@ includes replica shards.
 one node to another node.  This number is often zero, but can increase when
 Elasticsearch decides a cluster is not properly balanced, a new node is added,
 or a node is taken down, for example.
-- `initializing_shards` is a count of shards that are being freshly created. For 
+- `initializing_shards` is a count of shards that are being freshly created. For
 example, when you first create an index, the shards will all briefly reside in
 `initializing` state.  This is typically a transient event, and shards shouldn't
-linger in `initializing` too long.  You may also see initializing shards when a 
+linger in `initializing` too long.  You may also see initializing shards when a
 node is first restarted: as shards are loaded from disk, they start as `initializing`.
 - `unassigned_shards` are shards that exist in the cluster state, but cannot be
 found in the cluster itself.  A common source of unassigned shards are unassigned
@@ -79,7 +80,7 @@ cluster is `red` (since primaries are missing).
 
 ==== Drilling Deeper: Finding Problematic Indices
 
-Imagine something goes wrong one day,((("indices", "problematic, finding"))) and you notice that your cluster health
+Imagine something goes wrong one day, and you notice that your cluster health
 looks like this:
 
 [source,js]
@@ -98,15 +99,15 @@ looks like this:
 }
 ----
 
-OK, so what can we deduce from this health status?  Well, our cluster is `red`,
-which means we are missing data (primary + replicas).  We know our cluster has
-10 nodes, but see only 8 data nodes listed in the health.  Two of our nodes
-have gone missing.  We see that there are 20 unassigned shards.  
+OK, so what can we deduce from this health status? Well, our cluster is `red`,
+which means we are missing data (primary + replicas). We know our cluster has 10
+nodes, but see only 8 data nodes listed in the health. Two of our nodes have
+gone missing. We see that there are 20 unassigned shards.
 
 That's about all the information we can glean.  The nature of those missing
 shards are still a mystery.  Are we missing 20 indices with 1 primary shard each?
 Or 1 index with 20 primary shards? Or 10 indices with 1 primary + 1 replica?
-Which index? 
+Which index?
 
 To answer these questions, we need to ask `cluster-health` for a little more
 information by using the `level` parameter:
@@ -183,40 +184,43 @@ The `level` parameter accepts one more option:
 GET _cluster/health?level=shards
 ----
 
-The `shards` option will provide a very verbose output, which lists the status 
+The `shards` option will provide a very verbose output, which lists the status
 and location of every shard inside every index.  This output is sometimes useful,
 but because of the verbosity can be difficult to work with.  Once you know the index
-that is having problems, other APIs that we discuss in this chapter will tend 
+that is having problems, other APIs that we discuss in this chapter will tend
 to be more helpful.
 
 ==== Blocking for Status Changes
 
 The `cluster-health` API has another neat trick that is useful when building
 unit and integration tests, or automated scripts that work with Elasticsearch.
-You can specify a `wait_for_status` parameter, which will only return after the status is satisfied.  For example:
+You can specify a `wait_for_status` parameter, which will only return after the
+status is satisfied. For example:
 
 [source,bash]
 ----
 GET _cluster/health?wait_for_status=green
 ----
 
-This call will _block_ (not return control to your program) until the `cluster-health` has turned `green`, meaning all primary and replica shards have been allocated.
-This is important for automated scripts and tests.
+This call will _block_ (not return control to your program) until the
+`cluster-health` has turned `green`, meaning all primary and replica shards have
+been allocated. This is important for automated scripts and tests.
 
 If you create an index, Elasticsearch must broadcast the change in cluster state
-to all nodes.  Those nodes must initialize those new shards, and then respond to the
-master that the shards are `Started`.  This process is fast, but because of network
-latency may take 10–20ms.
-
-If you have an automated script that (a) creates an index and then (b) immediately
-attempts to index a document, this operation may fail, because the index has not
-been fully initialized yet.  The time between (a) and (b) will likely be less than 1ms--not nearly enough time to account for network latency.
-
-Rather than sleeping, just have your script/test call `cluster-health` with
-a `wait_for_status` parameter.  As soon as the index is fully created, the `cluster-health` will change to `green`, the call will return control to your script, and you may
-begin indexing.
-
-Valid options are `green`, `yellow`, and `red`.  The call will return when the 
-requested status (or one "higher") is reached. For example, if you request `yellow`,
-a status change to `yellow` or `green` will unblock the call.
-
+to all nodes. Those nodes must initialize those new shards, and then respond to
+the master that the shards are `Started`. This process is fast, but because of
+network latency may take 10–20ms.
+
+If you have an automated script that (a) creates an index and then (b)
+immediately attempts to index a document, this operation may fail, because the
+index has not been fully initialized yet. The time between (a) and (b) will
+likely be less than 1ms--not nearly enough time to account for network latency.
+
+Rather than sleeping, just have your script/test call `cluster-health` with a
+`wait_for_status` parameter. As soon as the index is fully created, the
+`cluster-health` will change to `green`, the call will return control to your
+script, and you may begin indexing.
+
+Valid options are `green`, `yellow`, and `red`. The call will return when the
+requested status (or one "higher") is reached. For example, if you request
+`yellow`, a status change to `yellow` or `green` will unblock the call.