Merge pull request #25 from mileszhang2016/develop

polish documents for ingress-bfe

README-CN.md

@@ -13,9 +13,9 @@ BFE Ingress Controller 为基于 [BFE][] 实现的[Kubernetes Ingress Controller
 详见[文档列表](docs/zh_cn/SUMMARY.md)
 
 ## 参与贡献
-- 请首先在 issue 列表中创建一个 issue
+- 请首先在 [issue 列表](https://github.com/bfenetworks/ingress-bfe/issues) 中创建一个 issue
 - 如有必要，请联系项目维护者/负责人进行进一步讨论
-- 请遵循 Golang 编程规范
+- 请遵循 [Golang 编程规范](https://github.com/golang/go/wiki/Style)
 
 ## 社区交流
 

README.md

@@ -27,6 +27,6 @@ See [Document Summary](docs/en_us/SUMMARY.md)
 
 BFE is under the Apache 2.0 license. See the [LICENSE](https://github.com/bfenetworks/ingress-bfe/blob/master/LICENSE) file for details
 
-[Kubernetes Ingress Controller]: https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/ "Kubernetes"
+[Ingress Controller]: https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/ "Kubernetes"
 [Ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ "Kubernetes"
 [BFE]: https://github.com/bfenetworks/bfe "Github"

docs/en_us/FAQ/FAQ.md

@@ -5,8 +5,8 @@
 
 |Argument | Default value | Description|
 | --- | --- | --- |
-| --namespace <br> -n | Null | Specifies in which namespaces the BFE Ingress Controller will monitor Ingress, seperate multiple namespaces by `,`. <br>Default value means monitor all namespaces  |
-| --ingress-class| bfe | Specifies the `kubernetes.io/ingress.class` value of Ingress it monitors. <br>If not specified, BFE Ingress Controller monitors the Ingress with ingress class set as bfe. Usually you don't need to specify it. |
+| --namespace <br> -n | Null | Specify in which namespaces BFE Ingress Controller will monitor Ingress. Multiple namespaces are seperated by `,`. <br>Default value means to monitor all namespaces.  |
+| --ingress-class| bfe | Specify the `kubernetes.io/ingress.class` value of Ingress it monitors. <br>If not specified, BFE Ingress Controller monitors the Ingress with ingress class set as "bfe". Usually you don't need to specify it. |
 | --default-backend| Null | Specify name of default backend service, in the format of `namespace/name`.<br>If specified, requests that match no Ingress rule will be forwarded to the service specified. |
 
 How to define：

docs/en_us/SUMMARY.md

@@ -6,9 +6,9 @@
     * [Role-Based Access Control (RBAC)](rbac.md)
 * Configuration
     * [Configuration Guide](ingress/basic.md)
-    * [Validate State](ingress/validate-state.md)
+    * [Ingress Status](ingress/validate-state.md)
     * [Priority of Route Rules](ingress/priority.md)
-    * [Route Rule Conflicts](ingress/conflict.md)
+    * [Principles of Handling Route Rule Conflicts](ingress/conflict.md)
     * [TLS  Configuration](ingress/tls.md)
     * [Load Balance](ingress/load-balance.md)
 * Configuration Examples

docs/en_us/deployment.md

@@ -8,7 +8,7 @@
     kubectl apply -f controller.yaml
     ```
     - Config file example: [controller.yaml](../../examples/controller.yaml)
-        - This config file uses [BFE Ingress Controller]:latest image on Docker Hub. If you want to use your customized version of the image, edit the config file to specify it.
+        - This config file uses [BFE Ingress Controller latest image on Docker Hub](https://hub.docker.com/r/bfenetworks/bfe-ingress-controller). If you want to use your customized version of the image, edit the config file to specify it.
         - Or you can run `make docker` in root folder of this project to create your own local image and use it.
 
 * To config role-based access control:
@@ -17,7 +17,7 @@
     ```
 
    - Config file example: [rbac.yaml](../../examples/rbac.yaml)
-   - See detailed instructions in [Role-Based Access Control](rbac.md)。
+   - See detailed instructions in [Role-Based Access Control](rbac.md)
 
 ## Test
 
@@ -38,6 +38,4 @@
 
    - Refer to [ingress.yaml](../../examples/ingress.yaml) for basic Ingress configuration.
 
-   - More Ingress configuration options that BFE Ingress Controller support, refer to [Configuration](SUMMARY.md).
-
-[BFE Ingress Controller]: https://hub.docker.com/r/bfenetworks/bfe-ingress-controller
+   - Refer to [Summary](SUMMARY.md) for more Ingress configuration options that BFE Ingress Controller support.

docs/en_us/example/canary-release.md

@@ -1,10 +1,10 @@
 # Canary Release
 
 ## Introduction
-BFE Ingress Controller support `Header/Cookie` based "canary release" by configuring`Annotation`.
+BFE Ingress Controller supports `Header/Cookie` based "canary release" by configuring`Annotation`.
 
 ## Config Example
-* Original ingress config as follows, which will forward matched requests to `service`：
+* Original ingress configuration is shown as follows. Ingress will forward matched requests to `service`：
 ```yaml
 kind: Ingress
 apiVersion: networking.k8s.io/v1beta1
@@ -24,8 +24,8 @@ spec:
               servicePort: 80
 ```
 
-* Canary release is required and interested requests should be forwarded to a new service `service2`.
-* To implement this, create a new ingress, with header or cookie information of  interested requests included in annotations.
+* Canary release is applied and interested requests should be forwarded to a new service `service2`.
+* To achieve this, create a new ingress, with header or cookie information of interested requests included in annotations.
 ```yaml
 kind: Ingress
 apiVersion: networking.k8s.io/v1beta1
@@ -48,8 +48,8 @@ spec:
               servicePort: 80
 
 ```
-* Based on above config, BFE Ingress Controller will
-1. requests with `host == example.net && path == /bar && cookie[key] == value && Header[Key] == Value`,
-   forwarded to service `service-new`
-1. other request with `host == example.net && path == /bar`，
-   forwarded to service `service`
+* Based on above configuration, BFE Ingress Controller will
+1. forward requests with `host == example.net && path == /bar && cookie[key] == value && Header[Key] == Value`
+   to service `service-new`
+1. forward other requests with `host == example.net && path == /bar`
+   to service `service`

docs/en_us/example/example.md

@@ -1,9 +1,9 @@
-# Config File Example
+# Examples of Config File 
 
 ## deployment
 | Program | File | Description |
 | ---- | ---- | ---- |
-| bfe-ingress-controller  | [controller.yaml](../../../examples/controller.yaml)| to deploy Bfe Ingress Controller |
+| bfe-ingress-controller  | [controller.yaml](../../../examples/controller.yaml)| to deploy BFE Ingress Controller |
 | example backend service: whoami | [whoami.yaml](../../../examples/whoami.yaml) | to deploy example service `whoami` |
 
 ## ingress
@@ -14,5 +14,5 @@
 ## rbac
 | File | Description |
 | ---- | ---- |
-| [rbac.yaml](../../../examples/rbac.yaml) | to config access control for Bfe Ingress Controller |
+| [rbac.yaml](../../../examples/rbac.yaml) | to config access control for BFE Ingress Controller |
 

docs/en_us/ingress/basic.md

@@ -1,7 +1,7 @@
 # Configuration Guide
 
 ## Introduction
-Configure Ingress resources to define route of accessing Services in Kubernetes cluster from outside the cluster. For more information about Ingress, refer to [Ingress][] .
+Configure Ingress resources to define routes for accessing Services in Kubernetes cluster from outside of the cluster. For more information about Ingress, please refer to [Ingress][] .
 
 Refer to [ingress.yaml](../../examples/ingress.yaml) when configuring Ingress resources in yaml files.
 
@@ -25,14 +25,12 @@ spec:
             port:
               number: 80
 ```
-Above example defined a Ingress resource, and
+Above example defines a Ingress resource, and
 
-- set `kubernetes.io/ingress.class` to `bfe`, means this Ingress will be handled by BFE Ingress Controller
+- sets `kubernetes.io/ingress.class` to `bfe`, means this Ingress will be handled by BFE Ingress Controller
 
--  defines a simple route rule：
-  A requests will be forwarded to port 80 of Service `whoami`, if it matches both below conditions:
+- defines a simple route rule. A request will be forwarded to port 80 of Service `whoami`, if it matches both below conditions:
   - hostname is `whoami.com` 
-
   - path has prefix `/testpath`
 
 ### Complicated example
@@ -70,9 +68,9 @@ spec:
             port:
               number: 80
 ```
-Above Ingress resource defines 2 advanced route rule, and configure TLS certificate for `foo.com`. Rules in annotations are BFE defined rule options.
+Above Ingress resource defines 2 advanced route rules, and configure TLS certificate for `foo.com`. Rule options supported by BFE are defined with annotations.
 
-- Route rule 1：a request will be forwarded to port 80 of service`foo` , if it matches all below conditions. And Service `foo` is composed of two Services: `sub-foo1` and `sub-foo2`, serving 80% and 20% of requests to `foo`. See [Load balancing between Services](load-balance.md).
+- Route rule 1：a request will be forwarded to port 80 of service`foo` , if it matches all below conditions. Service `foo` is composed of two Services: `sub-foo1` and `sub-foo2`, serving 80% and 20% of total requests to `foo`. See [Load balancing between Services](load-balance.md).
 
     - hostname is `foo.com`
     - path has prefix `/foo`
@@ -109,9 +107,9 @@ BFE Ingress Controller support below pathType：
 
 BFE Ingress Controller supports advanced conditions by configuring `annotation`.
 
-Advanced conditions is shared in a Ingress resource. So all the rules in the same Ingress resource will be restrained by advanced conditions, if configured.
+Advanced conditions are shared in a Ingress resource. So all the rules in the same Ingress resource will be restrained by advanced conditions, if configured.
 
-Currently BFE Ingress Controller support two advanced conditions types: cookie and header.
+Currently BFE Ingress Controller supports two types of advanced condition: cookie and header.
 
 #### Cookie
 
@@ -122,7 +120,7 @@ bfe.ingress.kubernetes.io/router.cookie: "key: value"
 
 Explanation：
 
-Requests containing a cookie with name=`key` and value=`value` are considered match this condition.
+Requests containing a cookie with name=`key` and value=`value` are considered as matching this condition.
 
 #### Header      
 
@@ -140,7 +138,7 @@ Requests containing a header with name=`key` and value=`value` are considered ma
 
 - In a Ingress resource, for each advanced condition type, no more than one `Annotation` can be configured.
 
-- If more than one `Annotation` of the same advanced condition type are configured in the same Ingress resource, the bottom one takes effect.
+- If more than one `Annotation`s of the same advanced condition type are configured in the same Ingress resource, the last one takes effect.
 
     ```yaml
     # example
@@ -151,7 +149,7 @@ Requests containing a header with name=`key` and value=`value` are considered ma
 
 ## Ingress class
 
-BFE Ingress Controller support user to configure ingress class in two ways:
+BFE Ingress Controller supports user to configure ingress class in two ways:
 
 ### Set in annotations
 
@@ -164,7 +162,7 @@ Set `kubernetes.io/ingress.class` in annotations of Ingress. Default value is `b
 
 ### Set in IngressClass
 
-For k8s vesions from 1.18, set  controller to`bfe-networks.com/ingress-controller` in IngressClass of K8S Cluster. Example:
+For K8S vesions from 1.18, set controller to `bfe-networks.com/ingress-controller` in IngressClass of K8S Cluster. Example:
 
 ```yaml
 apiVersion: networking.k8s.io/v1beta1
@@ -186,10 +184,10 @@ spec:
 ...
 ```
 
-For information about  IngressClass, refer to [IngressClass]。
+For information about IngressClass, refer to [IngressClass]
 
 
 [Ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/#what-is-ingress
 [pathType]: https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types
 [hostname-wildcards]: https://kubernetes.io/docs/concepts/services-networking/ingress/#hostname-wildcards
-
+[IngressClass]: https://kubernetes.io/blog/2020/04/02/improvements-to-the-ingress-api-in-kubernetes-1.18/#extended-configuration-with-ingress-classes

docs/en_us/ingress/conflict.md

@@ -1,15 +1,15 @@
 # Route Rule Conflict
 
 ## Definition
-If Ingress configuration will create Ingress resources containing a same Ingress rule (host, path and advanced conditions are all the same), a route rule conflict happens. 
+If Ingress configuration is created with Ingress resources containing the same Ingress rule (host, path and advanced conditions are all the same), a route rule conflict happens. 
 
 ## Conflict handling: first-created-resource-win principle
 
 For those Ingress resources with route rule conflict, BFE Ingress Controller will follow first-created-resource-win principle and only takes the first created Ingress resource as valid.  
 
-Route rule conflicts within a namespace or among different namespaces will both follow this principle.
+This principle will be followed when route rule conflict happens within a namespace or among different namespaces.
 
-For those Ingress resources that not taken as valid by BFE Ingress Controller due to route rule conflict, related error messages will be writen to its annotation, see [Validate State](validate-state.md) `annotations`.
+For those Ingress resources invalid due to route rule conflict, error messages will be written to its annotation, see [Ingress Status](validate-state.md).
 
 ## Example
 
@@ -51,12 +51,12 @@ spec:
           servicePort: 80
 
 ```
-In above config, ingress-A and ingress-B have conflict, and ingress-A is created before ingress-B. So only ingress-A will been created and take effect.
+In above configuration, there is conflict between ingress-A and ingress-B, and ingress-A is created before ingress-B. So only ingress-A will been created and take effect.
 
-## Validate state writeback
-If a Ingress resource is ignored (not take effect) due to route rule conflict, after validate state writeback, the `status` of validate state `annotation` will be set as “fail”, and `message` will tell which Ingres resource it conflict with.
+## Ingress status feedback
+If a Ingress resource is ignored (not take effect) due to route rule conflict, after the ingress status is written back, the `status` in `annotation` will be set as “fail”, and `message` will tell which Ingress resource it has conflict with.
 
-In previous example, validate state `annotation` will be like:
+In previous example, `annotation` for ingress status will be like:
 
 
 ```yaml
@@ -66,5 +66,5 @@ metadata:
     	{"status": "fail", "message": "conflict with production/ingress-A"}
 ```
 
-For more information about validate state, refer to [Validate state](validate-state.md)。
+For more information about ingress status, refer to [ingress status](validate-state.md)。
 

docs/en_us/ingress/load-balance.md

@@ -1,15 +1,15 @@
 # Load banlancing between Services
 ## Introduction
 
-For `Service`s that providing the same service (called Sub-Services),  BFE Ingress Controller support load balancing between them, based on weight configured for each `Service`.
+For `Service`s that providing the same service (called Sub-Services),  BFE Ingress Controller supports load balancing between them, based on weight configured for each `Service`.
 
 ## Configuration
 
 BFE Ingress Controller use `Annotation` to support load-balancing between multiple Sub-Services：
 
 - in `annotations`
 
-  - config weight for each Sub-Service.
+  - configurate weight for each Sub-Service.
 
   - define a `Service` name for the service they provided together：
 
@@ -19,7 +19,7 @@ BFE Ingress Controller use `Annotation` to support load-balancing between multip
 
 - in `rules`
 
-  - config the `serviceName` of `backend` as the `Service` name in `Annotation`, and config the `servicePort`.
+  - set the `serviceName` of `backend` as the `Service` name in `Annotation`, and set the `servicePort`.
 
 ## Example
 
@@ -45,4 +45,4 @@ spec:
         backend:
           serviceName: service
           servicePort: 80
-```
+```

docs/en_us/ingress/priority.md

@@ -1,10 +1,10 @@
 # Priority of route rules
 If a request matches multiple ingress rules, BFE Ingress Controller will decide which rule will be hit according to below strategies:
 
--  Compares the hostname and select the rule with more precise hostname；
--  If hostname is identical, select the rule with more precise path；
+-  Compare the hostname and select the rule with more precise hostname;
+-  If hostname is identical, select the rule with more precise path;
 -  If both hostname and path are identical, select the rule with more matching advanced conditions;
--  If all the above criteria are the same, select the rule which matches an advanced condition of higher priority
+-  If all the above rules fails, select the rule which matches an advanced condition of higher priority
    - in advanced match condition, Cookie condition has higher priority than Header condition；
 
 ## Examples
@@ -44,7 +44,7 @@ spec:
               serviceName: service2
               servicePort: 80
 ```
-In above example, for requests generated by `curl "http://example.net/bar"`, rule in `host_priority1` will be hit
+In above example, for requests generated by `curl "http://example.net/bar"`, rule with name `host_priority1` will be hit.
 
 ### Path precision first when hostname are identical
 ```yaml
@@ -83,7 +83,7 @@ spec:
               serviceName: service2
               servicePort: 80
 ```
-In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Key: value"`, rule in `path_priority1` will be hit
+In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Key: value"`, rule with name `path_priority1` will be hit
 
 ### More matched advanced condition first, when hostname and path both identical
 ```yaml
@@ -123,7 +123,7 @@ spec:
               serviceName: service2
               servicePort: 80
 ```
-In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Key: value"`, rule in `cond_priority1` will be hit
+In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Key: value"`, rule with name `cond_priority1` will be hit
 
 ### Matched advanced condition with higher priority first, when above criteria are the same
 ```yaml
@@ -163,5 +163,5 @@ spec:
               serviceName: service2
               servicePort: 80
 ```
-In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Header-key: value" --cookie "cookie-key: value"`, rule in `multi_cond_priority2` will be hit, as `Cookie` condition has higher priority than `Header` condition
+In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Header-key: value" --cookie "cookie-key: value"`, rule with name `multi_cond_priority2` will be hit, for `Cookie` condition has higher priority than `Header` condition.
 

docs/en_us/ingress/tls.md

@@ -1,9 +1,9 @@
 # TLS Configuration
-BFE Ingress Controller manage TLS certificates and secretes in the way defined by Kubernetes.
+BFE Ingress Controller manages TLS certificates and secretes in the way defined by Kubernetes.
 
 TLS certificates and secretes are stored in `Secret`. See examples below:
 
-**Config Secret**
+**Configurate Secret**
 
 ```yaml
 apiVersion: v1
@@ -16,7 +16,7 @@ data:
   tls.key: base64 encoded key
 type: kubernetes.io/tls
 ```
-**Config Ingress**
+**Configurate Ingress**
 
 ```yaml
 apiVersion: networking.k8s.io/v1beta1