Add docs for the conditional policy

CHANGELOG.md

@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `GC` module that implements a workaround to be able to define `__gc` on tables [PR #790](https://github.com/3scale/apicast/pull/790)
 - Policies can define `__gc` metamethod that gets called when they are garbage collected to do cleanup [PR #688](https://github.com/3scale/apicast/pull/688)
 - Keycloak Role Check policy [PR #773](https://github.com/3scale/apicast/pull/773)
-- Conditional policy. This policy includes a condition and a policy chain, and only executes the chain when the condition is true [PR #812](https://github.com/3scale/apicast/pull/812), [PR #814](https://github.com/3scale/apicast/pull/814)
+- Conditional policy. This policy includes a condition and a policy chain, and only executes the chain when the condition is true [PR #812](https://github.com/3scale/apicast/pull/812), [PR #814](https://github.com/3scale/apicast/pull/814), [PR #820](https://github.com/3scale/apicast/pull/820)
 - Request headers are now exposed in the context available when evaluating Liquid [PR #819](https://github.com/3scale/apicast/pull/819)
 
 ### Changed

gateway/src/apicast/policy/conditional/README.md

@@ -0,0 +1,139 @@
+# Conditional Policy
+
+- [**Description**](#description)
+- [**Conditions**](#conditions)
+- [**Example config**](#example-config)
+
+## Description
+
+The conditional policy is a bit different from the rest because it contains a
+chain of policies. It defines a condition that is evaluated on each nginx phase
+(access, rewrite, log, etc.). When that condition is true, the conditional
+policy runs that phase for each of the policies that it contains in its chain.
+
+Let's see an example:
+
+```
+APIcast --> Caching --> Conditional --> Upstream
+
+                             |
+                             v
+
+                          Headers
+
+                             |
+                             v
+
+                       URL Rewriting
+
+```
+
+Let's assume that the conditional policy defines the following condition: `the
+request method is POST`. In that case, when the request is a POST, the order of
+execution for each phase is:
+1) APIcast
+2) Caching
+3) Headers
+4) URL Rewriting
+5) Upstream
+
+When the request is not a POST, the order of execution for each phase is:
+1) APIcast
+2) Caching
+3) Upstream
+
+
+## Conditions
+
+The condition that determines whether to run the policies in the chain of the
+conditional policy can be expressed with JSON, and it uses liquid templating.
+This is an example that checks whether the request path is `/example_path`:
+
+```json
+{
+  "left": "{{ uri }}",
+  "left_type": "liquid",
+  "op": "==",
+  "right": "/example_path",
+  "right_type": "plain"
+}
+```
+
+Notice that both the left and right operands can be evaluated either as liquid or
+as plain strings. The latter is the default.
+
+We can combine operations with `and` or `or`. This config checks the same as
+the one above plus the value of the `Backend` header:
+
+```json
+{
+  "operations": [
+    {
+      "left": "{{ uri }}",
+      "left_type": "liquid",
+      "op": "==",
+      "right": "/example_path",
+      "right_type": "plain"
+    },
+    {
+      "left": "{{ headers['Backend'] }}",
+      "left_type": "liquid",
+      "op": "==",
+      "right": "test_upstream",
+      "right_type": "plain"
+    }
+  ],
+  "combine_op": "and"
+}
+```
+
+To know more about the details of what is exactly supported please check the
+[policy config schema](apicast-policy.json).
+
+These are the variables supported in liquid:
+* uri
+* host
+* remote_addr
+* headers['Some-Header']
+
+The updated list of variables can be found [here](../ngx_variable.lua)
+
+
+## Example config
+
+This is an example configuration. It executes the upstream policy only when
+the `Backend` header of the request is `staging`:
+
+```json
+{
+   "name":"conditional",
+   "version":"builtin",
+   "configuration":{
+      "condition":{
+         "operations":[
+            {
+               "left":"{{ headers['Backend'] }}",
+               "left_type":"liquid",
+               "op":"==",
+               "right":"staging"
+            }
+         ]
+      },
+      "policy_chain":[
+         {
+            "name":"upstream",
+            "version": "builtin",
+            "configuration":{
+               "rules":[
+                  {
+                     "regex":"/",
+                     "url":"http://my_staging_environment"
+                  }
+               ]
+            }
+         }
+      ]
+   }
+}
+
+```