Updated documentation and adding more test case for async-cache

agent/consul/acl_test.go

@@ -589,6 +589,9 @@ func TestACL_DownPolicy_ExtendCache(t *testing.T) {
 
 func TestACL_Replication(t *testing.T) {
 	t.Parallel()
+	aclExtendPolicies := []string{"extend-cache", "async-cache"} //"async-cache"
+
+	for _, aclDownPolicy := range aclExtendPolicies {
 		dir1, s1 := testServerWithConfig(t, func(c *Config) {
 			c.ACLDatacenter = "dc1"
 			c.ACLMasterToken = "root"
@@ -602,7 +605,7 @@ func TestACL_Replication(t *testing.T) {
 			c.Datacenter = "dc2"
 			c.ACLDatacenter = "dc1"
 			c.ACLDefaultPolicy = "deny"
-		c.ACLDownPolicy = "extend-cache"
+			c.ACLDownPolicy = aclDownPolicy
 			c.EnableACLReplication = true
 			c.ACLReplicationInterval = 10 * time.Millisecond
 			c.ACLReplicationApplyLimit = 1000000
@@ -701,6 +704,7 @@ func TestACL_Replication(t *testing.T) {
 			t.Fatalf("unexpected read")
 		}
 	}
+}
 
 func TestACL_MultiDC_Found(t *testing.T) {
 	t.Parallel()

website/source/docs/agent/options.html.md

@@ -496,11 +496,13 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
   to enable ACL support.
 
 * <a name="acl_down_policy"></a><a href="#acl_down_policy">`acl_down_policy`</a> - Either
-  "allow", "deny" or "extend-cache"; "extend-cache" is the default. In the case that the
+  "allow", "deny", "extend-cache" or "async-cache"; "extend-cache" is the default. In the case that the
   policy for a token cannot be read from the [`acl_datacenter`](#acl_datacenter) or leader
   node, the down policy is applied. In "allow" mode, all actions are permitted, "deny" restricts
   all operations, and "extend-cache" allows any cached ACLs to be used, ignoring their TTL
-  values. If a non-cached ACL is used, "extend-cache" acts like "deny".
+  values. If a non-cached ACL is used, "extend-cache" acts like "deny". "async-cache" acts the same
+  way as "extend-cache" but performs updates asynchronously when ACL is present but its TTL is
+  expired.
 
 * <a name="acl_agent_master_token"></a><a href="#acl_agent_master_token">`acl_agent_master_token`</a> -
   Used to access <a href="/api/agent.html">agent endpoints</a> that require agent read

website/source/docs/guides/acl.html.md

@@ -1062,9 +1062,10 @@ is set to "extend-cache", tokens will be resolved during the outage using the
 replicated set of ACLs. An [ACL replication status](/api/acl.html#acl_replication_status)
 endpoint is available to monitor the health of the replication process.
 Also note that in recent versions of Consul (greater than 1.2.0), using
-`acl_down_policy = "extend-cache"` refreshes token asynchronously when an ACL is
+`acl_down_policy = "async-cache"` refreshes token asynchronously when an ACL is
-already cached and is expired. It allows to avoid having issues when connectivity with
+already cached and is expired while similar semantics than "extend-cache".
-the authoritative is not completely broken, but very slow.
+It allows to avoid having issues when connectivity with the authoritative is not completely
+broken, but very slow.
 
 Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/options.html#acl_ttl)
 setting of the non-authoritative datacenter, so these entries may persist in the