From f8faa08f9246ebec1a6373cf1d08cb0d2d7a032c Mon Sep 17 00:00:00 2001
From: Shuting Zhao <shutting06@gmail.com>
Date: Tue, 22 Sep 2020 18:28:21 -0700
Subject: [PATCH] update doc

---
 .../writing-policies-configmap-reference.md   | 65 +++++++++++++++----
 1 file changed, 54 insertions(+), 11 deletions(-)

diff --git a/documentation/writing-policies-configmap-reference.md b/documentation/writing-policies-configmap-reference.md
index fb6fea339e..b90245a085 100644
--- a/documentation/writing-policies-configmap-reference.md
+++ b/documentation/writing-policies-configmap-reference.md
@@ -10,41 +10,84 @@ The Configmap Reference allows the reference of configmap values inside kyverno
 
 To refer Configmap inside any Rule provide the context inside each rule defining the list of configmaps which will be referenced in that Rule.
 
-```
+````yaml
   rules:
-    - name: add-sidecar-pod
+    - name: example-configmap-lookup
       # added context to define the configmap information which will be referred 
       context:
       # unique name to identify configmap
-      - name: mycmapRef
+      - name: dictionary
         configMap: 
           # configmap name - name of the configmap which will be referred
           name: mycmap
           # configmap namepsace - namespace of the configmap which will be referred
-```
+          namespace: test
+````
 
 Referenced Configmap Definition
 
-```
+````yaml
 apiVersion: v1
 data:
-  env: production, sandbox, staging
+  env: production
 kind: ConfigMap
 metadata:
   name: mycmap
-```
+````
 
 # Referring Value
 
 The configmaps that are defined inside rule context can be referred using the unique name that is used to identify configmap inside context.
 
-We can refer it's value using a JMESPATH
+We can refer it's value using a JMESPATH `{{<name>.<data>.<key>}}`. 
 
-`{{<name>.<data>.<key>}}`
+For the above context we can refer it's value by `{{dictionary.data.env}}`, which will be substitued with `production` during policy application.
 
-So for the above context we can refer it's value using
+# Deal with Array of Values
 
-`{{mycmapRef.data.env}}`
+The substitute variable can be an array of values. It allows the JSON format when defining it in the configMap.
+
+For example, a list of allowed roles can be stored in configMap, and the kyverno policy can refer to this list to deny the disallowed request.
+
+Here is the allowed roles in configMap:
+````yaml
+apiVersion: v1
+data:
+  allowed-roles: "[\"cluster-admin\", \"cluster-operator\", \"tenant-admin\"]"
+kind: ConfigMap
+metadata:
+  name: roles-dictionary
+  namespace: test
+````
+
+
+This is a rule to deny the Deployment operation, if the value of annotation `role` is not in the allowed list:
+````yaml
+spec:
+  validationFailureAction: enforce
+  rules:
+  - name: validate-role-annotation
+    context:
+      - name: roles-dictionary
+        configMap: 
+          name: roles-dictionary
+          namespace: test
+    match:
+      resources:
+        kinds:
+        - Deployment
+    preconditions:
+    - key: "{{ request.object.metadata.annotations.role }}"
+      operator: NotEquals
+      value: ""
+    validate:
+      message: "role {{ request.object.metadata.annotations.role }} is not in the allowed list {{ \"roles-dictionary\".data.\"allowed-roles\" }}"
+      deny:
+        conditions: 
+        - key: "{{ request.object.metadata.annotations.role }}"
+          operator: NotIn
+          value:  "{{ \"roles-dictionary\".data.\"allowed-roles\" }}"
+````