Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

polish documents for ingress-bfe #25

Merged
merged 19 commits into from
Oct 25, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

## 社区交流

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
4 changes: 2 additions & 2 deletions docs/en_us/FAQ/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@

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

How to define:
Expand Down
4 changes: 2 additions & 2 deletions docs/en_us/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 3 additions & 5 deletions docs/en_us/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand All @@ -38,6 +38,4 @@

- Refer to [ingress.yaml](../../examples/ingress.yaml) for basic Ingress configuration.

- More Ingress configuration options that BFE Ingress Controller support, refer to [Configuration](SUMMARY.md).

[BFE Ingress Controller]: https://hub.docker.com/r/bfenetworks/bfe-ingress-controller
- Refer to [Summary](SUMMARY.md) for more Ingress configuration options that BFE Ingress Controller support.
18 changes: 9 additions & 9 deletions docs/en_us/example/canary-release.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand All @@ -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`
6 changes: 3 additions & 3 deletions docs/en_us/example/example.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 |

30 changes: 14 additions & 16 deletions docs/en_us/ingress/basic.md
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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
16 changes: 8 additions & 8 deletions docs/en_us/ingress/conflict.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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)。

8 changes: 4 additions & 4 deletions docs/en_us/ingress/load-balance.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Load banlancing between Services
## Introduction

For `Service`s that providing the same service (called Sub-Services), BFE Ingress Controller support load balancing between them, based on weight configured for each `Service`.
For `Service`s that providing the same service (called Sub-Services), BFE Ingress Controller supports load balancing between them, based on weight configured for each `Service`.

## Configuration

BFE Ingress Controller use `Annotation` to support load-balancing between multiple Sub-Services:

- in `annotations`

- config weight for each Sub-Service.
- configurate weight for each Sub-Service.

- define a `Service` name for the service they provided together:

Expand All @@ -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

Expand All @@ -45,4 +45,4 @@ spec:
backend:
serviceName: service
servicePort: 80
```
```
14 changes: 7 additions & 7 deletions docs/en_us/ingress/priority.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

6 changes: 3 additions & 3 deletions docs/en_us/ingress/tls.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# TLS Configuration
BFE Ingress Controller manage TLS certificates and secretes in the way defined by Kubernetes.
BFE Ingress Controller manages TLS certificates and secretes in the way defined by Kubernetes.

TLS certificates and secretes are stored in `Secret`. See examples below:

**Config Secret**
**Configurate Secret**

```yaml
apiVersion: v1
Expand All @@ -16,7 +16,7 @@ data:
tls.key: base64 encoded key
type: kubernetes.io/tls
```
**Config Ingress**
**Configurate Ingress**

```yaml
apiVersion: networking.k8s.io/v1beta1
Expand Down
Loading