From 7eec29e38e69ae9e75f1d9a5bb57e0541048c9a2 Mon Sep 17 00:00:00 2001 From: clarinette9 <83874119+clarinette9@users.noreply.github.com> Date: Fri, 15 Oct 2021 19:39:17 +0800 Subject: [PATCH 01/28] Fix a broken link in doc (#17) --- docs/zh_cn/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh_cn/README.md b/docs/zh_cn/README.md index 800d8288..07856e2a 100644 --- a/docs/zh_cn/README.md +++ b/docs/zh_cn/README.md @@ -3,7 +3,7 @@ BFE Ingress Controller 是基于 [BFE][] 实现的 Kubernetes [Ingress Controller][]， 用于支持在 Kubernetes 中使用 [Ingress][]。 -[文档列表](summary.md) +[文档列表](SUMMARY.md) [Ingress Controller]: https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/ "Kubernetes" [Ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/ "Kubernetes" From 6c70a5e167e3c9e45878b5c2c5ceb43bb74f9037 Mon Sep 17 00:00:00 2001 From: daiming Date: Wed, 20 Oct 2021 11:56:08 +0800 Subject: [PATCH 02/28] new arguments, bfe reload addr Signed-off-by: daiming --- cmd/ingress-controller/flags.go | 2 ++ cmd/ingress-controller/main.go | 2 +- internal/option/options.go | 18 +++++++++--------- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/cmd/ingress-controller/flags.go b/cmd/ingress-controller/flags.go index a0da2b6a..10ef35b4 100644 --- a/cmd/ingress-controller/flags.go +++ b/cmd/ingress-controller/flags.go @@ -28,6 +28,7 @@ var ( namespaces string ingressClass string configPath string + reloadAddr string metricsAddr string probeAddr string defaultBackend string @@ -46,6 +47,7 @@ func initFlags() { flag.StringVar(&configPath, "bfe-config-path", option.ConfigPath, "Root directory of bfe configuration files.") flag.StringVar(&configPath, "c", option.ConfigPath, "Root directory of bfe configuration files.") + flag.StringVar(&reloadAddr, "bfe-reload-address", option.ReloadAddr, "Address of bfe config reloading.") flag.StringVar(&ingressClass, "ingress-class", option.IngressClassName, "Class name of bfe ingress controller.") flag.StringVar(&metricsAddr, "metrics-bind-address", option.MetricsBindAddress, "The address the metric endpoint binds to.") flag.StringVar(&probeAddr, "health-probe-bind-address", option.HealthProbeBindAddress, "The address the probe endpoint binds to.") diff --git a/cmd/ingress-controller/main.go b/cmd/ingress-controller/main.go index 3cd9eeba..e20174de 100644 --- a/cmd/ingress-controller/main.go +++ b/cmd/ingress-controller/main.go @@ -65,7 +65,7 @@ func main() { } err := option.SetOptions( - namespaces, ingressClass, configPath, + namespaces, ingressClass, configPath, reloadAddr, metricsAddr, probeAddr, defaultBackend) if err != nil { setupLog.Error(err, "fail to start controllers") diff --git a/internal/option/options.go b/internal/option/options.go index 38cb5e64..faf4e737 100644 --- a/internal/option/options.go +++ b/internal/option/options.go @@ -25,8 +25,9 @@ import ( const ( ConfigPath = "/bfe/conf/" - reloadUrlPrefix = "http://localhost:8421/reload/" + ReloadAddr = "localhost:8421" reloadInterval = 3 * time.Second + reloadUrlPrefix = "http://%s/reload/" FilePerm os.FileMode = 0744 @@ -59,9 +60,7 @@ var ( Opts *Options ) -func SetOptions(namespaces, class, configPath, metricsAddr, probeAddr, defaultBackend string) error { - ns := strings.Split(namespaces, ",") - +func SetOptions(namespaces, class, configPath, reloadAddr, metricsAddr, probeAddr, defaultBackend string) error { if len(defaultBackend) > 0 { names := strings.Split(defaultBackend, string(types.Separator)) if len(names) != 2 { @@ -69,11 +68,15 @@ func SetOptions(namespaces, class, configPath, metricsAddr, probeAddr, defaultBa } } + if !strings.HasSuffix(configPath, "/") { + configPath = configPath + "/" + } + Opts = &Options{ - Namespaces: ns, + Namespaces: strings.Split(namespaces, ","), IngressClass: class, ControllerName: ControllerName, - ReloadUrl: reloadUrlPrefix, + ReloadUrl: fmt.Sprintf(reloadUrlPrefix, reloadAddr), ConfigPath: configPath, MetricsAddr: metricsAddr, HealthProbeAddr: probeAddr, @@ -81,8 +84,5 @@ func SetOptions(namespaces, class, configPath, metricsAddr, probeAddr, defaultBa DefaultBackend: defaultBackend, } - if !strings.HasSuffix(configPath, "/") { - Opts.ConfigPath = Opts.ConfigPath + "/" - } return nil } From 87d523df410e39b03775a79e5c09ce6b1b168f97 Mon Sep 17 00:00:00 2001 From: daiming Date: Fri, 22 Oct 2021 11:19:49 +0800 Subject: [PATCH 03/28] fix service port checking Signed-off-by: daiming --- internal/controllers/netv1/ingress_controller.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/controllers/netv1/ingress_controller.go b/internal/controllers/netv1/ingress_controller.go index 485efbdb..667fb0b8 100644 --- a/internal/controllers/netv1/ingress_controller.go +++ b/internal/controllers/netv1/ingress_controller.go @@ -230,7 +230,7 @@ func getService(ctx context.Context, r client.Reader, namespace, name string, po // check port exist for _, p := range svc.Spec.Ports { - if p.Name == port.Name || p.Port == port.Number { + if (port.Number > 0 && p.Port == port.Number) || (len(port.Name) > 0 && p.Name == port.Name) { return svc, nil } } From f1a4a56c8082a814449d4a84488780f7b42930ec Mon Sep 17 00:00:00 2001 From: zhugelianglongming Date: Fri, 22 Oct 2021 14:34:04 +0800 Subject: [PATCH 04/28] Enable Github pipeline Signed-off-by: zhugelianglongming --- .github/workflows/ci.yml | 41 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..bec5cf4d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,41 @@ +# This is a basic workflow to help you get started with Actions + +name: CI + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the master branch +on: + push: + branches: [ develop ] + pull_request: + branches: [ develop ] + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "ci" + ci: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - name: Checkout repository + uses: actions/checkout@v2 + with: + # Must fetch at least the immediate parents so that if this is + # a pull request then we can checkout the head of the pull request. + # Only include this option if you are running this workflow on pull requests. + fetch-depth: 2 + + # If this run was triggered by a pull request event then checkout + # the head of the pull request instead of the merge commit. + # Only include this step if you are running this workflow on pull requests. + - run: git checkout HEAD^2 + if: ${{ github.event_name == 'pull_request' }} + + # Build + - name: Build + shell: bash + run: | + make From 0f9f25cbba1f85947d2deb0a86cacb8fa609a2da Mon Sep 17 00:00:00 2001 From: clarinette9 Date: Sat, 23 Oct 2021 11:15:46 +0800 Subject: [PATCH 05/28] add english docs and update docs Signed-off-by: clarinette9 --- README-CN.md | 47 +++++ README.md | 33 ++- docs/en_us/FAQ/FAQ.md | 21 ++ docs/en_us/README.md | 10 + docs/en_us/SUMMARY.md | 25 +++ docs/en_us/contribute/contribute-codes.md | 108 ++++++++++ docs/en_us/contribute/contribute-documents.md | 17 ++ docs/en_us/contribute/how-to-contribute.md | 5 + docs/en_us/deployment.md | 43 ++++ docs/en_us/example/canary-release.md | 55 +++++ docs/en_us/example/example.md | 18 ++ docs/en_us/ingress/basic.md | 195 ++++++++++++++++++ docs/en_us/ingress/conflict.md | 66 ++++++ docs/en_us/ingress/load-balance.md | 47 +++++ docs/en_us/ingress/priority.md | 155 ++++++++++++++ docs/en_us/ingress/tls.md | 39 ++++ docs/en_us/ingress/validate-state.md | 86 ++++++++ docs/en_us/rbac.md | 65 ++++++ docs/images/qrcode_for_gh.jpg | Bin 0 -> 29049 bytes docs/zh_cn/ingress/basic.md | 16 +- docs/zh_cn/ingress/conflict.md | 19 +- docs/zh_cn/ingress/load-balance.md | 7 +- docs/zh_cn/ingress/priority.md | 27 +-- docs/zh_cn/ingress/validate-state.md | 21 +- 24 files changed, 1060 insertions(+), 65 deletions(-) create mode 100644 README-CN.md create mode 100644 docs/en_us/FAQ/FAQ.md create mode 100644 docs/en_us/README.md create mode 100644 docs/en_us/SUMMARY.md create mode 100644 docs/en_us/contribute/contribute-codes.md create mode 100644 docs/en_us/contribute/contribute-documents.md create mode 100644 docs/en_us/contribute/how-to-contribute.md create mode 100644 docs/en_us/deployment.md create mode 100644 docs/en_us/example/canary-release.md create mode 100644 docs/en_us/example/example.md create mode 100644 docs/en_us/ingress/basic.md create mode 100644 docs/en_us/ingress/conflict.md create mode 100644 docs/en_us/ingress/load-balance.md create mode 100644 docs/en_us/ingress/priority.md create mode 100644 docs/en_us/ingress/tls.md create mode 100644 docs/en_us/ingress/validate-state.md create mode 100644 docs/en_us/rbac.md create mode 100644 docs/images/qrcode_for_gh.jpg diff --git a/README-CN.md b/README-CN.md new file mode 100644 index 00000000..c43cec36 --- /dev/null +++ b/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开源项目”，及时获取项目最新信息和技术分享 + + + + + +
+ +- **开源BFE用户微信群**：扫码加入，探讨和分享对BFE的建议、使用心得、疑问等 + + + + + +
+ +- **开源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" diff --git a/README.md b/README.md index 84ea2b33..99c436bd 100644 --- a/README.md +++ b/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" diff --git a/docs/en_us/FAQ/FAQ.md b/docs/en_us/FAQ/FAQ.md new file mode 100644 index 00000000..e496c896 --- /dev/null +++ b/docs/en_us/FAQ/FAQ.md @@ -0,0 +1,21 @@ +# 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
-n | Null | Specifies in which namespaces the BFE Ingress Controller will monitor Ingress, seperate multiple namespaces by `,`.
Default value means monitor all namespaces | +| --ingress-class| bfe | Specifies the `kubernetes.io/ingress.class` value of Ingress it monitors.
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`.
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. Example： +```yaml +... + containers: + - name: bfe-ingress-controller + image: bfenetworks/bfe-ingress-controller:latest + args: ["-n", "ns1,ns2", "--default-backend", "test/whoami"] +... +``` diff --git a/docs/en_us/README.md b/docs/en_us/README.md new file mode 100644 index 00000000..2156f19f --- /dev/null +++ b/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" + diff --git a/docs/en_us/SUMMARY.md b/docs/en_us/SUMMARY.md new file mode 100644 index 00000000..47a6552f --- /dev/null +++ b/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/zh_cn/development/release_regulation/) + diff --git a/docs/en_us/contribute/contribute-codes.md b/docs/en_us/contribute/contribute-codes.md new file mode 100644 index 00000000..b5442982 --- /dev/null +++ b/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` . + + Notice：commit message is also required to trigger CI unit test，format as below: + + ```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/zh_cn/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/ \ No newline at end of file diff --git a/docs/en_us/contribute/contribute-documents.md b/docs/en_us/contribute/contribute-documents.md new file mode 100644 index 00000000..36cd0bbe --- /dev/null +++ b/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/zh_cn/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/ + diff --git a/docs/en_us/contribute/how-to-contribute.md b/docs/en_us/contribute/how-to-contribute.md new file mode 100644 index 00000000..7eace66c --- /dev/null +++ b/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/zh_cn/development/release_regulation/) + diff --git a/docs/en_us/deployment.md b/docs/en_us/deployment.md new file mode 100644 index 00000000..bd939425 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/en_us/example/canary-release.md b/docs/en_us/example/canary-release.md new file mode 100644 index 00000000..efaba18e --- /dev/null +++ b/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` diff --git a/docs/en_us/example/example.md b/docs/en_us/example/example.md new file mode 100644 index 00000000..f0f2ef5a --- /dev/null +++ b/docs/en_us/example/example.md @@ -0,0 +1,18 @@ +# Config File Example + +## deployment +| Program | File | Description | +| ---- | ---- | ---- | +| 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 +| File | Description | +| ---- | ---- | +| [ingress.yaml](../../../examples/ingress.yaml) | to config route for traffic to example service `whoami` | + +## rbac +| File | Description | +| ---- | ---- | +| [rbac.yaml](../../../examples/rbac.yaml) | to config access control for Bfe Ingress Controller | + diff --git a/docs/en_us/ingress/basic.md b/docs/en_us/ingress/basic.md new file mode 100644 index 00000000..b2336547 --- /dev/null +++ b/docs/en_us/ingress/basic.md @@ -0,0 +1,195 @@ +# 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][] . + +Refer to [ingress.yaml](../../deploy/ingress.yaml) when configuring Ingress resources in yaml files. + +## Example +### Simple example +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + name: simple-ingress +spec: + rules: + - host: whoami.com + http: + paths: + - path: /testpath + pathType: Prefix + backend: + service: + name: whoami + port: + number: 80 +``` +Above example defined a Ingress resource, and + +- set `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: + - hostname is `whoami.com` + + - path has prefix `/testpath` + +### Complicated example +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + name: complex-ingress + namespace: my-namespace + annotations: + bfe.ingress.kubernetes.io/loadbalance: '{"foo": {"sub-foo1":80, "sub-foo2":20}}' + bfe.ingress.kubernetes.io/router.cookie: "Session: 123" + bfe.ingress.kubernetes.io/router.header: "Content-Language: zh-cn" +spec: + tls: + - hosts: + - foo.com + secretName: secret-foo-com + rules: + - host: foo.com + http: + paths: + - path: /foo + pathType: Prefix + backend: + service: + name: foo + port: + number: 80 + - path: /bar + pathType: Exact + backend: + service: + name: bar + 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. + +- 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). + + - hostname is `foo.com` + - path has prefix `/foo` + - value of a Cookie named `Session` is `123` + - value of a Header named `Content-Language` is `zh-cn` + +- Route rule 2：a request will be forwarded to port 80 of service`bar` , if it matches all below conditions. + - hostname is `foo.com` + - path has prefix `/bar` + - value of a cookie named `Session` is `123` + - value of a header named `Content-Language` is `zh-cn` + + +## Condition of route rules + +### Hostname condition(host) + +Specified by `host` in a rule + +BFE Ingress Controller support [Kubernetes defined hostname conditions][hostname-wildcards]. + +### Path condition(path) +Specified by `path` and `pathType` in a rule + +BFE Ingress Controller support below pathType： + +- Prefix: prefix match. +- Exact: exact match +- ImplementationSpecific: __default__，implemented by BFE Ingress Controller as prefix match + +### Advanced match condition + +#### Introduction + +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. + +Currently BFE Ingress Controller support two advanced conditions types: cookie and header. + +#### Cookie + +Format： +``` yaml +bfe.ingress.kubernetes.io/router.cookie: "key: value" +``` + +Explanation： + +Requests containing a cookie with name=`key` and value=`value` are considered match this condition. + +#### Header + +Format： + +``` yaml +bfe.ingress.kubernetes.io/router.header: "key: value" +``` + +Explanation： + +Requests containing a header with name=`key` and value=`value` are considered match this condition. + +#### Restriction + +- 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. + + ```yaml + # example + annotation: + bfe.ingress.kubernetes.io/router.header: "key1: value1" # not take effect + bfe.ingress.kubernetes.io/router.header: "key2: value2" # takes effect + ``` + +## Ingress class + +BFE Ingress Controller support user to configure ingress class in two ways: + +### Set in annotations + +Set `kubernetes.io/ingress.class` in annotations of Ingress. Default value is `bfe` + +```yaml + annotations: + kubernetes.io/ingress.class: bfe +``` + +### Set in IngressClass + +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 +kind: IngressClass +metadata: + name: external-lb + controller: bfe-networks.com/ingress-controller +``` + +Then set `ingressClassName` to `external-lb` in Ingress: + +```yaml +apiVersion: "networking.k8s.io/v1beta1" +kind: "Ingress" +metadata: + name: "example-ingress" +spec: + ingressClassName: "external-lb" +... +``` + +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 + diff --git a/docs/en_us/ingress/conflict.md b/docs/en_us/ingress/conflict.md new file mode 100644 index 00000000..36180e93 --- /dev/null +++ b/docs/en_us/ingress/conflict.md @@ -0,0 +1,66 @@ +# 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. + +## 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. + +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 [validate state writeback](validate-state.md) `annotations`. + +## Example + +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + name: ingress-A + namespace: production +spec: + rules: + - host: example.foo.com + http: + paths: + - path: /foo + pathType: Prefix + backend: + serviceName: service1 + servicePort: 80 +--- +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + name: ingress-B + namespace: production +spec: + rules: + - host: example.foo.com + http: + paths: + - path: /foo + pathType: Prefix + backend: + serviceName: service2 + 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. + +## 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. + +In previous example, validate state `annotation` will be like: + + +```yaml +metadata: + annotations: + bfe.ingress.kubernetes.io/bfe-ingress-status: | + {"status": "fail", "message": "conflict with production/ingress-A"} +``` + +For more information about validate state, refer to [Validate state](validate-state.md)。 + diff --git a/docs/en_us/ingress/load-balance.md b/docs/en_us/ingress/load-balance.md new file mode 100644 index 00000000..8c91fb00 --- /dev/null +++ b/docs/en_us/ingress/load-balance.md @@ -0,0 +1,47 @@ +# 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`. + +## Configuration + +BFE Ingress Controller use `Annotation` to support load-balancing between multiple Sub-Services： + +- in `annotations` + + - config weight for each Sub-Service. + + - define a `Service` name for the service they provided together： + + ``` yaml + bfe.ingress.kubernetes.io/balance.weight: '{"service": {"sub-service1":80, "sub-service2":20}}' + ``` + +- in `rules` + + - config the `serviceName` of `backend` as the `Service` name in `Annotation`, and config the `servicePort`. + +## Example + +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + name: tls-example-ingress + annotations: + bfe.ingress.kubernetes.io/balance.weight: '{"service": {"service1":80, "service2":20}}' +spec: + tls: + - hosts: + - https-example.foo.com + secretName: testsecret-tls + rules: + - host: https-example.foo.com + http: + paths: + - path: / + pathType: Prefix + backend: + serviceName: service + servicePort: 80 +``` \ No newline at end of file diff --git a/docs/en_us/ingress/priority.md b/docs/en_us/ingress/priority.md new file mode 100644 index 00000000..2aa04cbe --- /dev/null +++ b/docs/en_us/ingress/priority.md @@ -0,0 +1,155 @@ +# Priority of route rules +If a request matches multiple ingress rules, BFE Ingress Controller will decide + +当请求能匹配到多条Ingress规则时，BFE Ingress Controller会按照以下优先级策略来选择规则： + +- 根据主机名，优先选择主机名匹配更精确的规则； +- 主机名相同时，优先选择路径匹配更精确的规则； +- 主机名、路径均相同时，优先选择高级匹配条件更多的规则； +- 主机名、路径、高级匹配条件个数均相同时，优先选择高级匹配条件的优先级更高的规则； + - 对于高级匹配条件，Cookie的优先级高于Header； + +## 优先级示例 +### 主机名精确优先 +```yaml +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "host_priority1" + namespace: production + +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service1 + servicePort: 80 +--- +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "host_priority2" + namespace: production + +spec: + rules: + - host: *.net + http: + paths: + - path: /bar + backend: + serviceName: service2 + servicePort: 80 +``` +在以上示例中，针对`curl "http://example.net/bar"`产生的请求，优先匹配规则`host_priority1` + +### 主机名相同，路径匹配精确优先 +```yaml +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "path_priority1" + namespace: production + +spec: + rules: + - host: example.net + http: + paths: + - path: /bar/foo + backend: + serviceName: service1 + servicePort: 80 +--- +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "path_priority2" + namespace: production + bfe.ingress.kubernetes.io/router.header: "key: value" +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service2 + servicePort: 80 +``` +在以上示例中，针对`curl "http://example.net/bar/foo" -H "Key: value"`产生的请求，优先匹配规则`path_priority1` + +### 主机名、路径均相同，高级匹配条件个数优先 +```yaml +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "cond_priority1" + namespace: production + bfe.ingress.kubernetes.io/router.header: "key: value" +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service1 + servicePort: 80 +--- +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "cond_priority1" + namespace: production +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service2 + servicePort: 80 +``` +在以上示例中，针对`curl "http://example.net/bar/foo" -H "Key: value"`产生的请求，优先匹配规则`cond_priority1` + +### 主机名、路径、高级匹配条件个数均相同，按高级匹配条件的优先级排序 +```yaml +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "multi_cond_priority1" + namespace: production + bfe.ingress.kubernetes.io/router.header: "header-key: value" +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service1 + servicePort: 80 +--- +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "multi_cond_priority2" + namespace: production + bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service2 + servicePort: 80 +``` +在以上示例中，针对`curl "http://example.net/bar/foo" -H "Header-key: value" --cookie "cookie-key: value"`产生的请求，优先匹配规则`multi_cond_priority2`，因为`Cookie`的优先级高于`Header`的优先级。 + diff --git a/docs/en_us/ingress/tls.md b/docs/en_us/ingress/tls.md new file mode 100644 index 00000000..d53cf043 --- /dev/null +++ b/docs/en_us/ingress/tls.md @@ -0,0 +1,39 @@ +# TLS 配置 +BFE Ingress Controller按照Kubernetes原生定义的方式来管理TLS的证书和密钥 + +TLS的证书和密钥通过Secrets进行保存，示例如下： + +**Secret配置** + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: testsecret-tls + namespace: default +data: + tls.crt: base64 encoded cert + tls.key: base64 encoded key +type: kubernetes.io/tls +``` +**Ingress配置** +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + name: tls-example-ingress +spec: + tls: + - hosts: + - https-example.foo.com + secretName: testsecret-tls + rules: + - host: https-example.foo.com + http: + paths: + - path: / + pathType: Prefix + backend: + serviceName: service1 + servicePort: 80 +``` diff --git a/docs/en_us/ingress/validate-state.md b/docs/en_us/ingress/validate-state.md new file mode 100644 index 00000000..eb908fa9 --- /dev/null +++ b/docs/en_us/ingress/validate-state.md @@ -0,0 +1,86 @@ +# 生效状态 + +## 生效状态回写 +Ingress配置的合法性检查是一个异步过程，检查结果在配置生效的过程中才能返回。为了能给用户反馈当前Ingress是否生效，BFE Ingress Controller会将Ingress的实际生效状态回写到Ingress的一个Annotation当中。 +**BFE Ingress Controller的状态Annotation定义如下：** + +```yaml +#bfe.ingress.kubernetes.io/bfe-ingress-status为BFE-Ingress预留的Annotation key， +#用于BFE-Ingress回写状态 +# status; 表示当前ingress是否合法， 取值为：success -> ingress合法， error -> ingress不合法 +# message; 当ingress不合法的情况下，message记录错误详细原因。 +bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "", "message": ""} +``` +## 示例 + +下面是BFE-Ingress生效状态回写的一个示例，展示发生路由冲突的两个Ingress资源的生效状态回写。 +`Ingress1`和`Ingress2`的路由规则完全一样(`Host:example.net, Path:/bar`)。 + +```yaml +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "ingress1" + namespace: production +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service1 + servicePort: 80 +--- +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "ingress2" + namespace: production +spec: + rules: + - host: example.net + http: + paths: + - path: /foo + backend: + serviceName: service2 + servicePort: 80 +``` +根据路由冲突时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 +```yaml +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "ingress1" + namespace: production + annotations: + bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success", "message": ""} +spec: + rules: + - host: example.net + http: + paths: + - path: /bar + backend: + serviceName: service1 + servicePort: 80 +--- +kind: Ingress +apiVersion: networking.k8s.io/v1beta1 +metadata: + name: "ingress2" + namespace: production + annotations: + bfe.ingress.kubernetes.io/bfe-ingress-status: | + {"status": "fail", "message": "conflict with production/ingress1"} +spec: + rules: + - host: example.net + http: + paths: + - path: /foo + backend: + serviceName: service2 + servicePort: 80 +``` \ No newline at end of file diff --git a/docs/en_us/rbac.md b/docs/en_us/rbac.md new file mode 100644 index 00000000..c1f41987 --- /dev/null +++ b/docs/en_us/rbac.md @@ -0,0 +1,65 @@ +# Role-Based Access Control (RBAC) + +## Introduction + +This document describe how to deploy BFE Ingress Controller in a environment with RBAC enabled. + +Kubernetes use [Role-based access control](https://kubernetes.io/docs/reference/access-authn-authz/rbac/), and define below objects： + +- Define 'role', to set permissions for the role： + - `ClusterRole` - to define permissions of a role which is cluster-wide + - `Role` - to define permissions of a role which belongs to specific namespace + +- Define role binding, to grant permissions defined in a role to a user or set of users: + - `ClusterRoleBinding` , to grant permissions defined in `ClusterRole` to user + - `RoleBinding` , to grant permissions defined in `Role` to user + +To deploy a BFE Ingress Controller instance in a environment with RBAC enabled, use the `ServiceAccount` that binded to a `ClusterRole`, which has been granted with all permissions BFE Ingress Controller required. + +## Minimum permission set + +BFE Ingress Controller required at least below permissions： + +- permissions defined for a ClusterRole： + + ```yaml + services, endpoints, secrets, namespaces: get, list, watch + ingresses, ingressclasses: get, list, watch, update + ``` + +## Example + +### Example config files + +[controller.yaml](../../examples/controller.yaml) + +[rbac.yaml](../../examples/rbac.yaml) + +### Define and refer ServiceAccount + +In [controller.yaml](../../examples/controller.yaml) ： + +- define a `ServiceAccount` , + - name it as `bfe-ingress-controller` +- define a BFE Ingress Controller instance deployment + - Instance deployed should liked to ServiceAccount `bfe-ingress-controller` + +### Define ClusterRole + +In [rbac.yaml](../../examples/rbac.yaml) ： +- define a `ClusterRole`, + - name it as `bfe-ingress-controller` + - grant below cluster-wide permissions to it： + + ```yaml + services, endpoints, secrets, namespaces: get, list, watch + ingresses, ingressclasses: get, list, watch, update + ``` + +### Bind ClusterRole + +In [rbac.yaml](../../examples/rbac.yaml) ： + +- define a `ClusterRoleBinding`, + - bind ServiceAccount `bfe-ingress-controller` to ClusterRole `bfe-ingress-controller` + diff --git a/docs/images/qrcode_for_gh.jpg b/docs/images/qrcode_for_gh.jpg new file mode 100644 index 0000000000000000000000000000000000000000..f17ebad4f0ea180c4ade93020d0f64c9a567393c GIT binary patch literal 29049 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 literal 0 HcmV?d00001 diff --git a/docs/zh_cn/ingress/basic.md b/docs/zh_cn/ingress/basic.md index f9093afc..ca4a1bab 100644 --- a/docs/zh_cn/ingress/basic.md +++ b/docs/zh_cn/ingress/basic.md @@ -1,7 +1,9 @@ # 配置指南 ## 概述 -通过配置K8S Ingress资源，可以定义K8S集群中的服务对外暴露的规则。更多Ingress相关信息，可参考[Ingress介绍]。 +通过配置K8S Ingress资源，可以定义K8S集群中的服务对外暴露时的流量路由规则。更多Ingress相关信息，可参考[Ingress介绍]。 + +我们提供了配置文件示例 [ingress.yaml](../../deploy/ingress.yaml)，可供配置时参考。 ## Ingress示例 ### 示例1 @@ -25,10 +27,10 @@ spec: port: number: 80 ``` -上述示例设置`kubernetes.io/ingress.class`为`bfe`，标识该Ingress由BFE Ingress Controller处理。 +上述示例中定义了一个 Ingress 资源 -设置请求的域名为 `whoami.com`，路径前缀为 `/testpath`。 -符合条件的流量将被转发给服务`whoami`的80端口处理。 +- 设置`kubernetes.io/ingress.class`为`bfe`，标识该Ingress由BFE Ingress Controller处理。 +- 定义了一条简单的路由规则：若请求流量的域名为 `whoami.com`，路径前缀为 `/testpath`，则将流量转发给`whoami` Service 的80端口处理 ### 示例2 ```yaml @@ -83,14 +85,14 @@ spec: ## Ingress中路由的匹配条件 -### host条件 +### 主机名条件(host) 由规则(rules)中的`host`字段指定 BFE Ingress Controller支持[Kubernetes原生定义的host匹配][hostname-wildcards] -### path条件 +### 路径条件(path) 由规则(rules)中的`path`和`pathType`字段指定 BFE Ingress Controller支持如下三种pathType： @@ -103,7 +105,7 @@ BFE Ingress Controller支持如下三种pathType： BFE Ingress Controller支持以annotation的方式设置高级匹配条件。目前支持cookie和header两种高级匹配条件。 -一个Ingress的所有路由规则，都会受该Ingress的annotaiton中定义的高级匹配条件的约束。 +高级匹配条件在Ingress资源内共享，即同一个Ingress资源内的所有规则，都会受高级匹配条件的约束。 #### cookie diff --git a/docs/zh_cn/ingress/conflict.md b/docs/zh_cn/ingress/conflict.md index b9ed4566..b81f1651 100644 --- a/docs/zh_cn/ingress/conflict.md +++ b/docs/zh_cn/ingress/conflict.md @@ -1,11 +1,16 @@ # 路由冲突处理 -## 创建时间优先原则 -当用户的Ingress配置最终生成相同的Ingress规则的情况下（Host、Path、高级匹配条件均完全相同），会产生路由冲突，BFE Ingress Controller将按照`创建时间优先`的原则使用先配置的路由规则。 +## 路由冲突的定义 + +当Ingress配置最终生成包含相同的Ingress规则（Host、Path、高级匹配条件均完全相同）的Ingress资源的情况下，会产生路由冲突。 + +## 处理原则：最先创建的生效 + +对存在路由冲突的多个Ingress资源，BFE Ingress Controller将按照"最先创建的生效"的原则，仅使最早被创建的Ingress资源生效。 在同一个namespace之间，或在多个namespace之间的路由冲突，均按照此原则处理。 -对于因路由冲突导致的配置生成失败，可在[生效状态](validate-state.md)回写的Annotation中查找相应的错误消息。 +对于因路由冲突导致的没有在BFE Ingress Controller中生效的Ingress资源，可在[生效状态](validate-state.md)反馈的Annotation中查找相应的错误消息。 ## 示例 @@ -15,8 +20,6 @@ kind: Ingress metadata: name: ingress-A namespace: production - annotations: - kubernetes.io/ingress.class: bfe spec: rules: - host: example.foo.com @@ -33,8 +36,6 @@ kind: Ingress metadata: name: ingress-B namespace: production - annotations: - kubernetes.io/ingress.class: bfe spec: rules: - host: example.foo.com @@ -49,8 +50,8 @@ spec: ``` 在以上配置中，ingress-A和ingress-B冲突，ingress-A先于ingress-B创建，所以最终仅ingress-A生效。 -## 生效状态回写 -若一个Ingress资源因路由冲突而被忽略（未生效），状态回写后，对于生效状态的注解的status会被设为“fail”，message中会包含和哪个Ingress资源发生了冲突。 +## 生效状态反馈 +若一个Ingress资源因路由冲突而被忽略（未生效），生效状态反馈回写后，对于生效状态的注解的status会被设为“fail”，message中会包含和哪个Ingress资源发生了冲突。 在前面的示例中，ingress-B的生效状态的注解将会如下面所示： diff --git a/docs/zh_cn/ingress/load-balance.md b/docs/zh_cn/ingress/load-balance.md index a2cd78eb..719e1697 100644 --- a/docs/zh_cn/ingress/load-balance.md +++ b/docs/zh_cn/ingress/load-balance.md @@ -1,13 +1,13 @@ # 多Service之间的负载均衡 ## 说明 -BFE Ingress Controller支持在提供相同服务的多个Service（为便于理解，在文档中称其为子服务，Sub-Service）之间按权重进行负载均衡。 +BFE Ingress Controller支持在提供相同服务的多个Service（为便于理解，在BFE Ingress文档中称其为子服务，Sub-Service）之间按权重进行负载均衡。 配置方式 BFE Ingress Controller通过`注解`（`Annotation`）的方式支持多个Sub-Service之间的负载均衡。配置方式为： -- 在注解中 +- 在`annotations`中 - 为多个Sub-Service分别指定流量分配权重 @@ -19,7 +19,7 @@ BFE Ingress Controller通过`注解`（`Annotation`）的方式支持多个Sub-S bfe.ingress.kubernetes.io/balance.weight: '{"service": {"sub-service1":80, "sub-service2":20}}' ``` -- 在规则中 +- 在`rules`中 - 将backend的serviceName设置为注解中设置的Service名称，并指定servicePort @@ -31,7 +31,6 @@ kind: Ingress metadata: name: tls-example-ingress annotations: - kubernetes.io/ingress.class: bfe bfe.ingress.kubernetes.io/balance.weight: '{"service": {"service1":80, "service2":20}}' spec: tls: diff --git a/docs/zh_cn/ingress/priority.md b/docs/zh_cn/ingress/priority.md index fd533442..e4c00504 100644 --- a/docs/zh_cn/ingress/priority.md +++ b/docs/zh_cn/ingress/priority.md @@ -15,8 +15,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "host_priority1" namespace: production - annotations: - kubernetes.io/ingress.class: bfe + spec: rules: - host: example.net @@ -32,8 +31,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "host_priority2" namespace: production - annotations: - kubernetes.io/ingress.class: bfe + spec: rules: - host: *.net @@ -53,8 +51,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "path_priority1" namespace: production - annotations: - kubernetes.io/ingress.class: bfe + spec: rules: - host: example.net @@ -70,9 +67,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "path_priority2" namespace: production - annotations: - kubernetes.io/ingress.class: bfe - bfe.ingress.kubernetes.io/router.header: "key: value" + bfe.ingress.kubernetes.io/router.header: "key: value" spec: rules: - host: example.net @@ -92,9 +87,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "cond_priority1" namespace: production - annotations: - kubernetes.io/ingress.class: bfe - bfe.ingress.kubernetes.io/router.header: "key: value" + bfe.ingress.kubernetes.io/router.header: "key: value" spec: rules: - host: example.net @@ -110,8 +103,6 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "cond_priority1" namespace: production - annotations: - kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -131,9 +122,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "multi_cond_priority1" namespace: production - annotations: - kubernetes.io/ingress.class: bfe - bfe.ingress.kubernetes.io/router.header: "header-key: value" + bfe.ingress.kubernetes.io/router.header: "header-key: value" spec: rules: - host: example.net @@ -149,9 +138,7 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "multi_cond_priority2" namespace: production - annotations: - kubernetes.io/ingress.class: bfe - bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" + bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" spec: rules: - host: example.net diff --git a/docs/zh_cn/ingress/validate-state.md b/docs/zh_cn/ingress/validate-state.md index f9e0d89a..fdbba56f 100644 --- a/docs/zh_cn/ingress/validate-state.md +++ b/docs/zh_cn/ingress/validate-state.md @@ -1,22 +1,21 @@ # 生效状态 -## Ingress状态回写 +## 生效状态反馈 Ingress配置的合法性检查是一个异步过程，检查结果在配置生效的过程中才能返回。 -为了能给用户反馈当前Ingress是否生效，BFE Ingress Controller会将Ingress的实际生效状态回写到Ingress的Annotation当中。 - +为了能给用户反馈当前Ingress是否生效，BFE Ingress Controller会将Ingress的实际生效状态回写到Ingress的一个Annotation当中。 **BFE Ingress Controller的状态Annotation定义如下：** ```yaml #bfe.ingress.kubernetes.io/bfe-ingress-status为BFE-Ingress预留的Annotation key， -#用于BFE-Ingress回写状态 +#用于BFE-Ingress反馈生效状态 # status; 表示当前ingress是否合法， 取值为：success -> ingress合法， error -> ingress不合法 # message; 当ingress不合法的情况下，message记录错误详细原因。 bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "", "message": ""} ``` ## 示例 -下面是BFE-Ingress生效状态回写的一个示例，展示发生路由冲突的两个Ingress资源的生效状态回写。 +下面是BFE-Ingress生效状态反馈的一个示例，展示发生路由冲突的两个Ingress资源的生效状态反馈。 `Ingress1`和`Ingress2`的路由规则完全一样(`Host:example.net, Path:/bar`)。 ```yaml @@ -25,8 +24,6 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "ingress1" namespace: production - annotations: - kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -42,19 +39,17 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "ingress2" namespace: production - annotations: - kubernetes.io/ingress.class: bfe spec: rules: - host: example.net http: paths: - - path: /bar + - path: /foo backend: serviceName: service2 servicePort: 80 ``` -根据路由冲突时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 +根据路由冲突时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写反馈后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 @@ -62,8 +57,7 @@ metadata: name: "ingress1" namespace: production annotations: - kubernetes.io/ingress.class: bfe - bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success"} + bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success", "message": ""} spec: rules: - host: example.net @@ -80,7 +74,6 @@ metadata: name: "ingress2" namespace: production annotations: - kubernetes.io/ingress.class: bfe bfe.ingress.kubernetes.io/bfe-ingress-status: | {"status": "fail", "message": "conflict with production/ingress1"} spec: From acb7a96d42974c2127330464a2f8ae473f1cef4b Mon Sep 17 00:00:00 2001 From: clarinette9 Date: Sat, 23 Oct 2021 11:53:10 +0800 Subject: [PATCH 06/28] add english docs and update docs Signed-off-by: clarinette9 --- docs/en_us/contribute/contribute-codes.md | 2 +- docs/en_us/contribute/contribute-documents.md | 2 +- docs/en_us/contribute/how-to-contribute.md | 2 +- docs/en_us/ingress/basic.md | 4 +-- docs/en_us/ingress/conflict.md | 2 +- docs/en_us/ingress/tls.md | 11 ++++---- docs/en_us/ingress/validate-state.md | 27 ++++++++++--------- docs/zh_cn/ingress/validate-state.md | 2 +- 8 files changed, 28 insertions(+), 24 deletions(-) diff --git a/docs/en_us/contribute/contribute-codes.md b/docs/en_us/contribute/contribute-codes.md index b5442982..cf316f85 100644 --- a/docs/en_us/contribute/contribute-codes.md +++ b/docs/en_us/contribute/contribute-codes.md @@ -102,7 +102,7 @@ $ git push origin my-cool-stuff [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/zh_cn/development/release_regulation.md +[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/ \ No newline at end of file diff --git a/docs/en_us/contribute/contribute-documents.md b/docs/en_us/contribute/contribute-documents.md index 36cd0bbe..2c8a0754 100644 --- a/docs/en_us/contribute/contribute-documents.md +++ b/docs/en_us/contribute/contribute-documents.md @@ -7,7 +7,7 @@ 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/zh_cn/development/write_doc_guide/#_2) + - [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) diff --git a/docs/en_us/contribute/how-to-contribute.md b/docs/en_us/contribute/how-to-contribute.md index 7eace66c..935545fc 100644 --- a/docs/en_us/contribute/how-to-contribute.md +++ b/docs/en_us/contribute/how-to-contribute.md @@ -1,5 +1,5 @@ # Contribute - [Contribute Code](contribute-codes.md) - [Contribute Document](contribute-documents.md) -- [Release Regulation](https://www.bfe-networks.net/zh_cn/development/release_regulation/) +- [Release Regulation](https://www.bfe-networks.net/en_us/development/release_regulation/) diff --git a/docs/en_us/ingress/basic.md b/docs/en_us/ingress/basic.md index b2336547..0e9ada8c 100644 --- a/docs/en_us/ingress/basic.md +++ b/docs/en_us/ingress/basic.md @@ -3,7 +3,7 @@ ## 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][] . -Refer to [ingress.yaml](../../deploy/ingress.yaml) when configuring Ingress resources in yaml files. +Refer to [ingress.yaml](../../examples/ingress.yaml) when configuring Ingress resources in yaml files. ## Example ### Simple example @@ -92,7 +92,7 @@ Above Ingress resource defines 2 advanced route rule, and configure TLS certific Specified by `host` in a rule -BFE Ingress Controller support [Kubernetes defined hostname conditions][hostname-wildcards]. +BFE Ingress Controller support [hostname conditions][hostname-wildcards] defined by Kubernetes. ### Path condition(path) Specified by `path` and `pathType` in a rule diff --git a/docs/en_us/ingress/conflict.md b/docs/en_us/ingress/conflict.md index 36180e93..21aeb001 100644 --- a/docs/en_us/ingress/conflict.md +++ b/docs/en_us/ingress/conflict.md @@ -9,7 +9,7 @@ For those Ingress resources with route rule conflict, BFE Ingress Controller wil Route rule conflicts within a namespace or among different namespaces will both follow this principle. -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 [validate state writeback](validate-state.md) `annotations`. +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`. ## Example diff --git a/docs/en_us/ingress/tls.md b/docs/en_us/ingress/tls.md index d53cf043..b93f111d 100644 --- a/docs/en_us/ingress/tls.md +++ b/docs/en_us/ingress/tls.md @@ -1,9 +1,9 @@ -# TLS 配置 -BFE Ingress Controller按照Kubernetes原生定义的方式来管理TLS的证书和密钥 +# TLS Configuration +BFE Ingress Controller manage TLS certificates and secretes in the way defined by Kubernetes. -TLS的证书和密钥通过Secrets进行保存，示例如下： +TLS certificates and secretes are stored in `Secret`. See examples below: -**Secret配置** +**Config Secret** ```yaml apiVersion: v1 @@ -16,7 +16,8 @@ data: tls.key: base64 encoded key type: kubernetes.io/tls ``` -**Ingress配置** +**Config Ingress** + ```yaml apiVersion: networking.k8s.io/v1beta1 kind: Ingress diff --git a/docs/en_us/ingress/validate-state.md b/docs/en_us/ingress/validate-state.md index eb908fa9..39ef52f0 100644 --- a/docs/en_us/ingress/validate-state.md +++ b/docs/en_us/ingress/validate-state.md @@ -1,20 +1,23 @@ -# 生效状态 +# Validate State -## 生效状态回写 -Ingress配置的合法性检查是一个异步过程，检查结果在配置生效的过程中才能返回。为了能给用户反馈当前Ingress是否生效，BFE Ingress Controller会将Ingress的实际生效状态回写到Ingress的一个Annotation当中。 -**BFE Ingress Controller的状态Annotation定义如下：** +## Validate state response +Validating the Ingress config is an async process and the result can only be returned after resources applied. + +In order to response the result of whether the Ingress takes effect, BFE Ingress Controller will write the validate state of the Ingress back to its annotations. + +**BFE Ingress Controller defines the annotation for validate state as follow:** ```yaml -#bfe.ingress.kubernetes.io/bfe-ingress-status为BFE-Ingress预留的Annotation key， -#用于BFE-Ingress回写状态 -# status; 表示当前ingress是否合法， 取值为：success -> ingress合法， error -> ingress不合法 -# message; 当ingress不合法的情况下，message记录错误详细原因。 +#bfe.ingress.kubernetes.io/bfe-ingress-status is the reserved Annotation key of BFE Ingress Controller， +#used for validate state response +# status; indicate if this ingress is valid, value can be: success -> ingress is valid and takes effect， error -> ingress is not valid +# message; if ingress is not valid, error messages will be recoreded bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "", "message": ""} ``` -## 示例 +## Example -下面是BFE-Ingress生效状态回写的一个示例，展示发生路由冲突的两个Ingress资源的生效状态回写。 -`Ingress1`和`Ingress2`的路由规则完全一样(`Host:example.net, Path:/bar`)。 +Below example shows the validate state response of two ingress with route rules conflict +`Ingress1` and `Ingress2` have one identical route rule (`Host:example.net, Path:/bar`) ```yaml kind: Ingress @@ -47,7 +50,7 @@ spec: serviceName: service2 servicePort: 80 ``` -根据路由冲突时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 +According to conflict handling principle for [route rule conflict](conflict.md), `Ingress1` will take effect and `Ingress2` will be ignored. After validate state responsed, `status` of `Ingress1` will be "success" and for `Ingress2` it will be "fail". ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 diff --git a/docs/zh_cn/ingress/validate-state.md b/docs/zh_cn/ingress/validate-state.md index fdbba56f..959674fd 100644 --- a/docs/zh_cn/ingress/validate-state.md +++ b/docs/zh_cn/ingress/validate-state.md @@ -49,7 +49,7 @@ spec: serviceName: service2 servicePort: 80 ``` -根据路由冲突时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写反馈后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 +根据[路由冲突](conflict.md)时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写反馈后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 From 5f586b96feb248b05f294dc9dfc804b3fadd6239 Mon Sep 17 00:00:00 2001 From: clarinette9 Date: Sat, 23 Oct 2021 11:58:08 +0800 Subject: [PATCH 07/28] fix some links Signed-off-by: clarinette9 --- docs/en_us/FAQ/FAQ.md | 3 ++- docs/en_us/SUMMARY.md | 2 +- docs/zh_cn/FAQ/FAQ.md | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/en_us/FAQ/FAQ.md b/docs/en_us/FAQ/FAQ.md index e496c896..b03480c2 100644 --- a/docs/en_us/FAQ/FAQ.md +++ b/docs/en_us/FAQ/FAQ.md @@ -10,7 +10,8 @@ | --default-backend| Null | Specify name of default backend service, in the format of `namespace/name`.
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. Example： +Define in config file of BFE Ingress Controller, like [controller.yaml](../../../examples/controller.yaml). Example： + ```yaml ... containers: diff --git a/docs/en_us/SUMMARY.md b/docs/en_us/SUMMARY.md index 47a6552f..f761f376 100644 --- a/docs/en_us/SUMMARY.md +++ b/docs/en_us/SUMMARY.md @@ -21,5 +21,5 @@ * [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/zh_cn/development/release_regulation/) + * [Release Regulation](https://www.bfe-networks.net/en_us/development/release_regulation/) diff --git a/docs/zh_cn/FAQ/FAQ.md b/docs/zh_cn/FAQ/FAQ.md index da4f9fbe..64873313 100644 --- a/docs/zh_cn/FAQ/FAQ.md +++ b/docs/zh_cn/FAQ/FAQ.md @@ -10,7 +10,7 @@ | --default-backend| 空 | 指定default-backend服务的名字，格式为`namespace/name`。
如指定default-backend，没有命中任何Ingress规则的请求，将被转发到default-backend。 | 设置方式： -在BFE Ingress Controller的部署文件controller.yaml中指定。例如： +在BFE Ingress Controller的部署文件[controller.yaml](../../../examples/controller.yaml)中指定。例如： ```yaml ... containers: From da4416f8fd2ce0efa59b49ec0f019df496d84700 Mon Sep 17 00:00:00 2001 From: clarinette9 Date: Sat, 23 Oct 2021 12:56:51 +0800 Subject: [PATCH 08/28] update docs Signed-off-by: clarinette9 --- docs/en_us/ingress/conflict.md | 4 ++++ docs/en_us/ingress/load-balance.md | 1 + docs/en_us/ingress/priority.md | 30 ++++++++++++++++++++-------- docs/en_us/ingress/validate-state.md | 12 ++++++++--- docs/zh_cn/ingress/annotation.md | 27 ------------------------- docs/zh_cn/ingress/conflict.md | 4 ++++ docs/zh_cn/ingress/load-balance.md | 1 + docs/zh_cn/ingress/priority.md | 27 ++++++++++++++++++------- docs/zh_cn/ingress/validate-state.md | 12 ++++++++--- 9 files changed, 70 insertions(+), 48 deletions(-) delete mode 100644 docs/zh_cn/ingress/annotation.md diff --git a/docs/en_us/ingress/conflict.md b/docs/en_us/ingress/conflict.md index 21aeb001..3d37e6d9 100644 --- a/docs/en_us/ingress/conflict.md +++ b/docs/en_us/ingress/conflict.md @@ -19,6 +19,8 @@ kind: Ingress metadata: name: ingress-A namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.foo.com @@ -35,6 +37,8 @@ kind: Ingress metadata: name: ingress-B namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.foo.com diff --git a/docs/en_us/ingress/load-balance.md b/docs/en_us/ingress/load-balance.md index 8c91fb00..bc2f7505 100644 --- a/docs/en_us/ingress/load-balance.md +++ b/docs/en_us/ingress/load-balance.md @@ -29,6 +29,7 @@ kind: Ingress metadata: name: tls-example-ingress annotations: + kubernetes.io/ingress.class: bfe bfe.ingress.kubernetes.io/balance.weight: '{"service": {"service1":80, "service2":20}}' spec: tls: diff --git a/docs/en_us/ingress/priority.md b/docs/en_us/ingress/priority.md index 2aa04cbe..83ea8057 100644 --- a/docs/en_us/ingress/priority.md +++ b/docs/en_us/ingress/priority.md @@ -17,7 +17,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "host_priority1" namespace: production - + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -33,7 +34,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "host_priority2" namespace: production - + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: *.net @@ -53,7 +55,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "path_priority1" namespace: production - + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -69,7 +72,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "path_priority2" namespace: production - bfe.ingress.kubernetes.io/router.header: "key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.header: "key: value" spec: rules: - host: example.net @@ -89,7 +94,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "cond_priority1" namespace: production - bfe.ingress.kubernetes.io/router.header: "key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.header: "key: value" spec: rules: - host: example.net @@ -104,7 +111,10 @@ kind: Ingress apiVersion: networking.k8s.io/v1beta1 metadata: name: "cond_priority1" - namespace: production + namespace: production + annotations: + kubernetes.io/ingress.class: bfe + spec: rules: - host: example.net @@ -124,7 +134,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "multi_cond_priority1" namespace: production - bfe.ingress.kubernetes.io/router.header: "header-key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.header: "header-key: value" spec: rules: - host: example.net @@ -140,7 +152,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "multi_cond_priority2" namespace: production - bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" spec: rules: - host: example.net diff --git a/docs/en_us/ingress/validate-state.md b/docs/en_us/ingress/validate-state.md index 39ef52f0..02efdac6 100644 --- a/docs/en_us/ingress/validate-state.md +++ b/docs/en_us/ingress/validate-state.md @@ -25,6 +25,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "ingress1" namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -40,12 +42,14 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "ingress2" namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net http: paths: - - path: /foo + - path: /bar backend: serviceName: service2 servicePort: 80 @@ -58,7 +62,8 @@ metadata: name: "ingress1" namespace: production annotations: - bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success", "message": ""} + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success"} spec: rules: - host: example.net @@ -75,6 +80,7 @@ metadata: name: "ingress2" namespace: production annotations: + kubernetes.io/ingress.class: bfe bfe.ingress.kubernetes.io/bfe-ingress-status: | {"status": "fail", "message": "conflict with production/ingress1"} spec: @@ -82,7 +88,7 @@ spec: - host: example.net http: paths: - - path: /foo + - path: /bar backend: serviceName: service2 servicePort: 80 diff --git a/docs/zh_cn/ingress/annotation.md b/docs/zh_cn/ingress/annotation.md deleted file mode 100644 index 2cf3c8a7..00000000 --- a/docs/zh_cn/ingress/annotation.md +++ /dev/null @@ -1,27 +0,0 @@ -# Annotation - -## 用途 -BFE Ingress Controller支持通过Annotation配置高级规则。目前支持`Cookie`和`Header`两种，格式和优先级如下: - -## Cookie -- 优先级：0 -``` yaml -bfe.ingress.kubernetes.io/router.cookie: "key: value" -``` -BFE将执行 `req.Cookies["Key"]==value` 的判断 - -## Header -- 优先级：1 -``` yaml -bfe.ingress.kubernetes.io/router.header: "key: value" -``` -BFE将执行 `req.Headers["Key"]==value` 的判断 - -## 注意 -- 一个类型的Annotation下仅支持设置一个值； - ```yaml - annotation: - bfe.ingress.kubernetes.io/router.header: "key1: value1" # 不生效 - bfe.ingress.kubernetes.io/router.header: "key2: value2" # 生效 - ``` -- 优先级数越小，其优先级越高 \ No newline at end of file diff --git a/docs/zh_cn/ingress/conflict.md b/docs/zh_cn/ingress/conflict.md index b81f1651..e885c02e 100644 --- a/docs/zh_cn/ingress/conflict.md +++ b/docs/zh_cn/ingress/conflict.md @@ -20,6 +20,8 @@ kind: Ingress metadata: name: ingress-A namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.foo.com @@ -36,6 +38,8 @@ kind: Ingress metadata: name: ingress-B namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.foo.com diff --git a/docs/zh_cn/ingress/load-balance.md b/docs/zh_cn/ingress/load-balance.md index 719e1697..a2383dd2 100644 --- a/docs/zh_cn/ingress/load-balance.md +++ b/docs/zh_cn/ingress/load-balance.md @@ -31,6 +31,7 @@ kind: Ingress metadata: name: tls-example-ingress annotations: + kubernetes.io/ingress.class: bfe bfe.ingress.kubernetes.io/balance.weight: '{"service": {"service1":80, "service2":20}}' spec: tls: diff --git a/docs/zh_cn/ingress/priority.md b/docs/zh_cn/ingress/priority.md index e4c00504..68d96e2a 100644 --- a/docs/zh_cn/ingress/priority.md +++ b/docs/zh_cn/ingress/priority.md @@ -15,7 +15,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "host_priority1" namespace: production - + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -31,7 +32,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "host_priority2" namespace: production - + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: *.net @@ -51,7 +53,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "path_priority1" namespace: production - + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -67,7 +70,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "path_priority2" namespace: production - bfe.ingress.kubernetes.io/router.header: "key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.header: "key: value" spec: rules: - host: example.net @@ -87,7 +92,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "cond_priority1" namespace: production - bfe.ingress.kubernetes.io/router.header: "key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.header: "key: value" spec: rules: - host: example.net @@ -103,6 +110,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "cond_priority1" namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -122,7 +131,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "multi_cond_priority1" namespace: production - bfe.ingress.kubernetes.io/router.header: "header-key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.header: "header-key: value" spec: rules: - host: example.net @@ -138,7 +149,9 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "multi_cond_priority2" namespace: production - bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" + annotations: + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/router.cookie: "cookie-key: value" spec: rules: - host: example.net diff --git a/docs/zh_cn/ingress/validate-state.md b/docs/zh_cn/ingress/validate-state.md index 959674fd..27059d43 100644 --- a/docs/zh_cn/ingress/validate-state.md +++ b/docs/zh_cn/ingress/validate-state.md @@ -24,6 +24,8 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "ingress1" namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net @@ -39,12 +41,14 @@ apiVersion: networking.k8s.io/v1beta1 metadata: name: "ingress2" namespace: production + annotations: + kubernetes.io/ingress.class: bfe spec: rules: - host: example.net http: paths: - - path: /foo + - path: /bar backend: serviceName: service2 servicePort: 80 @@ -57,7 +61,8 @@ metadata: name: "ingress1" namespace: production annotations: - bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success", "message": ""} + kubernetes.io/ingress.class: bfe + bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "success"} spec: rules: - host: example.net @@ -74,6 +79,7 @@ metadata: name: "ingress2" namespace: production annotations: + kubernetes.io/ingress.class: bfe bfe.ingress.kubernetes.io/bfe-ingress-status: | {"status": "fail", "message": "conflict with production/ingress1"} spec: @@ -81,7 +87,7 @@ spec: - host: example.net http: paths: - - path: /foo + - path: /bar backend: serviceName: service2 servicePort: 80 From f7578e2067922491ae482200c310b5cd55aeae52 Mon Sep 17 00:00:00 2001 From: clarinette9 Date: Sat, 23 Oct 2021 13:31:49 +0800 Subject: [PATCH 09/28] translate priority.md Signed-off-by: clarinette9 --- docs/en_us/ingress/priority.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/en_us/ingress/priority.md b/docs/en_us/ingress/priority.md index 83ea8057..e8d4ebb1 100644 --- a/docs/en_us/ingress/priority.md +++ b/docs/en_us/ingress/priority.md @@ -1,16 +1,14 @@ # Priority of route rules -If a request matches multiple ingress rules, BFE Ingress Controller will decide +If a request matches multiple ingress rules, BFE Ingress Controller will decide which rule will be hit according to below strategies: -当请求能匹配到多条Ingress规则时，BFE Ingress Controller会按照以下优先级策略来选择规则： +- Compares 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 + - in advanced match condition, Cookie condition has higher priority than Header condition； -- 根据主机名，优先选择主机名匹配更精确的规则； -- 主机名相同时，优先选择路径匹配更精确的规则； -- 主机名、路径均相同时，优先选择高级匹配条件更多的规则； -- 主机名、路径、高级匹配条件个数均相同时，优先选择高级匹配条件的优先级更高的规则； - - 对于高级匹配条件，Cookie的优先级高于Header； - -## 优先级示例 -### 主机名精确优先 +## Examples +### Hostname precision first ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 @@ -46,9 +44,9 @@ spec: serviceName: service2 servicePort: 80 ``` -在以上示例中，针对`curl "http://example.net/bar"`产生的请求，优先匹配规则`host_priority1` +In above example, for requests generated by `curl "http://example.net/bar"`, rule in `host_priority1` will be hit -### 主机名相同，路径匹配精确优先 +### Path precision first when hostname are identical ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 @@ -85,9 +83,9 @@ spec: serviceName: service2 servicePort: 80 ``` -在以上示例中，针对`curl "http://example.net/bar/foo" -H "Key: value"`产生的请求，优先匹配规则`path_priority1` +In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Key: value"`, rule in `path_priority1` will be hit -### 主机名、路径均相同，高级匹配条件个数优先 +### More matched advanced condition first, when hostname and path both identical ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 @@ -125,9 +123,9 @@ spec: serviceName: service2 servicePort: 80 ``` -在以上示例中，针对`curl "http://example.net/bar/foo" -H "Key: value"`产生的请求，优先匹配规则`cond_priority1` +In above example, for requests generated by `curl "http://example.net/bar/foo" -H "Key: value"`, rule in `cond_priority1` will be hit -### 主机名、路径、高级匹配条件个数均相同，按高级匹配条件的优先级排序 +### Matched advanced condition with higher priority first, when above criteria are the same ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 @@ -165,5 +163,5 @@ spec: serviceName: service2 servicePort: 80 ``` -在以上示例中，针对`curl "http://example.net/bar/foo" -H "Header-key: value" --cookie "cookie-key: value"`产生的请求，优先匹配规则`multi_cond_priority2`，因为`Cookie`的优先级高于`Header`的优先级。 +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 From 51c3660f471b72c6f75b41b3e384946ce71da962 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 14:42:42 +0800 Subject: [PATCH 10/28] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 99c436bd..5f0bf1e7 100644 --- a/README.md +++ b/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" From 999f82c06c47ee3a3b58a37a31b252717308d5f7 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 14:46:50 +0800 Subject: [PATCH 11/28] Update README-CN.md --- README-CN.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README-CN.md b/README-CN.md index c43cec36..efafda10 100644 --- a/README-CN.md +++ b/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) ## 社区交流 From 00d7957a7788791ed41d48078f7f575f80393f10 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 15:07:24 +0800 Subject: [PATCH 12/28] Update deployment.md --- docs/en_us/deployment.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/en_us/deployment.md b/docs/en_us/deployment.md index bd939425..6a9cc5c0 100644 --- a/docs/en_us/deployment.md +++ b/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 \ No newline at end of file + - Refer to [Summary](SUMMARY.md) for more Ingress configuration options that BFE Ingress Controller support. From 5f5832fd761afd9176ffab31f8f27eee4e66ba8e Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 15:10:53 +0800 Subject: [PATCH 13/28] Update deployment.md --- docs/zh_cn/deployment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/zh_cn/deployment.md b/docs/zh_cn/deployment.md index dec7de05..ec3a1db0 100644 --- a/docs/zh_cn/deployment.md +++ b/docs/zh_cn/deployment.md @@ -6,7 +6,7 @@ kubectl apply -f controller.yaml ``` - 配置文件示例[controller.yaml](../../examples/controller.yaml) - - 配置文件中使用了Docker Hub 上的[BFE Ingress Controller]:latest镜像。如需使用指定版本的镜像，修改配置文件，指定镜像版本。 + - 配置文件中使用了[Docker Hub 上的BFE Ingress Controller的最新镜像](https://hub.docker.com/r/bfenetworks/bfe-ingress-controller)。如需使用指定版本的镜像，修改配置文件，指定镜像版本。 - 也可在项目根目录下执行`make docker`，创建自己的本地镜像。 * 配置所需权限 @@ -32,4 +32,4 @@ - 基本的Ingess配置可参考 [ingress.yaml](../../examples/ingress.yaml)。 - 更多的BFE Ingress Controller所支持的Ingress配置，可参考配置[相关文档](SUMMARY.md)。 -[BFE Ingress Controller]: https://hub.docker.com/r/bfenetworks/bfe-ingress-controller + From 37fead39560d4b0c5e5f5b62415aae746ce2a228 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 15:24:24 +0800 Subject: [PATCH 14/28] Update rbac.md --- docs/en_us/rbac.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en_us/rbac.md b/docs/en_us/rbac.md index c1f41987..69c1ea85 100644 --- a/docs/en_us/rbac.md +++ b/docs/en_us/rbac.md @@ -2,7 +2,7 @@ ## Introduction -This document describe how to deploy BFE Ingress Controller in a environment with RBAC enabled. +This document describe how to deploy BFE Ingress Controller in an environment with RBAC enabled. Kubernetes use [Role-based access control](https://kubernetes.io/docs/reference/access-authn-authz/rbac/), and define below objects： @@ -10,11 +10,11 @@ Kubernetes use [Role-based access control](https://kubernetes.io/docs/reference/ - `ClusterRole` - to define permissions of a role which is cluster-wide - `Role` - to define permissions of a role which belongs to specific namespace -- Define role binding, to grant permissions defined in a role to a user or set of users: +- Define 'role binding', to grant permissions defined in a role to a user or set of users: - `ClusterRoleBinding` , to grant permissions defined in `ClusterRole` to user - `RoleBinding` , to grant permissions defined in `Role` to user -To deploy a BFE Ingress Controller instance in a environment with RBAC enabled, use the `ServiceAccount` that binded to a `ClusterRole`, which has been granted with all permissions BFE Ingress Controller required. +To deploy a BFE Ingress Controller instance in an environment with RBAC enabled, use the `ServiceAccount` that binded to a `ClusterRole`, which has been granted with all permissions BFE Ingress Controller required. ## Minimum permission set @@ -42,14 +42,14 @@ In [controller.yaml](../../examples/controller.yaml) ： - define a `ServiceAccount` , - name it as `bfe-ingress-controller` - define a BFE Ingress Controller instance deployment - - Instance deployed should liked to ServiceAccount `bfe-ingress-controller` + - Instance deployed should be linked to ServiceAccount `bfe-ingress-controller` ### Define ClusterRole In [rbac.yaml](../../examples/rbac.yaml) ： - define a `ClusterRole`, - name it as `bfe-ingress-controller` - - grant below cluster-wide permissions to it： + - grant cluster-wide permissions below to it： ```yaml services, endpoints, secrets, namespaces: get, list, watch From dee70325f4bf1bbe299ed1aaf3c293cc096f16ef Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 16:39:27 +0800 Subject: [PATCH 15/28] Update basic.md --- docs/en_us/ingress/basic.md | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/en_us/ingress/basic.md b/docs/en_us/ingress/basic.md index 0e9ada8c..d7057aff 100644 --- a/docs/en_us/ingress/basic.md +++ b/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 From 3bc04a954472cb5423ff07d2872792977445105f Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:15:09 +0800 Subject: [PATCH 16/28] Update validate-state.md --- docs/zh_cn/ingress/validate-state.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/zh_cn/ingress/validate-state.md b/docs/zh_cn/ingress/validate-state.md index 27059d43..4684c2a2 100644 --- a/docs/zh_cn/ingress/validate-state.md +++ b/docs/zh_cn/ingress/validate-state.md @@ -9,8 +9,8 @@ Ingress配置的合法性检查是一个异步过程，检查结果在配置生 ```yaml #bfe.ingress.kubernetes.io/bfe-ingress-status为BFE-Ingress预留的Annotation key， #用于BFE-Ingress反馈生效状态 -# status; 表示当前ingress是否合法， 取值为：success -> ingress合法， error -> ingress不合法 -# message; 当ingress不合法的情况下，message记录错误详细原因。 +# status: 表示当前ingress是否合法， 取值为：success -> ingress合法， error -> ingress不合法 +# message: 当ingress不合法的情况下，message记录错误详细原因。 bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "", "message": ""} ``` ## 示例 @@ -91,4 +91,4 @@ spec: backend: serviceName: service2 servicePort: 80 -``` \ No newline at end of file +``` From 3e1b5d991ceed9cd4a84ef9926a46977e56975c5 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:20:47 +0800 Subject: [PATCH 17/28] Update validate-state.md --- docs/zh_cn/ingress/validate-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/zh_cn/ingress/validate-state.md b/docs/zh_cn/ingress/validate-state.md index 4684c2a2..00d03870 100644 --- a/docs/zh_cn/ingress/validate-state.md +++ b/docs/zh_cn/ingress/validate-state.md @@ -53,7 +53,7 @@ spec: serviceName: service2 servicePort: 80 ``` -根据[路由冲突](conflict.md)时的配置规则，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写反馈后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 +根据[路由冲突处理原则](conflict.md)，`Ingress1`将生效，而`Ingress2`将被忽略。状态回写反馈后，`Ingress1`的状态为success，而`Ingress2`的状态为fail。 ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 From 18fe56cd4232a0fe7a48b4d204ba7749f87b1030 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:23:09 +0800 Subject: [PATCH 18/28] Update validate-state.md --- docs/en_us/ingress/validate-state.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/en_us/ingress/validate-state.md b/docs/en_us/ingress/validate-state.md index 02efdac6..4aa7a25e 100644 --- a/docs/en_us/ingress/validate-state.md +++ b/docs/en_us/ingress/validate-state.md @@ -1,22 +1,22 @@ -# Validate State +# Ingress status -## Validate state response -Validating the Ingress config is an async process and the result can only be returned after resources applied. +## Feedback for ingress status +The validation of the Ingress configuration is an asynchronous process. The status can only be returned after the configuation has taken effect. -In order to response the result of whether the Ingress takes effect, BFE Ingress Controller will write the validate state of the Ingress back to its annotations. +In order to provide feedback for ingress status, BFE Ingress Controller will write status back to its annotations. -**BFE Ingress Controller defines the annotation for validate state as follow:** +**BFE Ingress Controller defines the annotation for status as follow:** ```yaml -#bfe.ingress.kubernetes.io/bfe-ingress-status is the reserved Annotation key of BFE Ingress Controller， -#used for validate state response -# status; indicate if this ingress is valid, value can be: success -> ingress is valid and takes effect， error -> ingress is not valid -# message; if ingress is not valid, error messages will be recoreded +#bfe.ingress.kubernetes.io/bfe-ingress-status is the reserved Annotation key of BFE Ingress Controller +#used for status feedback. +# status: success -> ingress is valid, error -> ingress is invalid. +# message: if ingress is invalid, error messages will be recorded bfe.ingress.kubernetes.io/bfe-ingress-status: {"status": "", "message": ""} ``` ## Example -Below example shows the validate state response of two ingress with route rules conflict +The following example shows the status of two ingresses with route rules conflict. `Ingress1` and `Ingress2` have one identical route rule (`Host:example.net, Path:/bar`) ```yaml @@ -54,7 +54,7 @@ spec: serviceName: service2 servicePort: 80 ``` -According to conflict handling principle for [route rule conflict](conflict.md), `Ingress1` will take effect and `Ingress2` will be ignored. After validate state responsed, `status` of `Ingress1` will be "success" and for `Ingress2` it will be "fail". +According to [principles of handling route rule conflict](conflict.md), `Ingress1` will take effect and `Ingress2` will be ignored. After the status is returned, `status` of `Ingress1` will be "success" and status of `Ingress2` it will be "fail". ```yaml kind: Ingress apiVersion: networking.k8s.io/v1beta1 @@ -92,4 +92,4 @@ spec: backend: serviceName: service2 servicePort: 80 -``` \ No newline at end of file +``` From 98c967c79a3d26ca4d254ae5890fa5f546d27865 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:25:50 +0800 Subject: [PATCH 19/28] Update SUMMARY.md --- docs/en_us/SUMMARY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en_us/SUMMARY.md b/docs/en_us/SUMMARY.md index f761f376..16997db4 100644 --- a/docs/en_us/SUMMARY.md +++ b/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 From 4479c7e154d8179ff452b4c6f4e1555c241a1a6f Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:42:12 +0800 Subject: [PATCH 20/28] Update conflict.md --- docs/en_us/ingress/conflict.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/en_us/ingress/conflict.md b/docs/en_us/ingress/conflict.md index 3d37e6d9..6db823ea 100644 --- a/docs/en_us/ingress/conflict.md +++ b/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)。 From 63f01ed9bd1576d65914865ead6719d63123ba9a Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:51:38 +0800 Subject: [PATCH 21/28] Update priority.md --- docs/en_us/ingress/priority.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/en_us/ingress/priority.md b/docs/en_us/ingress/priority.md index e8d4ebb1..5bd46c0c 100644 --- a/docs/en_us/ingress/priority.md +++ b/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. From 04f15e056800ab555271e89fc80c1825875a0090 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:53:23 +0800 Subject: [PATCH 22/28] Update tls.md --- docs/en_us/ingress/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en_us/ingress/tls.md b/docs/en_us/ingress/tls.md index b93f111d..6d16aa01 100644 --- a/docs/en_us/ingress/tls.md +++ b/docs/en_us/ingress/tls.md @@ -1,5 +1,5 @@ # 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: From feb37e9a08dd24d44e8254fbf07b0e7ea0aa97e9 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 17:54:36 +0800 Subject: [PATCH 23/28] Update load-balance.md --- docs/en_us/ingress/load-balance.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en_us/ingress/load-balance.md b/docs/en_us/ingress/load-balance.md index bc2f7505..d478b07c 100644 --- a/docs/en_us/ingress/load-balance.md +++ b/docs/en_us/ingress/load-balance.md @@ -1,7 +1,7 @@ # 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 @@ -9,7 +9,7 @@ BFE Ingress Controller use `Annotation` to support load-balancing between multip - in `annotations` - - config weight for each Sub-Service. + - configurate weight for each Sub-Service. - define a `Service` name for the service they provided together： @@ -45,4 +45,4 @@ spec: backend: serviceName: service servicePort: 80 -``` \ No newline at end of file +``` From 8e894f9ee5262e4579cb80fcfdf7c493b1fa07ba Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 19:08:20 +0800 Subject: [PATCH 24/28] Update load-balance.md --- docs/en_us/ingress/load-balance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en_us/ingress/load-balance.md b/docs/en_us/ingress/load-balance.md index d478b07c..40a71871 100644 --- a/docs/en_us/ingress/load-balance.md +++ b/docs/en_us/ingress/load-balance.md @@ -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 From d3e18979bff913fb66823e719a32a4daad9c3b26 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 19:14:51 +0800 Subject: [PATCH 25/28] Update example.md --- docs/en_us/example/example.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en_us/example/example.md b/docs/en_us/example/example.md index f0f2ef5a..fa2d6345 100644 --- a/docs/en_us/example/example.md +++ b/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 | From f0feff52b7b0f69dc173c8554720afb8a93bd834 Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 19:34:04 +0800 Subject: [PATCH 26/28] Update canary-release.md --- docs/en_us/example/canary-release.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en_us/example/canary-release.md b/docs/en_us/example/canary-release.md index efaba18e..d1f22728 100644 --- a/docs/en_us/example/canary-release.md +++ b/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` From d8dc87b7c81b7c35493468213559d0e46bfa1bad Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 19:47:45 +0800 Subject: [PATCH 27/28] Update tls.md --- docs/en_us/ingress/tls.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en_us/ingress/tls.md b/docs/en_us/ingress/tls.md index 6d16aa01..c820cbd8 100644 --- a/docs/en_us/ingress/tls.md +++ b/docs/en_us/ingress/tls.md @@ -3,7 +3,7 @@ BFE Ingress Controller manages TLS certificates and secretes in the way defined 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 From 7b15d653a0b87837a38cdd0869e8a98dca6d025e Mon Sep 17 00:00:00 2001 From: Miles Zhang Date: Mon, 25 Oct 2021 19:54:06 +0800 Subject: [PATCH 28/28] Update FAQ.md --- docs/en_us/FAQ/FAQ.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en_us/FAQ/FAQ.md b/docs/en_us/FAQ/FAQ.md index b03480c2..e64a9140 100644 --- a/docs/en_us/FAQ/FAQ.md +++ b/docs/en_us/FAQ/FAQ.md @@ -5,8 +5,8 @@ |Argument | Default value | Description| | --- | --- | --- | -| --namespace
-n | Null | Specifies in which namespaces the BFE Ingress Controller will monitor Ingress, seperate multiple namespaces by `,`.
Default value means monitor all namespaces | -| --ingress-class| bfe | Specifies the `kubernetes.io/ingress.class` value of Ingress it monitors.
If not specified, BFE Ingress Controller monitors the Ingress with ingress class set as bfe. Usually you don't need to specify it. | +| --namespace
-n | Null | Specify in which namespaces BFE Ingress Controller will monitor Ingress. Multiple namespaces are seperated by `,`.
Default value means to monitor all namespaces. | +| --ingress-class| bfe | Specify the `kubernetes.io/ingress.class` value of Ingress it monitors.
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`.
If specified, requests that match no Ingress rule will be forwarded to the service specified. | How to define：