From 40957d43ccaf13b380887d8dee8abe709e01a303 Mon Sep 17 00:00:00 2001 From: longwuyuan Date: Fri, 26 May 2023 23:58:19 +0530 Subject: [PATCH] add faq section in docs --- docs/faq.md | 33 ++++++++++++++ docs/index.md | 7 +-- docs/user-guide/retaining-client-ipaddress.md | 44 +++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 79 insertions(+), 6 deletions(-) create mode 100644 docs/faq.md create mode 100644 docs/user-guide/retaining-client-ipaddress.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..253378c65 --- /dev/null +++ b/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 ingress-nginx-dev@kubernetes.io diff --git a/docs/index.md b/docs/index.md index bcf4a4018..0a0f488cf 100644 --- a/docs/index.md +++ b/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). diff --git a/docs/user-guide/retaining-client-ipaddress.md b/docs/user-guide/retaining-client-ipaddress.md new file mode 100644 index 000000000..237bd3004 --- /dev/null +++ b/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 + +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 diff --git a/mkdocs.yml b/mkdocs.yml index 380b1b67a..992c04d45 100644 --- a/mkdocs.yml +++ b/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"