From 2d4e406a8649c7ad06845038a46236cc4ee3677a Mon Sep 17 00:00:00 2001
From: Alpha <AlphaWong@users.noreply.github.com>
Date: Tue, 20 Oct 2020 12:56:43 +0800
Subject: [PATCH 1/3] doc: add varReference example

---
 .../kustomization/vars/_index.md              | 30 ++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/site/content/en/api-reference/kustomization/vars/_index.md b/site/content/en/api-reference/kustomization/vars/_index.md
index 353518b51..d5e776f43 100644
--- a/site/content/en/api-reference/kustomization/vars/_index.md
+++ b/site/content/en/api-reference/kustomization/vars/_index.md
@@ -15,13 +15,17 @@ k8s Secret object in a container's environment variable,
 so that the following would work:
 
 ```yaml
-
+# consider it is a deployment
 containers:
   - image: myimage
     command: ["start", "--host", "$(MY_SERVICE_NAME)"]
     env:
     - name: SECRET_TOKEN
       value: $(SOME_SECRET_NAME)
+    livenessProbe:
+       httpGet:
+         path: /healthz
+         port: $(APP_PORT)
 ```
 
 To do so, add an entry to `vars:` as follows:
@@ -30,6 +34,11 @@ To do so, add an entry to `vars:` as follows:
 apiVersion: kustomize.config.k8s.io/v1beta1
 kind: Kustomization
 
+configMapGenerator:
+- name: my-config
+  literals:
+  - MY_PORT=8080
+
 vars:
 - name: SOME_SECRET_NAME
   objref:
@@ -50,6 +59,25 @@ vars:
     apiVersion: apps/v1
   fieldref:
     fieldpath: spec.template.spec.restartPolicy
+- name: APP_PORT
+  objref:
+    kind: ConfigMap
+    name: my-config
+    apiVersion: v1
+  fieldref:
+    fieldpath: data.MY_PORT
+    
+configurations:
+  - linkage.yaml
+```
+
+Define the linkage of the consuming resource(s) and the field(s) inside.
+
+```yaml
+# linkage.yaml
+varReference:
+  - path: spec/template/spec/containers/livenessProbe/httpGet/port
+    kind: Deployment
 ```
 
 A var is a tuple of variable name, object

From cf1aafb121c7a972e39aba379425f5547ac28b8c Mon Sep 17 00:00:00 2001
From: Alpha <AlphaWong@users.noreply.github.com>
Date: Tue, 20 Oct 2020 13:06:31 +0800
Subject: [PATCH 2/3] doc: add description for new user about `vars`

---
 site/content/en/api-reference/kustomization/vars/_index.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/site/content/en/api-reference/kustomization/vars/_index.md b/site/content/en/api-reference/kustomization/vars/_index.md
index d5e776f43..4cf74015c 100644
--- a/site/content/en/api-reference/kustomization/vars/_index.md
+++ b/site/content/en/api-reference/kustomization/vars/_index.md
@@ -25,6 +25,7 @@ containers:
     livenessProbe:
        httpGet:
          path: /healthz
+         # it enables the parser to lookup this field
          port: $(APP_PORT)
 ```
 
@@ -59,6 +60,9 @@ vars:
     apiVersion: apps/v1
   fieldref:
     fieldpath: spec.template.spec.restartPolicy
+# it exports a value as `APP_PORT` 
+# from `ConfigMap` named `my-config`
+# in `data.MY_PORT`
 - name: APP_PORT
   objref:
     kind: ConfigMap
@@ -76,6 +80,7 @@ Define the linkage of the consuming resource(s) and the field(s) inside.
 ```yaml
 # linkage.yaml
 varReference:
+  # the path of resource(s) that you want the parser to lookup
   - path: spec/template/spec/containers/livenessProbe/httpGet/port
     kind: Deployment
 ```

From 5d5b1c2c38fc35de6f3d05d07f409589a7f11cad Mon Sep 17 00:00:00 2001
From: Alpha <AlphaWong@users.noreply.github.com>
Date: Tue, 20 Oct 2020 13:13:13 +0800
Subject: [PATCH 3/3] doc: simplify the language for understanding

---
 .../content/en/api-reference/kustomization/vars/_index.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/site/content/en/api-reference/kustomization/vars/_index.md b/site/content/en/api-reference/kustomization/vars/_index.md
index 4cf74015c..9cf96591c 100644
--- a/site/content/en/api-reference/kustomization/vars/_index.md
+++ b/site/content/en/api-reference/kustomization/vars/_index.md
@@ -72,15 +72,15 @@ vars:
     fieldpath: data.MY_PORT
     
 configurations:
-  - linkage.yaml
+  - lookup.yaml
 ```
 
-Define the linkage of the consuming resource(s) and the field(s) inside.
+Define the consuming resource(s) and the field(s) inside need to lookup.
 
 ```yaml
-# linkage.yaml
+# lookup.yaml
 varReference:
-  # the path of resource(s) that you want the parser to lookup
+  # the path of field that you want the parser to lookups and replace.
   - path: spec/template/spec/containers/livenessProbe/httpGet/port
     kind: Deployment
 ```