Merge pull request #22 from clarinette9/develop

Develop: add english docs and update other docs and README

README-CN.md

@@ -0,0 +1,47 @@
+# BFE Ingress Controller
+
+中文 | [English](README.md)
+
+## 简介
+
+BFE Ingress Controller 为基于 [BFE][] 实现的[Kubernetes Ingress Controller][]，用于支持在 Kubernetes 中使用 [Ingress][]。 
+
+## 开始使用
+详见[部署指南](docs/zh_cn/deployment.md)
+
+## 说明文档
+详见[文档列表](docs/zh_cn/SUMMARY.md)
+
+## 参与贡献
+- 请首先在 issue 列表中创建一个 issue
+- 如有必要，请联系项目维护者/负责人进行进一步讨论
+- 请遵循 Golang 编程规范
+
+## 社区交流
+
+- [用户论坛](https://github.com/bfenetworks/ingress-bfe/discussions)
+
+- **开源BFE微信公众号**：扫码关注公众号“BFE开源项目”，及时获取项目最新信息和技术分享
+
+  <table>
+  <tr>
+  <td><img src="./docs/images/qrcode_for_gh.jpg" width="100"></td>
+  </tr>
+  </table>
+
+- **开源BFE用户微信群**：扫码加入，探讨和分享对BFE的建议、使用心得、疑问等
+
+  <table>
+  <tr>
+  <td><img src="https://bfeopensource.bj.bcebos.com/wechatQRCode.png" width="100"></td>
+  </tr>
+  </table>
+
+- **开源BFE开发者微信群**: [发送邮件](mailto:iyangsj@gmail.com)说明您的微信号及贡献(例如PR/Issue)，我们将及时邀请您加入
+
+## 许可
+基于 Apache 2.0 许可证，详见 [LICENSE](https://github.com/bfenetworks/ingress-bfe/blob/master/LICENSE) 文件说明
+
+[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"

README.md

@@ -1,20 +1,31 @@
 # BFE Ingress Controller
 
-BFE Ingress Controller 为基于 [BFE][] 实现的[Kubernetes Ingress Controller][]，用于支持在 Kubernetes 中使用 [Ingress][]。 
+English | [中文](README-CN.md)
 
-## 开始使用
-详见[部署指南](docs/zh_cn/deployment.md)
+## Overview
 
-## 说明文档
-详见[文档列表](docs/zh_cn/SUMMARY.md)
+BFE Ingress Controller is an implementation of Kubernetes [Ingress Controller][] based on  [BFE][] , to fulfill  [Ingress][] in Kubernetes。 
 
-## 参与贡献
-- 请首先在 issue 列表中创建一个 issue
-- 如有必要，请联系项目维护者/负责人进行进一步讨论
-- 请遵循 Golang 编程规范
+## Quick start
+See [Deployment](docs/en_us/deployment.md) for quick start of using BFE Ingress Controller
 
-## 许可
-基于 Apache 2.0 许可证，详见 [LICENSE](https://github.com/bfenetworks/ingress-bfe/blob/master/LICENSE) 文件说明
+## Documentation
+See [Document Summary](docs/en_us/SUMMARY.md)
+
+## Contribute
+- Create and issue in [Issue List](https://github.com/bfenetworks/ingress-bfe/issues)
+- If necessary, contact and discuss with maintainer
+- Follow the [Golang style guide](https://github.com/golang/go/wiki/Style)
+
+## Communication
+
+- [Forum](https://github.com/bfenetworks/ingress-bfe/discussions)
+- BFE community on Slack: [Sign up](https://slack.cncf.io/) CNCF Slack and join bfe channel.
+- BFE developer group on WeChat: [Send a request mail](mailto:iyangsj@gmail.com) with your WeChat ID and a contribution you've made to BFE(such as a PR/Issue). We will invite you right away.
+
+## License
+
+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]: https://kubernetes.io/docs/concepts/services-networking/ingress/ "Kubernetes"

docs/en_us/FAQ/FAQ.md

@@ -0,0 +1,22 @@
+# FAQ
+1. Question：what arguments can be used to run BFE Ingress Controller, and how to define them?
+
+   Answer: Arguments supported by BFE Ingress Controller：
+
+|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. |
+| --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：
+Define in config file of BFE Ingress Controller, like [controller.yaml](../../../examples/controller.yaml). Example：
+
+```yaml
+...
+      containers:
+        - name: bfe-ingress-controller
+          image: bfenetworks/bfe-ingress-controller:latest
+          args: ["-n", "ns1,ns2", "--default-backend", "test/whoami"]
+...
+```

docs/en_us/README.md

@@ -0,0 +1,10 @@
+# BFE Ingress Controller
+
+BFE Ingress Controller is a Kubernetes [Ingress Controller][] based on [BFE][], to fullfill the [Ingress][] in Kubernetes. 
+
+[Documents](SUMMARY.md)
+
+[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/SUMMARY.md

@@ -0,0 +1,25 @@
+# Summary
+
+[comment]: <> "For user"
+* Deployment
+    * [Deployment Guide](deployment.md)
+    * [Role-Based Access Control (RBAC)](rbac.md)
+* Configuration
+    * [Configuration Guide](ingress/basic.md)
+    * [Validate State](ingress/validate-state.md)
+    * [Priority of Route Rules](ingress/priority.md)
+    * [Route Rule Conflicts](ingress/conflict.md)
+    * [TLS  Configuration](ingress/tls.md)
+    * [Load Balance](ingress/load-balance.md)
+* Configuration Examples
+    * [Config File Example](example/example.md)
+    * [Canary Release Example](example/canary-release.md)
+* [FAQ](FAQ/FAQ.md)
+---
+
+[comment]: <> "For developer"
+* [How to contribute](contribute/how-to-contribute.md)
+    * [Contribute codes](contribute/contribute-codes.md)
+    * [Contribute documents](contribute/contribute-documents.md)
+    * [Release Regulation](https://www.bfe-networks.net/en_us/development/release_regulation/)
+

docs/en_us/contribute/contribute-codes.md

@@ -0,0 +1,108 @@
+# Contribute Code
+This document explains how to contribute code
+
+## Coding Standard
+- For code and comment, follow the [Golang style guide](https://github.com/golang/go/wiki/Style).
+- Provide unit test for all code
+- Pass all unit test
+- Follow our [regulations of submmiting codes](https://www.bfe-networks.net/en_us/development/submit_pr_guide/)
+
+## Code Develop
+Below tutorial will guide you to submit code
+
+1. [Fork](https://help.github.com/articles/fork-a-repo/)
+
+    Go to [BFE Ingress Github][], click `Fork` button and generate a repository in your own github space.
+
+    >  `https://github.com/${USERNAME}/ingress-bfe`
+    
+1. Clone
+
+    Clone the repository  in your own space to your local :
+    ```bash
+    $ git clone https://github.com/${USERNAME}/ingress-bfe
+    $ cd ingress-bfe
+    ```
+
+1. Create local branch
+
+    We currently use [Git Branching Model][] to develop, test, release and maintenance, refer to [Release Regulation][]。
+    * all development for feature and bug fix should be performed in a new branch
+    * create new branch from branch `develop` in most case
+
+    Use `git checkout -b` to create and switch to a new branch.
+    ```bash
+    $ git checkout -b my-cool-stuff
+    ```
+
+    > Before checkout, verify by `git status` command and keep current branch clean, otherwise untracked files will be bring to the new branch. 
+
+1. Use pre-commit hook
+
+    We use [pre-commit][] tool to manage Git pre-commit hook. 
+
+
+    1. run following command：
+        ```bash
+        $ pip install pre-commit
+        $ pre-commit install
+        ```
+    1. use  `gofmt` to adjust golang source code format.
+
+1. Coding
+
+1. Build and test
+
+    Compile  BFE Ingress Controller docker from source code and test, see more instruction in [Deploy Guide](../deployment.md)
+
+1. Commit
+
+    run `git commit` .
+
+    Provides commit message for each commit, to let other people know what is changed in this commit.`git commit` .
+
+    <b> <font color="red">Notice：commit message is also required to trigger CI unit test，format as below:</font> </b>
+
+    ```bash
+    # trigger CI unit test in develop branch
+    $ git commit -m "test=develop"
+    
+    # trigger CI unit test in release/1.1 branch
+    $ git commit -m "test=release/1.1"
+    ```
+
+1. Keep local repository up-to-date
+
+1. An experienced Git user pulls from the official repo often -- daily or even hourly, so they notice conflicts with others work early, and it's easier to resolve smaller conflicts.
+
+   ```bash
+   git remote add upstream https://github.com/bfenetworks/bfe
+   git pull upstream develop
+   ```
+
+10. Push to remote repository
+
+    Push local to your repository on GitHub `https://github.com/${USERNAME}/ingress-bfe`
+
+```bash
+# Example: push to remote repository `origin` branch `my-cool-stuff`
+$ git push origin my-cool-stuff
+```
+
+> Refer to BFE [Local Develop Guide](https://www.bfe-networks.net/en_us/development/local_dev_guide/)
+
+## Pull Request
+
+1. Create an Issue and initiate Pull Request
+1. Pass unit test
+1. Delete the branch used at your own repository
+1. Delete the branch used at your local repository
+
+> Refer to BFE [Submit PR Guide][submit PR guide]
+
+[BFE Ingress Github]: https://github.com/bfenetworks/ingress-bfe
+[Git Branching Model]: http://nvie.com/posts/a-successful-git-branching-model/
+[Release Regulation]: https://github.com/bfenetworks/bfe/blob/develop/docs/en_us/development/release_regulation.md
+[pre-commit]: http://pre-commit.com/
+[git remote]: https://git-scm.com/docs/git-remote
+[submit PR guide]: https://www.bfe-networks.net/en_us/development/submit_pr_guide/

docs/en_us/contribute/contribute-documents.md

@@ -0,0 +1,17 @@
+# Contribute Document
+
+## Requirement
+- All documents should be written in [Markdown][markdown] (GitHub style)，using filename with suffix `.md`
+- If new document will be add, add the link to the new document in the index file（[SUMMARY.md](../SUMMARY.md)）
+## Process
+
+1. Write or edit document
+1. Use preview tools to preview and modify if neccesary
+    - [How to use preview tool](https://www.bfe-networks.net/en_us/development/write_doc_guide/#_2)
+1. Submit
+    - Commit and initiate a Pull Request, refer to [Contribute Code](contribute-codes.md)
+
+> Also you can refer to [Contribute Documentation](https://www.bfe-networks.net/en_us/development/write_doc_guide/) of BFE
+
+[markdown]: https://guides.github.com/features/mastering-markdown/
+

docs/en_us/contribute/how-to-contribute.md

@@ -0,0 +1,5 @@
+# Contribute
+- [Contribute Code](contribute-codes.md)
+- [Contribute Document](contribute-documents.md)
+- [Release Regulation](https://www.bfe-networks.net/en_us/development/release_regulation/)
+

docs/en_us/deployment.md

@@ -0,0 +1,43 @@
+# Deployment Guide
+
+## Install
+
+* To deploy BFE Ingress Controller and configure related access control:
+
+    ``` shell script
+    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.
+        - 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:
+    ``` shell script
+    kubectl apply -f rbac.yaml
+    ```
+
+   - Config file example: [rbac.yaml](../../examples/rbac.yaml)
+   - See detailed instructions in [Role-Based Access Control](rbac.md)。
+
+## Test
+
+* Create a test service
+
+  ``` shell script
+  kubectl apply -f whoami.yaml
+  ```
+
+
+   test service config file example：[whoami](../../examples/whoami.yaml)
+
+* Create ingress resource，configure route for the test service and verify
+
+   ``` shell script
+   kubectl apply -f ingress.yaml  
+   ```
+
+   - 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

docs/en_us/example/canary-release.md

@@ -0,0 +1,55 @@
+# Canary Release
+
+## Introduction
+BFE Ingress Controller support `Header/Cookie` based "canary release" by configuring`Annotation`.
+
+## Config Example
+* Original ingress config as follows, which will forward matched requests to `service`：
+```yaml
+kind: Ingress
+apiVersion: networking.k8s.io/v1beta1
+metadata:
+  name: "original"
+  namespace: production
+
+spec:
+  rules:
+    - host: example.net
+      http:
+        paths:
+          - path: /bar
+            pathType: Exact
+            backend:
+              serviceName: service
+              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.
+```yaml
+kind: Ingress
+apiVersion: networking.k8s.io/v1beta1
+metadata:
+  name: "greyscale"
+  namespace: production
+  annotations:
+    bfe.ingress.kubernetes.io/router.cookie: "key: value"
+    bfe.ingress.kubernetes.io/router.header: "Key: Value"
+
+spec:
+  rules:
+    - host: example.net
+      http:
+        paths:
+          - path: /bar
+            pathType: Exact
+            backend:
+              serviceName: service2
+              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`