Merge pull request #10003 from longwuyuan/add-faq-section

add faq section in docs

Author: strongjz

docs/faq.md

@@ -0,0 +1,33 @@
+
+# FAQ
+
+## Retaining Client IPAddress
+
+Please read [Retain Client IPAddress Guide here](./user-guide/retaining-client-ipaddress.md).
+
+## Kubernetes v1.22 Migration
+
+If you are using Ingress objects in your cluster (running Kubernetes older than v1.22), and you plan to upgrade your Kubernetes version to K8S 1.22 or above, then please read [the migration guide here](./user-guide/k8s-122-migration.md).
+
+## Validation Of __`path`__
+
+- For improving security and also following desired standards on Kubernetes API spec, the next release, scheduled for v1.8.0, will include a new & optional feature of validating the value for the key `ingress.spec.rules.http.paths.path` .
+
+- This behavior will be disabled by default on the 1.8.0 release and enabled by default on the next breaking change release, set for 2.0.0.
+
+- When "`ingress.spec.rules.http.pathType=Exact`" or "`pathType=Prefix`", this validation will limit the characters accepted on the field "`ingress.spec.rules.http.paths.path`",  to "`alphanumeric characters`", and  `"/," "_," "-."` Also, in this case, the path should start with `"/."`
+
+- When the ingress resource path contains other characters (like on rewrite configurations), the pathType value should be "`ImplementationSpecific`".
+
+- API Spec on pathType is documented [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types)
+
+- When this option is enabled, the validation will happen on the Admission Webhook. So if any new ingress object contains characters other than  "`alphanumeric characters`", and  `"/," "_," "-."` , in the `path` field, but is not using `pathType` value as `ImplementationSpecific`, then the ingress object will be denied admission.
+
+- The cluster admin should establish validation rules using mechanisms like "`Open Policy Agent`", to validate that only authorized users can use ImplementationSpecific pathType and that only the authorized characters can be used. [The configmap value is here](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/#strict-validate-path-type)
+
+- A complete example of an Openpolicyagent gatekeeper rule is available [here](https://kubernetes.github.io/ingress-nginx/examples/openpolicyagent/)
+
+- If you have any issues or concerns, please do one of the following: 
+  - Open a GitHub issue 
+  - Comment in our Dev Slack Channel
+  - Open a thread in our Google Group [email protected]

docs/index.md

@@ -6,12 +6,7 @@ It is built around the [Kubernetes Ingress resource](https://kubernetes.io/docs/
 
 You can learn more about using [Ingress](http://kubernetes.io/docs/user-guide/ingress/) in the official [Kubernetes documentation](https://docs.k8s.io).
 
-## Getting Started
+# Getting Started
 
 See [Deployment](./deploy/) for a whirlwind tour that will get you started.
 
-
-# FAQ - Kubernetes 1.22 Migration
-
-If you are using Ingress objects in your cluster (running Kubernetes older than v1.22),
-and you plan to upgrade to Kubernetes v1.22, please read [the migration guide here](./user-guide/k8s-122-migration.md).

docs/user-guide/retaining-client-ipaddress.md

@@ -0,0 +1,44 @@
+
+## Retaining Client IPAddress
+
+Please read this https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/#source-ip-address , to get details of retaining the client IPAddress.
+
+### Using proxy-protocol
+
+Please read this https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/#proxy-protocol , to use proxy-protocol for retaining client IPAddress
+
+
+### Using the K8S spec service.spec.externalTrafficPolicy
+
+```
+% kubectl explain service.spec.externalTrafficPolicy
+KIND:       Service
+VERSION:    v1
+
+FIELD: externalTrafficPolicy <string>
+
+DESCRIPTION:
+    externalTrafficPolicy describes how nodes distribute service traffic they
+    receive on one of the Service's "externally-facing" addresses (NodePorts,
+    ExternalIPs, and LoadBalancer IPs). If set to "Local", the proxy will
+    configure the service in a way that assumes that external load balancers
+    will take care of balancing the service traffic between nodes, and so each
+    node will deliver traffic only to the node-local endpoints of the service,
+    without masquerading the client source IP. (Traffic mistakenly sent to a
+    node with no endpoints will be dropped.) The default value, "Cluster", uses
+    the standard behavior of routing to all endpoints evenly (possibly modified
+    by topology and other features). Note that traffic sent to an External IP or
+    LoadBalancer IP from within the cluster will always get "Cluster" semantics,
+    but clients sending to a NodePort from within the cluster may need to take
+    traffic policy into account when picking a node.
+    
+    Possible enum values:
+     - `"Cluster"` routes traffic to all endpoints.
+     - `"Local"` preserves the source IP of the traffic by routing only to
+    endpoints on the same node as the traffic was received on (dropping the
+    traffic if there are no local endpoints).
+
+```
+
+
+- Setting the field `externalTrafficPolicy`, in the ingress-controller service, to a value of `Local` retains the client's ipaddress, within the scope explained above

mkdocs.yml

@@ -130,3 +130,4 @@ nav:
   - Developer Guide:
       - Getting Started: "developer-guide/getting-started.md"
       - Code Overview: "developer-guide/code-overview.md"
+  - FAQ: "faq.md"