Doc - Fix Active-Failover limitations (arangodb#6353)

graetzer · jsteemann · commit d64af1f3d32e · 2018-09-20T13:22:44.000+02:00
diff --git a/Documentation/Books/Manual/Architecture/DeploymentModes/ActiveFailover/Architecture.md b/Documentation/Books/Manual/Architecture/DeploymentModes/ActiveFailover/Architecture.md
@@ -45,12 +45,20 @@ When the _Leader_ goes down, this is automatically detected by the _Agency_
 instance, which is also started in this mode. This instance will make the
 previous follower stop its replication and make it the new _Leader_.
 
-The _Follower_ will deny all read and write requests from client applications.
+Operative Behaviour
+-------------------
+
+In contrast to the normal behaviour of a single-server instance, the Active-Failover
+mode will change the behaviour of ArangoDB in some situations.
+
+The _Follower_ will _always_ deny write requests from client applications.  Starting from ArangoDB 3.4
+read requests are _only_ permitted if the requests is marked with the `X-Arango-Allow-Dirty-Read` header,
+otherwise they are denied too.
 Only the replication itself is allowed to access the follower's data until the
 follower becomes a new _Leader_ (should a _failover_ happen).
 
 When sending a request to read or write data on a _Follower_, the _Follower_ will
-always respond with `HTTP 503 (Service unavailable)` and provide the address of
+respond with `HTTP 503 (Service unavailable)` and provide the address of
 the current _Leader_. Client applications and drivers can use this information to
 then make a follow-up request to the proper _Leader_:
 
@@ -64,6 +72,18 @@ Client applications can also detect who the current _Leader_ and the _Followers_
 are by calling the `/_api/cluster/endpoints` REST API. This API is accessible
 on _Leader_ and _Followers_ alike.
 
+Reading from Followers
+----------------------
+
+Followers in the active-failover setup are in a read-only mode. It is possible to read from these
+followers by adding a `X-Arango-Allow-Dirty-Read` header on each request. Responses will then automatically
+contain the `X-Arango-Potential-Dirty-Read` header so that clients can reject accidental dirty reads.
+
+Depending on the driver support for your specific programming language, you should be able to enable this option.
+
+Tooling Support
+---------------
+
 The tool _ArangoDB Starter_ supports starting two servers with asynchronous
 replication and failover [out of the box](../../../Deployment/ActiveFailover/UsingTheStarter.md).
 
diff --git a/Documentation/Books/Manual/Architecture/DeploymentModes/ActiveFailover/Limitations.md b/Documentation/Books/Manual/Architecture/DeploymentModes/ActiveFailover/Limitations.md
@@ -4,8 +4,11 @@ Active Failover Limitations
 The _Active Failover_ setup in ArangoDB has a few limitations. Some of these limitations 
 may be removed in later versions of ArangoDB:
 
-- Even though it is already possible to have several _followers_ of the same _leader_,
- currently only one _follower_ is officially supported
 - Should you add more than one _follower_, be aware that during a _failover_ situation
- the failover attempts to pick the most up to date follower as a new leader, 
- but there is **no guarantee** on how much operations may have been lost.
+ the failover attempts to pick the most up to date follower as the new leader on a **best-effort** basis. 
+- In contrast to full ArangoDB Cluster (with synchronous replication), there is **no guarantee** on 
+  how many database operations may have been lost during a failover.
+- Should you be using the [ArangoDB Starter](../../../Programs/Starter/README.md) 
+  or the [Kubernetes Operator](../../../Deployment/Kubernetes/README.md) to manage your Active-Failover
+  deployment, be aware that upgrading might trigger an unintentional failover between machines.
+
