This is an automated email from the ASF dual-hosted git repository.
kvn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new bde42f4 doc: new layout (#279)
bde42f4 is described below
commit bde42f49a7deadb4420eb1d99cb6d34a0b3282f9
Author: Alex Zhang <[email protected]>
AuthorDate: Thu Mar 4 17:54:06 2021 +0800
doc: new layout (#279)
* doc: new layout
* fix
---
README.md | 2 +-
docs/en/latest/CRD-specification.md | 362 ---------------------
docs/en/latest/concepts/apisix_route.md | 149 +++++++++
docs/en/latest/concepts/apisix_upstream.md | 195 +++++++++++
docs/en/latest/config.json | 31 +-
docs/en/latest/deployments/ack.md | 2 +-
docs/en/latest/deployments/aws.md | 2 +-
docs/en/latest/deployments/azure.md | 2 +-
docs/en/latest/deployments/gke.md | 2 +-
docs/en/latest/deployments/k3s-rke.md | 2 +-
docs/en/latest/deployments/kubesphere.md | 2 +-
docs/en/latest/deployments/minikube.md | 2 +-
docs/en/latest/deployments/tke.md | 2 +-
docs/en/latest/get-started.md | 66 ++++
docs/en/latest/{samples => practices}/index.md | 0
.../proxy-the-httpbin-service-with-ingress.md | 0
.../proxy-the-httpbin-service.md | 0
docs/en/latest/reference/apisix_route_v1.md | 39 +++
.../apisix_route_v2alpha1.md} | 7 +-
.../{samples/index.md => reference/apisix_tls.md} | 12 +-
docs/en/latest/reference/apisix_upstream.md | 68 ++++
docs/en/latest/usage.md | 112 -------
install.md | 2 +-
23 files changed, 557 insertions(+), 504 deletions(-)
diff --git a/README.md b/README.md
index 0651d1c..6cd40e4 100644
--- a/README.md
+++ b/README.md
@@ -97,7 +97,7 @@ Get more [implementation details](./docs/en/latest/design.md).
## Documents
-* [Usage](./docs/en/latest/usage.md)
+* [Get Started](docs/en/latest/get-started.md)
* [SDK doc](./docs/en/latest/development.md)
* [Design introduction](./docs/en/latest/design.md)
diff --git a/docs/en/latest/CRD-specification.md
b/docs/en/latest/CRD-specification.md
deleted file mode 100644
index a277568..0000000
--- a/docs/en/latest/CRD-specification.md
+++ /dev/null
@@ -1,362 +0,0 @@
----
-title: CRD specification
----
-
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-In order to control the behavior of the proxy ([Apache
APISIX](https://github.com/apache/apisix)), the following CRDs should be
defined.
-
-## CRD Types
-
-- [CRD Types](#crd-types)
-- [ApisixRoute](#apisixroute)
-- [ApisixUpstream](#apisixupstream)
- - [Configuring Load Balancer](#configuring-load-balancer)
- - [Configuring Health Check](#configuring-health-check)
- - [Configuring Retry and Timeout](#configuring-retry-and-timeout)
- - [Port Level Settings](#port-level-settings)
- - [Configuration References](#configuration-references)
-- [ApisixTls](#apisixtls)
-
-## ApisixRoute
-
-`ApisixRoute` corresponds to the `Route` object in Apache APISIX. The `Route`
matches the client's request by defining rules,
-then loads and executes the corresponding plugin based on the matching result,
and forwards the request to the specified Upstream.
-To learn more, please check the [Apache APISIX architecture-design
docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#route).
-
-Structure example:
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixRoute
-metadata:
- name: httpserverRoute
- namespace: cloud
-spec:
- rules:
- - host: test.apisix.apache.org
- http:
- paths:
- - backend:
- serviceName: httpserver
- servicePort: 8080
- path: /hello*
- plugins:
- - name: limit-count
- enable: true
- config:
- count: 2
- time_window: 60
- rejected_code: 503
- key: remote_addr
-```
-
-| Field | Type | Description
|
-|---------------|----------|----------------------------------------------------|
-| rules | array | ApisixRoute's request matching rules.
|
-| host | string | The requested host.
|
-| http | object | Route rules are applied to the scope of layer 7
traffic. |
-| paths | array | Path-based `route` rule matching.
|
-| backend | object | Backend service information configuration.
|
-| serviceName | string | The name of backend service. `namespace +
serviceName + servicePort` form an unique identifier to match the back-end
service. |
-| servicePort | int | The port of backend service. `namespace +
serviceName + servicePort` form an unique identifier to match the back-end
service. |
-| path | string | The URI matched by the route. Supports exact
match and prefix match. Example，exact match: `/hello`, prefix match: `/hello*`.
|
-| plugins | array | Custom plugin collection (Plugins defined in the
`route` level). For more plugin information, please refer to the [Apache APISIX
plugin docs](https://github.com/apache/apisix/tree/master/doc/plugins). |
-| name | string | The name of the plugin. For more information
about the example plugin, please check the [limit-count
docs](https://github.com/apache/apisix/blob/master/doc/plugins/limit-count.md#Attributes).
|
-| enable | boolean | Whether to enable the plugin, `true`: means
enable, `false`: means disable. |
-| config | object | Configuration of plugin information. Note: The
check of configuration schema is missing now, so please be careful when
editing. |
-
-**Support partial `annotation`**
-
-Structure example:
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixRoute
-metadata:
- annotations:
- k8s.apisix.apache.org/ingress.class: apisix_group
- k8s.apisix.apache.org/ssl-redirect: 'false'
- k8s.apisix.apache.org/whitelist-source-range:
- - 1.2.3.4/16
- - 4.3.2.1/8
- name: httpserverRoute
- namespace: cloud
-spec:
-```
-
-| Field | Type |
Description |
-|------------------------------------------------|------------|--------------------------------------------------------------------|
-| `k8s.apisix.apache.org/ssl-redirect` | boolean | Whether to
force http redirect to https. `ture`: means to force conversion to https,
`false`: means not to convert. |
-| `k8s.apisix.apache.org/ingress.class` | string | Grouping of
ingress. |
-| `k8s.apisix.apache.org/whitelist-source-range` | array | Whitelist of
IPs allowed to be accessed. |
-
-## ApisixUpstream
-
-ApisixUpstream is the decorator of Kubernetes Service. It's designed to have
same name with its target Kubernetes Service, it makes the Kubernetes Service
richer by adding
-load balancing, health check, retry, timeout parameters and etc.
-
-Resort to `ApisixUpstream` and the Kubernetes Service, apisix ingress
controller will generates the APISIX Upstream(s).
-To learn more, please check the [Apache APISIX architecture-design
docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#upstream).
-
-### Configuring Load Balancer
-
-A proper load balancing algorithm is required to scatter requests reasonably
for a Kubernetes Service.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: httpbin
-spec:
- loadbalancer:
- type: ewma
----
-apiVersion: v1
-kind: Service
-metadata:
- name: httpbin
-spec:
- selector:
- app: httpbin
- ports:
- - name: http
- port: 80
- targetPort: 8080
-```
-
-The above example shows that
[ewma](https://linkerd.io/2016/03/16/beyond-round-robin-load-balancing-for-latency/)
is used as the load balancer for Service `httpbin`.
-
-Sometimes the session sticky is desired, and you can use the [Consistent
Hashing](https://en.wikipedia.org/wiki/Consistent_hashing) load balancing
algorithm.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: httpbin
-spec:
- loadbalancer:
- type: chash
- hashOn: header
- key: "user-agent"
-```
-
-With the above settings, Apache APISIX will distributes requests according to
the User-Agent header.
-
-### Configuring Health Check
-
-Although Kubelet already provides
[probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#:~:text=The%20kubelet%20uses%20readiness%20probes,removed%20from%20Service%20load%20balancers.)
to detect whether pods are healthy, you may still need more powerful health
check mechanism,
-like the passive feedback capability.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: httpbin
-spec:
- healthCheck:
- passive:
- unhealthy:
- httpCodes:
- - 500
- - 502
- - 503
- - 504
- httpFailures: 3
- timeout: 5s
- active:
- type: http
- httpPath: /healthz
- timeout: 5s
- host: www.foo.com
- healthy:
- successes: 3
- interval: 2s
- httpCodes:
- - 200
- - 206
-```
-
-The above YAML snippet defines a passive health checker to detect the
unhealthy state for
-endpoints, once there are three consecutive requests with bad status code (one
of `500`, `502`, `503`, `504`), the endpoint
-will be set to unhealthy and no requests can be routed there until it's
healthy again.
-
-That's why the active health checker comes in, endpoints might be down for a
short while and ready again, the active health checker detects these unhealthy
endpoints continuously, and pull them
-up once the healthy conditions are met (three consecutive requests got good
status codes, e.g. `200` and `206`).
-
-Note the active health checker is somewhat duplicated with the
liveness/readiness probes but it's required if the passive feedback mechanism
is in use. So once you use the health check feature in ApisixUpstream,
-the active health checker is mandatory.
-
-### Configuring Retry and Timeout
-
-You may want the proxy to retry when requests occur faults like transient
network errors
-or service unavailable, by default the retry count is `1`. You can change it
by specifying the `retries` field.
-
-The following configuration configures the `retries` to `3`, which indicates
there'll be at most `3` requests sent to
-Kubernetes service `httpbin`'s endpoints.
-
-One should bear in mind that passing a request to the next endpoint is only
possible
-if nothing has been sent to a client yet. That is, if an error or timeout
occurs in the middle
-of the transferring of a response, fixing this is impossible.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: httpbin
-spec:
- retries: 3
-```
-
-The default connect, read and send timeout are `60s`, which might not proper
for some applications,
-just change them in the `timeout` field.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: httpbin
-spec:
- timeout:
- connect: 5s
- read: 10s
- send: 10s
-```
-
-The above examples sets the connect, read and timeout to `5s`, `10s`, `10s`
respectively.
-
-### Port Level Settings
-
-Once in a while a single Kubernetes Service might expose multiple ports which
provides distinct functions and different Upstream configurations are required.
-In that case, you can create configurations for individual port.
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: foo
-spec:
- loadbalancer:
- type: roundrobin
- portLevelSettings:
- - port: 7000
- scheme: http
- - port: 7001
- scheme: grpc
----
-apiVersion: v1
-kind: Service
-metadata:
- name: foo
-spec:
- selector:
- app: foo
- portLevelSettings:
- - name: http
- port: 7000
- targetPort: 7000
- - name: grpc
- port: 7001
- targetPort: 7001
-```
-
-The `foo` service exposes two ports, one of them use HTTP protocol and the
other uses grpc protocol.
-In the meanwhile, the ApisixUpstream `foo` sets `http` scheme for port `7000`
and `grpc` scheme for `7001`
-(all ports are the service port). But both ports shares the load balancer
configuration.
-
-`PortLevelSettings` is not mandatory if the service only exposes one port but
is useful when multiple ports are defined.
-
-### Configuration References
-
-| Field | Type | Description |
-|---------------|----------|----------------|
-| scheme | string | The protocol used to talk to the Service, can be
`http`, `grpc`, default is `http`. |
-| loadbalancer | object | The load balancing algorithm of this upstream
service |
-| loadbalancer.type | string | The load balancing type, can be `roundrobin`,
`ewma`, `least_conn`, `chash`, default is `roundrobin`. |
-| loadbalancer.hashOn | string | The hash value source scope, only take
effects if the `chash` algorithm is in use. Values can `vars`, `header`,
`vars_combinations`, `cookie` and `consumers`, default is `vars`. |
-| loadbalancer.key | string | The hash key, only in valid if the `chash`
algorithm is used.
-| retries | int | The retry count. |
-| timeout | object | The timeout settings. |
-| timeout.connect | time duration in the form "72h3m0.5s" | The connect
timeout. |
-| timeout.read | time duration in the form "72h3m0.5s" | The read timeout. |
-| timeout.send | time duration in the form "72h3m0.5s" | The send timeout. |
-| healthCheck | object | The health check parameters, see [Health
Check](https://github.com/apache/apisix/blob/master/doc/health-check.md) for
more details. |
-| healthCheck.active | object | active health check configuration, which is a
mandatory field. |
-| healthCheck.active.type | string | health check type, can be `http`, `https`
and `tcp`, default is `http`. |
-| healthCheck.active.timeout | time duration in the form "72h3m0.5s" | the
timeout settings for the probe, default is `1s`. |
-| healthCheck.active.concurrency | int | how many probes can be sent
simultaneously, default is `10`. |
-| healthCheck.active.host | string | host header in http probe request, only
in valid if the active health check type is `http` or `https`. |
-| healthCheck.active.port | int | target port to receive probes, it's
necessary to specify this field if the health check service exposes by
different port, note the port value here is the container port, not the service
port. |
-| healthCheck.active.httpPath | string | the HTTP URI path in http probe, only
in valid if the active health check type is `http` or `https`. |
-| healthCheck.active.strictTLS | boolean | whether to use the strict mode when
use TLS, only in valid if the active health check type is `https`, default is
`true`. |
-| healthCheck.active.requestHeaders | array of string | Extra HTTP requests
carried in the http probe, only in valid if the active health check type is
`http` or `https`. |
-| healthCheck.active.healthy | object | The conditions to judge an endpoint is
healthy. |
-| healthCheck.active.healthy.successes | int | The number of consecutive
requests needed to set an endpoint as healthy, default is `2`. |
-| healthCheck.active.healthy.httpCodes | array of integer | Good status codes
list to check whether a probe is successful, only in valid if the active health
check type is `http` or `https`, default is `[200, 302]`. |
-| healthCheck.active.healthy.interval | time duration in the form "72h3m0.5s"
| The probes sent interval (for healthy endpoints). |
-| healthCheck.active.unhealthy | object | The conditions to judge an endpoint
is unhealthy. |
-| healthCheck.active.unhealthy.httpFailures | int | The number of consecutive
http requests needed to set an endpoint as unhealthy, only in valid if the
active health check type is `http` or `https`, default is `5`. |
-| healthCheck.active.unhealthy.tcpFailures | int | The number of consecutive
tcp connections needed to set an endpoint as unhealthy, only in valid if the
active health check type is `tcp`, default is `2`. |
-| healthCheck.active.unhealthy.httpCodes | array of integer | Bad status codes
list to check whether a probe is failed, only in valid if the active health
check type is `http` or `https`, default is `[429, 404, 500, 501, 502, 503,
504, 505]`. |
-| healthCheck.active.unhealthy.interval | time duration in the form
"72h3m0.5s" | The probes sent interval (for unhealthy endpoints). |
-| healthCheck.passive | object | passive health check configuration, which is
an optional field. |
-| healthCheck.passive.type | string | health check type, can be `http`,
`https` and `tcp`, default is `http`. |
-| healthCheck.passive.healthy | object | The conditions to judge an endpoint
is healthy. |
-| healthCheck.passive.healthy.successes | int | The number of consecutive
requests needed to set an endpoint as healthy, default is `5`. |
-| healthCheck.passive.healthy.httpCodes | array of integer | Good status codes
list to check whether a probe is successful, only in valid if the active health
check type is `http` or `https`, default is `[200, 201, 202, 203, 204, 205,
206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]`. |
-| healthCheck.passive.unhealthy | object | The conditions to judge an endpoint
is unhealthy. |
-| healthCheck.passive.unhealthy.httpFailures | int | The number of consecutive
http requests needed to set an endpoint as unhealthy, only in valid if the
active health check type is `http` or `https`, default is `5`. |
-| healthCheck.passive.unhealthy.tcpFailures | int | The number of consecutive
tcp connections needed to set an endpoint as unhealthy, only in valid if the
active health check type is `tcp`, default is `2`. |
-| healthCheck.passive.unhealthy.httpCodes | array of integer | Bad status
codes list to check whether a probe is failed, only in valid if the active
health check type is `http` or `https`, default is `[429, 404, 500, 501, 502,
503, 504, 505]`. |
-| portLevelSettings | array | Settings for each individual port. |
-| portLevelSettings.port | int | The port number defined in the Kubernetes
Service, must be a valid port. |
-| portLevelSettings.scheme | string | same as `scheme` but takes higher
precedence. |
-| portLevelSettings.loadbalancer | object | same as `loadbalancer` but takes
higher precedence. |
-| portLevelSettings.healthCheck | object | same as `healthCheck` but takes
higher precedence. |
-
-## ApisixTls
-
-`ApisixTls` corresponds to the SSL load matching route in Apache APISIX.
-To learn more, please check the [Apache APISIX architecture-design
docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#router).
-
-Structure example:
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixSSL
-metadata:
- name: duiopen
-spec：
- hosts:
- - asr.duiopen.com
- - tts.duiopen.com
- secret:
- name: all.duiopen.com
- namespace: cloud
-```
-
-| Field | Type | Description |
-|---------------|----------|---------------------------------|
-| hosts | array | The domain list to identify which hosts (matched
with SNI) can use the TLS certificate stored in the Secret. |
-| secret | object | The definition of the related Secret object with
current ApisixTls object. |
-| name | string | The name of secret, the secret contains key and
cert for `TLS`. |
-| namespace | string | The namespace of secret, the secret contains key
and cert for `TLS`. |
-
-[Back to top](#crd-types)
diff --git a/docs/en/latest/concepts/apisix_route.md
b/docs/en/latest/concepts/apisix_route.md
new file mode 100644
index 0000000..1e678ca
--- /dev/null
+++ b/docs/en/latest/concepts/apisix_route.md
@@ -0,0 +1,149 @@
+---
+title: ApisixRoute
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+`ApisixRoute` is a CRD resource which focus on how to route traffic to
+expected backend, it exposes many features supported by Apache APISIX.
+Compared to
[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/),
+functions are implemented in a more native way, with stronger semantics.
+
+Path based route rules
+----------------------
+
+URI path are always used to split traffic, for instance, requests with host
`foo.com` and
+`/foo` prefix should be routed to service `foo` while requests which path is
`/bar`
+should be routed to service `bar`, in the manner of `ApisixRoute`, the
configuration
+should be:
+
+```yaml
+apiVersion: apisix.apache.org/v2alpha1
+kind: ApisixRoute
+metadata:
+ name: foor-bar-route
+spec:
+ http:
+ - name: foo
+ match:
+ hosts:
+ - foo.com
+ paths:
+ - "/foo*"
+ backend:
+ serviceName: foo
+ servicePort: 80
+ - name: bar
+ match:
+ paths:
+ - "/bar"
+ backend:
+ serviceName: bar
+ servicePort: 80
+```
+
+There are two path types can be used, `prefix` and `exact`, default is `exact`,
+while if `prefix` is desired, just append a `*`, for instance, `/id/*` matches
+all paths with the prefix of `/id/`.
+
+Advanced route features
+-----------------------
+
+Path based route are most common, but if it's not enough, try
+other route features in `ApisixRoute` such as `methods`, `nginxVars`.
+
+The `methods` splits traffic according to the HTTP method, the following
configurations routes requests
+with `GET` method to `foo` service (a Kubernetes Service).
+
+```yaml
+apiVersion: apisix.apache.org/v2alpha1
+kind: ApisixRoute
+metadata:
+ name: method-route
+spec:
+ http:
+ - name: method
+ match:
+ paths:
+ - /
+ methods:
+ - GET
+ backend:
+ serviceName: foo
+ servicePort: 80
+```
+
+Service Resolution Granularity
+------------------------------
+
+By default a referenced Service will be watched, so
+it's newest endpoints list can be updated to Apache APISIX.
+apisix-ingress-controller provides another mechanism that just use
+the `ClusterIP` of this service, if that's what you want, just set
+the `resolveGranularity` to `service` (default is `endpoint`).
+
+```yaml
+apiVersion: apisix.apache.org/v2alpha1
+kind: ApisixRoute
+metadata:
+ name: method-route
+spec:
+ http:
+ - name: method
+ match:
+ paths:
+ - /*
+ methods:
+ - GET
+ backend:
+ serviceName: foo
+ servicePort: 80
+ resolveGranularity: service
+```
+
+Plugins
+-------
+
+Apache APISIX provides more than 40
[plugins](https://github.com/apache/apisix/tree/master/docs/en/latest/plugins),
which can be used
+in `ApisixRoute`. All configuration items are named same to the one in APISIX.
+
+```yaml
+apiVersion: apisix.apache.org/v2alpha1
+kind: ApisixRoute
+metadata:
+ name: httpbin-route
+spec:
+ http:
+ - name: httpbin
+ match:
+ hosts:
+ - local.httpbin.org
+ paths:
+ - /*
+ backend:
+ serviceName: foo
+ servicePort: 80
+ plugins:
+ - name: cors
+ enable: true
+```
+
+The above configuration enables
[Cors](https://github.com/apache/apisix/blob/master/docs/en/latest/plugins/cors.md)
plugin for requests
+which host is `local.httpbin.org`.
diff --git a/docs/en/latest/concepts/apisix_upstream.md
b/docs/en/latest/concepts/apisix_upstream.md
new file mode 100644
index 0000000..33fbbc5
--- /dev/null
+++ b/docs/en/latest/concepts/apisix_upstream.md
@@ -0,0 +1,195 @@
+---
+title: ApisixUpstream
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+ApisixUpstream is the decorator of Kubernetes Service. It's designed to have
same name with its target Kubernetes Service, it makes the Kubernetes Service
richer by adding
+load balancing, health check, retry, timeout parameters and etc.
+
+Resort to `ApisixUpstream` and the Kubernetes Service, apisix ingress
controller will generates the APISIX Upstream(s).
+To learn more, please check the [Apache APISIX architecture-design
docs](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#upstream).
+
+### Configuring Load Balancer
+
+A proper load balancing algorithm is required to scatter requests reasonably
for a Kubernetes Service.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: httpbin
+spec:
+ loadbalancer:
+ type: ewma
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: httpbin
+spec:
+ selector:
+ app: httpbin
+ ports:
+ - name: http
+ port: 80
+ targetPort: 8080
+```
+
+The above example shows that
[ewma](https://linkerd.io/2016/03/16/beyond-round-robin-load-balancing-for-latency/)
is used as the load balancer for Service `httpbin`.
+
+Sometimes the session sticky is desired, and you can use the [Consistent
Hashing](https://en.wikipedia.org/wiki/Consistent_hashing) load balancing
algorithm.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: httpbin
+spec:
+ loadbalancer:
+ type: chash
+ hashOn: header
+ key: "user-agent"
+```
+
+With the above settings, Apache APISIX will distributes requests according to
the User-Agent header.
+
+### Configuring Health Check
+
+Although Kubelet already provides
[probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#:~:text=The%20kubelet%20uses%20readiness%20probes,removed%20from%20Service%20load%20balancers.)
to detect whether pods are healthy, you may still need more powerful health
check mechanism,
+like the passive feedback capability.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: httpbin
+spec:
+ healthCheck:
+ passive:
+ unhealthy:
+ httpCodes:
+ - 500
+ - 502
+ - 503
+ - 504
+ httpFailures: 3
+ timeout: 5s
+ active:
+ type: http
+ httpPath: /healthz
+ timeout: 5s
+ host: www.foo.com
+ healthy:
+ successes: 3
+ interval: 2s
+ httpCodes:
+ - 200
+ - 206
+```
+
+The above YAML snippet defines a passive health checker to detect the
unhealthy state for
+endpoints, once there are three consecutive requests with bad status code (one
of `500`, `502`, `503`, `504`), the endpoint
+will be set to unhealthy and no requests can be routed there until it's
healthy again.
+
+That's why the active health checker comes in, endpoints might be down for a
short while and ready again, the active health checker detects these unhealthy
endpoints continuously, and pull them
+up once the healthy conditions are met (three consecutive requests got good
status codes, e.g. `200` and `206`).
+
+Note the active health checker is somewhat duplicated with the
liveness/readiness probes but it's required if the passive feedback mechanism
is in use. So once you use the health check feature in ApisixUpstream,
+the active health checker is mandatory.
+
+### Configuring Retry and Timeout
+
+You may want the proxy to retry when requests occur faults like transient
network errors
+or service unavailable, by default the retry count is `1`. You can change it
by specifying the `retries` field.
+
+The following configuration configures the `retries` to `3`, which indicates
there'll be at most `3` requests sent to
+Kubernetes service `httpbin`'s endpoints.
+
+One should bear in mind that passing a request to the next endpoint is only
possible
+if nothing has been sent to a client yet. That is, if an error or timeout
occurs in the middle
+of the transferring of a response, fixing this is impossible.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: httpbin
+spec:
+ retries: 3
+```
+
+The default connect, read and send timeout are `60s`, which might not proper
for some applications,
+just change them in the `timeout` field.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: httpbin
+spec:
+ timeout:
+ connect: 5s
+ read: 10s
+ send: 10s
+```
+
+The above examples sets the connect, read and timeout to `5s`, `10s`, `10s`
respectively.
+
+### Port Level Settings
+
+Once in a while a single Kubernetes Service might expose multiple ports which
provides distinct functions and different Upstream configurations are required.
+In that case, you can create configurations for individual port.
+
+```yaml
+apiVersion: apisix.apache.org/v1
+kind: ApisixUpstream
+metadata:
+ name: foo
+spec:
+ loadbalancer:
+ type: roundrobin
+ portLevelSettings:
+ - port: 7000
+ scheme: http
+ - port: 7001
+ scheme: grpc
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: foo
+spec:
+ selector:
+ app: foo
+ portLevelSettings:
+ - name: http
+ port: 7000
+ targetPort: 7000
+ - name: grpc
+ port: 7001
+ targetPort: 7001
+```
+
+The `foo` service exposes two ports, one of them use HTTP protocol and the
other uses grpc protocol.
+In the meanwhile, the ApisixUpstream `foo` sets `http` scheme for port `7000`
and `grpc` scheme for `7001`
+(all ports are the service port). But both ports shares the load balancer
configuration.
+
+`PortLevelSettings` is not mandatory if the service only exposes one port but
is useful when multiple ports are defined.
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index bd47adf..3c6be47 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -5,22 +5,21 @@
"type": "category",
"label": "Getting Started",
"items": [
- "design",
- "CRD-specification"
+ "get-started"
]
},
{
"type": "category",
- "label": "Samples",
+ "label": "Practices",
"items": [
- "samples/index",
- "samples/proxy-the-httpbin-service-with-ingress",
- "samples/proxy-the-httpbin-service"
+ "practices/index",
+ "practices/proxy-the-httpbin-service-with-ingress",
+ "practices/proxy-the-httpbin-service"
]
},
{
"type": "category",
- "label": "Deployment",
+ "label": "Installation",
"items": [
"deployments/ack",
"deployments/aws",
@@ -33,8 +32,22 @@
]
},
{
- "type": "doc",
- "id": "usage"
+ "type": "category",
+ "label": "Reference",
+ "items": [
+ "apisix_route_v1",
+ "apisix_route_v2alpha1",
+ "apisix_upstream",
+ "apisix_tls"
+ ]
+ },
+ {
+ "type": "category",
+ "label": "Concepts",
+ "items": [
+ "apisix_route",
+ "apisix_upstream"
+ ]
},
{
"type": "doc",
diff --git a/docs/en/latest/deployments/ack.md
b/docs/en/latest/deployments/ack.md
index 46c6ea7..4d67880 100644
--- a/docs/en/latest/deployments/ack.md
+++ b/docs/en/latest/deployments/ack.md
@@ -72,4 +72,4 @@ helm install apisix-ingress-controller
./charts/apisix-ingress-controller \
Change the `image.tag` to the apisix-ingress-controller version that you
desire. You have to Wait for while until the corresponding pods are running.
-Try to create some [resources](../CRD-specification.md) to verify the running
status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Try to create some [resources](../CRD-specification.md) to verify the running
status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/aws.md
b/docs/en/latest/deployments/aws.md
index e26ddd2..bde61aa 100644
--- a/docs/en/latest/deployments/aws.md
+++ b/docs/en/latest/deployments/aws.md
@@ -74,4 +74,4 @@ Change the `image.tag` to the apisix-ingress-controller
version that you desire.
Now open your [EKS console](https://console.aws.amazon.com/eks/home), choosing
your cluster and clicking the Workloads tag, you'll see all pods of Apache
APISIX, etcd and apisix-ingress-controller are ready.
-Try to create some [resources](../CRD-specification.md) to verify the running
status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Try to create some [resources](../CRD-specification.md) to verify the running
status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/azure.md
b/docs/en/latest/deployments/azure.md
index fc1e50e..36f4f9b 100644
--- a/docs/en/latest/deployments/azure.md
+++ b/docs/en/latest/deployments/azure.md
@@ -72,4 +72,4 @@ helm install apisix-ingress-controller
./charts/apisix-ingress-controller \
Change the `image.tag` to the apisix-ingress-controller version that you
desire. You have to wait for while until the corresponding pods are running.
-Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/gke.md
b/docs/en/latest/deployments/gke.md
index a17943a..cdf7a15 100644
--- a/docs/en/latest/deployments/gke.md
+++ b/docs/en/latest/deployments/gke.md
@@ -72,4 +72,4 @@ helm install apisix-ingress-controller
./charts/apisix-ingress-controller \
Change the `image.tag` to the apisix-ingress-controller version that you
desire. You have to wait for while until the corresponding pods are running.
-Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/k3s-rke.md
b/docs/en/latest/deployments/k3s-rke.md
index df7e151..25c90ae 100644
--- a/docs/en/latest/deployments/k3s-rke.md
+++ b/docs/en/latest/deployments/k3s-rke.md
@@ -79,4 +79,4 @@ The admin key used in above mentioned commands is the default
one, if you change
Change the `image.tag` to the apisix-ingress-controller version that you
desire. You have to wait for while until the corresponding pods are running.
-Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/kubesphere.md
b/docs/en/latest/deployments/kubesphere.md
index 22dcb6a..4fdfd8c 100644
--- a/docs/en/latest/deployments/kubesphere.md
+++ b/docs/en/latest/deployments/kubesphere.md
@@ -72,4 +72,4 @@ The admin key used above is the default one. If you change
the admin key configu
Change the `image.tag` to the apisix-ingress-controller version that you
desire. Wait for the corresponding pods are running.
-Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Now try to create some [resources](../CRD-specification.md) to verify the
running status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/minikube.md
b/docs/en/latest/deployments/minikube.md
index cf3bb4e..5ad31df 100644
--- a/docs/en/latest/deployments/minikube.md
+++ b/docs/en/latest/deployments/minikube.md
@@ -64,4 +64,4 @@ helm install apisix-ingress-controller
./charts/apisix-ingress-controller \
Change the `image.tag` to the apisix-ingress-controller version that you
desire. You have to wait for while until the corresponding pods are running.
-Now try to create some [resources](../CRD-specification.md) to verify the
running of Ingress APISIX. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Now try to create some [resources](../CRD-specification.md) to verify the
running of Ingress APISIX. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/deployments/tke.md
b/docs/en/latest/deployments/tke.md
index 510920a..f87f633 100644
--- a/docs/en/latest/deployments/tke.md
+++ b/docs/en/latest/deployments/tke.md
@@ -77,4 +77,4 @@ Change the `image.tag` to the apisix-ingress-controller
version that you desire.
Now open your [TKE console](https://console.cloud.tencent.com/tke2/overview),
choosing your cluster and clicking the Workloads tag, you'll see all pods of
Apache APISIX, etcd and apisix-ingress-controller are ready.
-Try to create some [resources](../CRD-specification.md) to verify the running
status. As a minimalist example, see
[proxy-the-httpbin-service](../samples/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
+Try to create some [resources](../CRD-specification.md) to verify the running
status. As a minimalist example, see
[proxy-the-httpbin-service](../practices/proxy-the-httpbin-service.md) to learn
how to apply resources to drive the apisix-ingress-controller.
diff --git a/docs/en/latest/get-started.md b/docs/en/latest/get-started.md
new file mode 100644
index 0000000..cfccdc0
--- /dev/null
+++ b/docs/en/latest/get-started.md
@@ -0,0 +1,66 @@
+---
+title: Getting Started
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## What is apisix-ingress-controller
+
+apisix-ingress-controller is yet another Ingress controller for Kubernetes
using [Apache APISIX](https://apisix.apache.org) as the high performance
reverse proxy.
+
+It's configured by using the declarative configurations like
[ApisixRoute](./concepts/apisix_route.md), [ApisixUpstream](./concepts/apisix),
[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).
+All these resources are watched and converted to corresponding resources in
Apache APISIX.
+
+Service Discovery are also supported through [Kubernetes
Service](https://kubernetes.io/docs/concepts/services-networking/service/),
+and will be reflected to nodes in APISIX Upstream.
+
+
+
+## Features
+
+* Declarative configuration
+* Full dynamic capabilities to delivery configurations.
+* Native Kubernetes Ingress (both v1 and v1beta1) support.
+* Service Discovery based on Kubernetes Service.
+* Out of box support for node health check.
+* Support load balancing based on Pod (upstream nodes).
+* Rich plugins support.
+* Easy to deploy and use.
+
+## Installation on Cloud
+
+apisix-ingress-controller supports to be installed on some clouds such as AWS,
GCP.
+
+* [Install Ingress APISIX on Azure AKS](./docs/en/latest/deployments/azure.md)
+* [Install Ingress APISIX on AWS EKS](./docs/en/latest/deployments/aws.md)
+* [Install Ingress APISIX on ACK](./docs/en/latest/deployments/ack.md)
+* [Install Ingress APISIX on Google Cloud
GKE](./docs/en/latest/deployments/gke.md)
+* [Install Ingress APISIX on
Minikube](./docs/en/latest/deployments/minikube.md)
+* [Install Ingress APISIX on
KubeSphere](./docs/en/latest/deployments/kubesphere.md)
+* [Install Ingress APISIX on K3S and
RKE](./docs/en/latest/deployments/k3s-rke.md)
+
+## Installation on Prem
+
+If you want to deploy apisix-ingress-controller on Prem, we recommend you to
use [Helm](https://helm.io). Just a few steps
+
+## Get Involved to Contribute
+
+First, your supports and cooperations to make this project better are
appreciated.
+But before you start, please read [How to Contribute](./contribute.md) and
[How to Develop](./development.md).
diff --git a/docs/en/latest/samples/index.md b/docs/en/latest/practices/index.md
similarity index 100%
copy from docs/en/latest/samples/index.md
copy to docs/en/latest/practices/index.md
diff --git a/docs/en/latest/samples/proxy-the-httpbin-service-with-ingress.md
b/docs/en/latest/practices/proxy-the-httpbin-service-with-ingress.md
similarity index 100%
rename from docs/en/latest/samples/proxy-the-httpbin-service-with-ingress.md
rename to docs/en/latest/practices/proxy-the-httpbin-service-with-ingress.md
diff --git a/docs/en/latest/samples/proxy-the-httpbin-service.md
b/docs/en/latest/practices/proxy-the-httpbin-service.md
similarity index 100%
rename from docs/en/latest/samples/proxy-the-httpbin-service.md
rename to docs/en/latest/practices/proxy-the-httpbin-service.md
diff --git a/docs/en/latest/reference/apisix_route_v1.md
b/docs/en/latest/reference/apisix_route_v1.md
new file mode 100644
index 0000000..32d4587
--- /dev/null
+++ b/docs/en/latest/reference/apisix_route_v1.md
@@ -0,0 +1,39 @@
+---
+title: ApisixRoute/v1 (Deprecated) Reference
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+**WARNINIG**: `ApisixRoute/v1` is obsolete and will be unsupported in the
future, please use `ApisixRoute/v2alpha1`!
+
+| Field | Type | Description
|
+|---------------|----------|----------------------------------------------------|
+| rules | array | ApisixRoute's request matching rules.
|
+| host | string | The requested host.
|
+| http | object | Route rules are applied to the scope of layer 7
traffic. |
+| paths | array | Path-based `route` rule matching.
|
+| backend | object | Backend service information configuration.
|
+| serviceName | string | The name of backend service. `namespace +
serviceName + servicePort` form an unique identifier to match the back-end
service. |
+| servicePort | int | The port of backend service. `namespace +
serviceName + servicePort` form an unique identifier to match the back-end
service. |
+| path | string | The URI matched by the route. Supports exact
match and prefix match. Example，exact match: `/hello`, prefix match: `/hello*`.
|
+| plugins | array | Custom plugin collection (Plugins defined in the
`route` level). For more plugin information, please refer to the [Apache APISIX
plugin docs](https://github.com/apache/apisix/tree/master/doc/plugins). |
+| name | string | The name of the plugin. For more information
about the example plugin, please check the [limit-count
docs](https://github.com/apache/apisix/blob/master/doc/plugins/limit-count.md#Attributes).
|
+| enable | boolean | Whether to enable the plugin, `true`: means
enable, `false`: means disable. |
+| config | object | Configuration of plugin information. Note: The
check of configuration schema is missing now, so please be careful when
editing. |
diff --git a/docs/en/latest/samples/index.md
b/docs/en/latest/reference/apisix_route_v2alpha1.md
similarity index 72%
copy from docs/en/latest/samples/index.md
copy to docs/en/latest/reference/apisix_route_v2alpha1.md
index 28dcbb5..af36626 100644
--- a/docs/en/latest/samples/index.md
+++ b/docs/en/latest/reference/apisix_route_v2alpha1.md
@@ -1,5 +1,5 @@
---
-title: Ingress APISIX Use Examples
+title: ApisixRoute/v2alpha1 Reference
---
<!--
@@ -20,8 +20,3 @@ title: Ingress APISIX Use Examples
# limitations under the License.
#
-->
-
-This is an index page about use examples of Ingress APISIX. Read them if
you're trying to learn Ingress APISIX.
-
-* [Proxy the httpbin service](./proxy-the-httpbin-service.md).
-* [Proxy the httpbin service with the native
Ingress](./proxy-the-httpbin-service-with-ingress.md).
diff --git a/docs/en/latest/samples/index.md
b/docs/en/latest/reference/apisix_tls.md
similarity index 55%
rename from docs/en/latest/samples/index.md
rename to docs/en/latest/reference/apisix_tls.md
index 28dcbb5..3e46214 100644
--- a/docs/en/latest/samples/index.md
+++ b/docs/en/latest/reference/apisix_tls.md
@@ -1,5 +1,5 @@
---
-title: Ingress APISIX Use Examples
+title: ApisixTls Reference
---
<!--
@@ -21,7 +21,9 @@ title: Ingress APISIX Use Examples
#
-->
-This is an index page about use examples of Ingress APISIX. Read them if
you're trying to learn Ingress APISIX.
-
-* [Proxy the httpbin service](./proxy-the-httpbin-service.md).
-* [Proxy the httpbin service with the native
Ingress](./proxy-the-httpbin-service-with-ingress.md).
+| Field | Type | Description |
+|---------------|----------|---------------------------------|
+| hosts | array | The domain list to identify which hosts (matched
with SNI) can use the TLS certificate stored in the Secret. |
+| secret | object | The definition of the related Secret object with
current ApisixTls object. |
+| name | string | The name of secret, the secret contains key and
cert for `TLS`. |
+| namespace | string | The namespace of secret, the secret contains key
and cert for `TLS`. |
diff --git a/docs/en/latest/reference/apisix_upstream.md
b/docs/en/latest/reference/apisix_upstream.md
new file mode 100644
index 0000000..cbbc26a
--- /dev/null
+++ b/docs/en/latest/reference/apisix_upstream.md
@@ -0,0 +1,68 @@
+---
+title: ApisixUpstream Reference
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+| Field | Type | Description |
+|---------------|----------|----------------|
+| scheme | string | The protocol used to talk to the Service, can be
`http`, `grpc`, default is `http`. |
+| loadbalancer | object | The load balancing algorithm of this upstream
service |
+| loadbalancer.type | string | The load balancing type, can be `roundrobin`,
`ewma`, `least_conn`, `chash`, default is `roundrobin`. |
+| loadbalancer.hashOn | string | The hash value source scope, only take
effects if the `chash` algorithm is in use. Values can `vars`, `header`,
`vars_combinations`, `cookie` and `consumers`, default is `vars`. |
+| loadbalancer.key | string | The hash key, only in valid if the `chash`
algorithm is used.
+| retries | int | The retry count. |
+| timeout | object | The timeout settings. |
+| timeout.connect | time duration in the form "72h3m0.5s" | The connect
timeout. |
+| timeout.read | time duration in the form "72h3m0.5s" | The read timeout. |
+| timeout.send | time duration in the form "72h3m0.5s" | The send timeout. |
+| healthCheck | object | The health check parameters, see [Health
Check](https://github.com/apache/apisix/blob/master/doc/health-check.md) for
more details. |
+| healthCheck.active | object | active health check configuration, which is a
mandatory field. |
+| healthCheck.active.type | string | health check type, can be `http`, `https`
and `tcp`, default is `http`. |
+| healthCheck.active.timeout | time duration in the form "72h3m0.5s" | the
timeout settings for the probe, default is `1s`. |
+| healthCheck.active.concurrency | int | how many probes can be sent
simultaneously, default is `10`. |
+| healthCheck.active.host | string | host header in http probe request, only
in valid if the active health check type is `http` or `https`. |
+| healthCheck.active.port | int | target port to receive probes, it's
necessary to specify this field if the health check service exposes by
different port, note the port value here is the container port, not the service
port. |
+| healthCheck.active.httpPath | string | the HTTP URI path in http probe, only
in valid if the active health check type is `http` or `https`. |
+| healthCheck.active.strictTLS | boolean | whether to use the strict mode when
use TLS, only in valid if the active health check type is `https`, default is
`true`. |
+| healthCheck.active.requestHeaders | array of string | Extra HTTP requests
carried in the http probe, only in valid if the active health check type is
`http` or `https`. |
+| healthCheck.active.healthy | object | The conditions to judge an endpoint is
healthy. |
+| healthCheck.active.healthy.successes | int | The number of consecutive
requests needed to set an endpoint as healthy, default is `2`. |
+| healthCheck.active.healthy.httpCodes | array of integer | Good status codes
list to check whether a probe is successful, only in valid if the active health
check type is `http` or `https`, default is `[200, 302]`. |
+| healthCheck.active.healthy.interval | time duration in the form "72h3m0.5s"
| The probes sent interval (for healthy endpoints). |
+| healthCheck.active.unhealthy | object | The conditions to judge an endpoint
is unhealthy. |
+| healthCheck.active.unhealthy.httpFailures | int | The number of consecutive
http requests needed to set an endpoint as unhealthy, only in valid if the
active health check type is `http` or `https`, default is `5`. |
+| healthCheck.active.unhealthy.tcpFailures | int | The number of consecutive
tcp connections needed to set an endpoint as unhealthy, only in valid if the
active health check type is `tcp`, default is `2`. |
+| healthCheck.active.unhealthy.httpCodes | array of integer | Bad status codes
list to check whether a probe is failed, only in valid if the active health
check type is `http` or `https`, default is `[429, 404, 500, 501, 502, 503,
504, 505]`. |
+| healthCheck.active.unhealthy.interval | time duration in the form
"72h3m0.5s" | The probes sent interval (for unhealthy endpoints). |
+| healthCheck.passive | object | passive health check configuration, which is
an optional field. |
+| healthCheck.passive.type | string | health check type, can be `http`,
`https` and `tcp`, default is `http`. |
+| healthCheck.passive.healthy | object | The conditions to judge an endpoint
is healthy. |
+| healthCheck.passive.healthy.successes | int | The number of consecutive
requests needed to set an endpoint as healthy, default is `5`. |
+| healthCheck.passive.healthy.httpCodes | array of integer | Good status codes
list to check whether a probe is successful, only in valid if the active health
check type is `http` or `https`, default is `[200, 201, 202, 203, 204, 205,
206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]`. |
+| healthCheck.passive.unhealthy | object | The conditions to judge an endpoint
is unhealthy. |
+| healthCheck.passive.unhealthy.httpFailures | int | The number of consecutive
http requests needed to set an endpoint as unhealthy, only in valid if the
active health check type is `http` or `https`, default is `5`. |
+| healthCheck.passive.unhealthy.tcpFailures | int | The number of consecutive
tcp connections needed to set an endpoint as unhealthy, only in valid if the
active health check type is `tcp`, default is `2`. |
+| healthCheck.passive.unhealthy.httpCodes | array of integer | Bad status
codes list to check whether a probe is failed, only in valid if the active
health check type is `http` or `https`, default is `[429, 404, 500, 501, 502,
503, 504, 505]`. |
+| portLevelSettings | array | Settings for each individual port. |
+| portLevelSettings.port | int | The port number defined in the Kubernetes
Service, must be a valid port. |
+| portLevelSettings.scheme | string | same as `scheme` but takes higher
precedence. |
+| portLevelSettings.loadbalancer | object | same as `loadbalancer` but takes
higher precedence. |
+| portLevelSettings.healthCheck | object | same as `healthCheck` but takes
higher precedence. |
diff --git a/docs/en/latest/usage.md b/docs/en/latest/usage.md
deleted file mode 100644
index 89a2edc..0000000
--- a/docs/en/latest/usage.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-title: Usage of Ingress controller
----
-
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-In this article, we will use ingress controller CRDs
(CustomResourceDefinition) to define routing rules against the admin api of
Apache APISIX.
-
-## Scenes
-
-Configure a simple routing rule through the ingress controller CRDs. After
synchronizing to the gateway, the data traffic is accessed to the back-end
service through Apache APISIX. Then, we gradually add or remove plug-ins to the
routing to achieve functional expansion.
-
-As shown below.
-
-
-
-## A simple example
-
-Define the simplest route to direct traffic to the back-end service, the
back-end service is named `httpserver`.
-
-As shown below.(The ip list in nodes is an example, no specific meaning)
-
-
-
-Now we define with CRDs as follows.
-
-1. Define Upstream with `ApisixUpstream`
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixUpstream
-metadata:
- name: foo
-spec:
- ports:
- - port: 8080
- loadbalancer:
- type: chash
- hashOn: header
- key: hello
-```
-
-2. Define Route with `ApisixRoute`
-
-```yaml
-apiVersion: apisix.apache.org/v1
-kind: ApisixRoute
-metadata:
- name: foo-route
-spec:
- rules:
- - host: test.apisix.apache.org
- http:
- paths:
- - backend:
- serviceName: foo
- servicePort: 8080
- path: /hello*
-```
-
-Tips: When defining `ApisixUpstream`, there is no need to define a specific
pod ip list, the ingress controller will do service discovery based on
namespace/name/port composite index.
-
-List the way to define the above rules using `Admin API` to facilitate
comparison and understanding.
-
-```shell
-# 1. Define upstream: foo-upstream id=1 (the ip list in nodes is an example,
no specific meaning)
-curl -XPUT http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -d '
-{
- "nodes": {
- "10.244.143.48:8080": 100,
- "10.244.102.43:8080": 100,
- "10.244.102.63:8080": 100
- },
- "desc": "foo-upstream",
- "type": "roundrobin"
-}
-'
-# 2. Define service: foo-service, id=2, binding upstream: foo-upstream
-curl -XPUT http://127.0.0.1:9080/apisix/admin/services/2 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -d '
-{
- "desc": "foo-service",
- "upstream_id": 1
-}
-'
-
-# 3. Define route: foo-route， id=3， binding service: foo-service
-
-curl -XPUT http://127.0.0.1:9080/apisix/admin/routes/3 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -d '
-{
- "desc": "foo-route",
- "uri": "/hello*",
- "host": "test.apisix.apache.org",
- "service_id": "2"
-}'
-```
diff --git a/install.md b/install.md
index 97173e4..b3ed337 100644
--- a/install.md
+++ b/install.md
@@ -42,4 +42,4 @@ Parameters are hardcoded so if the default values are not
good for you, just twe
## Verify Installation
-There are a lot of use examples (See
[samples](./docs/en/latest/samples/index.md) for more details), try to follow
the operations there to verify the installation.
+There are a lot of use examples (See
[samples](docs/en/latest/practices/index.md) for more details), try to follow
the operations there to verify the installation.
