From c8ac9cb9be881489cfec3886d6f06363a16caa3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sandor=20Sz=C3=BCcs?= Date: Mon, 3 Jun 2024 14:45:50 +0200 Subject: [PATCH] doc: review and update ingress usage docs (#3094) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc: review and update ingress usage docs Signed-off-by: Sandor Szücs --- docs/kubernetes/ingress-usage.md | 118 ++++++++++++++++++++----------- docs/reference/filters.md | 2 +- 2 files changed, 76 insertions(+), 44 deletions(-) diff --git a/docs/kubernetes/ingress-usage.md b/docs/kubernetes/ingress-usage.md index 1b35e3cdae..d8d96fea7b 100644 --- a/docs/kubernetes/ingress-usage.md +++ b/docs/kubernetes/ingress-usage.md @@ -4,21 +4,21 @@ This documentation is meant for people deploying to Kubernetes Clusters and describes to use Ingress and low level and high level features Skipper provides. -[RouteGroups](routegroups.md), a relatively new feature, also -support each of these features, with an alternative format that -supports them in a more native way. The documentation contains a -section with -[mapping](routegroups.md#mapping-from-ingress-to-routegroups) -Ingress to RouteGroups. +[RouteGroups](routegroups.md), Skipper Kubernetes native routing +object that supports all Skipper features. If you need to create more +than one route to your application, RouteGroups should be the default +choice, instead of ingress. The documentation contains a section with +[mapping](routegroups.md#mapping-from-ingress-to-routegroups) Ingress +to RouteGroups. ## Skipper Ingress Annotations Annotation | example data | usage --- | --- | --- -zalando.org/backend-weights | `{"my-app-1": 80, "my-app-2": 20}` | blue-green deployments +zalando.org/backend-weights | `{"my-app-1": 80, "my-app-2": 20}` | blue-green deployments, see also [StackSet](https://github.com/zalando-incubator/stackset-controller) for more high-level integration zalando.org/skipper-filter | `consecutiveBreaker(15)` | arbitrary filters zalando.org/skipper-predicate | `QueryParam("version", "^alpha$")` | arbitrary predicates -zalando.org/skipper-routes | `Method("OPTIONS") -> status(200) -> ` | extra custom routes +zalando.org/skipper-routes | `Method("OPTIONS") -> status(200) -> ` | extra custom routes, please consider using [RouteGroups](routegroups.md) instead zalando.org/ratelimit | `ratelimit(50, "1m")` | deprecated, use zalando.org/skipper-filter instead zalando.org/skipper-ingress-redirect | `"true"` | change the default HTTPS redirect behavior for specific ingresses (true/false) zalando.org/skipper-ingress-redirect-code | `301` | change the default HTTPS redirect code for specific ingresses @@ -30,6 +30,7 @@ zalando.org/skipper-ingress-path-mode | `path-prefix` | (*deprecated*) please us Ingress backend definitions are services, which have different [service types](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types). +ClusterIP should be the default for all backend applications that expose via ingress. Service type | supported | workaround --- | --- | --- @@ -106,7 +107,7 @@ spec: If multiple ingresses define the same host and the same predicates, traffic routing may become non-deterministic. Consider the following two ingresses which have the same hostname and therefore -overlap. In skipper the routing of this is currently undefined as skipper +overlap. In Skipper the routing of this is currently undefined as skipper doesn't pick one over the other, but just creates routes (possible overlapping) for each of the ingresses. @@ -164,18 +165,19 @@ Ingress paths can be interpreted in five different modes: 1. `pathType: Prefix` results in [PathSubtree predicate](../reference/predicates.md#pathsubtree)) 2. `pathType: Exact` results in [Path predicate](../reference/predicates.md#path)) 3. `pathType: ImplementationSpecific` - 1. based on the kubernetes ingress specification + 1. based on the Kubernetes ingress specification 2. as plain regular expression 3. as a path prefix (same as `pathType: Prefix` and results in [PathSubtree](../reference/predicates.md#pathsubtree)) -The default is 3.1 the kubernetes ingress mode. It can be changed by a startup option -to any of the other modes, and the individual ingress rules can also override the -default behavior with the zalando.org/skipper-ingress-path-mode annotation. You can +The default is 3.1 the Kubernetes ingress mode. It can be changed by startup option `-kubernetes-path-mode` +to any of the other modes. The individual ingress rules can also override the +default behavior with the `zalando.org/skipper-ingress-path-mode` annotation. You can also set for each path rule a different Kubernetes `pathType` like `Prefix` and `Exact`. E.g.: - zalando.org/skipper-ingress-path-mode: path-prefix + zalando.org/skipper-ingress-path-mode: path-prefix # Skipper specific + pathType: Prefix # ingress v1 ### Kubernetes ingress specification base path @@ -188,7 +190,7 @@ path. ### Plain regular expression When the path mode is set to `path-regexp`, the ingress path is interpreted similar -to the default kubernetes ingress specification way, but is not prepended by the `^` +to the default Kubernetes ingress specification way, but is not prepended by the `^` control character. ### Path prefix @@ -241,7 +243,7 @@ Custom routes is a way of extending the default routes configured for an ingress resource. Sometimes you just want to return a header, redirect or even static -html content. You can return from skipper without doing a proxy call +html content. You can return from Skipper without doing a proxy call to a backend, if you end your filter chain with ``. The use of `` recommends the use in combination with `status()` filter, to not respond with the default http code, which defaults to 404. To @@ -253,7 +255,7 @@ priority. Custom routes specified in ingress will always add the `Host()` [predicate](../reference/predicates.md#host) to match the host header specified in the ingress `rules:`. If there is a `path:` definition in your -ingress, then it will be based on the skipper command line parameter +ingress, then it will be based on the Skipper command line parameter `-kubernetes-path-mode` set one of these predicates: - [Path()](../reference/predicates.md#path) @@ -351,7 +353,7 @@ directly with a HTTP status code 200: ``` zalando.org/skipper-routes: | - Path("/") -> setResponseHeader("X", "bar") -> inlineContent("hello") -> status(200) -> + PathRegexp("/") -> setResponseHeader("X", "bar") -> inlineContent("hello") -> status(200) -> ``` Keep in mind that you need a valid backend definition to backends @@ -399,8 +401,8 @@ Host(/^app-default[.]example[.]org$/) && Method("OPTIONS") -> ### Multiple routes -You can also set multiple routes, but you have to set the names of the -route as defined in eskip: +You can also set multiple routes, but you have to set the IDs +(`routename1`, `routename2`) of the route as defined in eskip: ``` zalando.org/skipper-routes: | @@ -449,7 +451,7 @@ A possible solution is to use skipper's [RouteGroups](routegroups.md). ## Filters - Basic HTTP manipulations -HTTP manipulations are done by using skipper filters. Changes can be +HTTP manipulations are done by using Skipper filters. Changes can be done in the request path, meaning request to your backend or in the response path to the client, which made the request. @@ -548,31 +550,26 @@ by the filters mentioned above. ### Diagnosis - Throttling Bandwidth - Latency -For diagnosis purpose there are filters that enable you to throttle +For diagnosis purpose there are more than 20 filters that enable you to throttle the bandwidth or add latency. For the full list of filters see our -[diag filter godoc page](https://godoc.org/github.com/zalando/skipper/filters/diag). +[diagnostics filters](../reference/filters.md#diagnostics). +Examples: bandwidth(30) // incoming in kb/s backendBandwidth(30) // outgoing in kb/s backendLatency(120) // in ms - -Filter documentation: - -- [latency](../reference/filters.md#latency) -- [bandwidth](../reference/filters.md#bandwidth) -- [chunks](../reference/filters.md#chunks) -- [backendlatency](../reference/filters.md#backendlatency) -- [backendChunks](../reference/filters.md#backendchunks) -- [randomcontent](../reference/filters.md#randomcontent) + normalRequestLatency("10ms", "5ms") // normal distribution for request latency as time duration string + logHeader("request") // log all request headers + logBody("response", 1024) // log up to 1024 Bytes of the response body ### Flow Id to trace request flows -To trace request flows skipper can generate a unique Flow Id for every +To trace request flows Skipper can generate a unique Flow Id for every HTTP request that it receives. You can then find the trace of the request in all your access logs. Skipper sets the X-Flow-Id header to a unique value. Read more about this in our [flowid filter](../reference/filters.md#flowid) -and [godoc](https://godoc.org/github.com/zalando/skipper/filters/flowid). +and [godoc](https://pkg.go.dev/github.com/zalando/skipper/filters/flowid). flowId("reuse") @@ -648,6 +645,33 @@ spec: pathType: ImplementationSpecific ``` +#### Admission Control + +The [admissionControl](../reference/filters.md#admissioncontrol) +filter is a dynamic circuit breaker that works based on HTTP error +codes observed by backends. It will dynamically adjust the shedding of +load to the maximum throughput possible. + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + annotations: + zalando.org/skipper-filter: admissionControl("myapp", "active", "1s", 5, 10, 0.95, 0.9, 0.5) + name: app +spec: + rules: + - host: app-default.example.org + http: + paths: + - backend: + service: + name: app-svc + port: + number: 80 + pathType: ImplementationSpecific +``` + ### Ratelimits @@ -665,15 +689,15 @@ side as described above. Ratelimits are enforced per route. -More details you will find in [ratelimit -package](https://godoc.org/github.com/zalando/skipper/filters/ratelimit) -and in our [ratelimit tutorial](../tutorials/ratelimit.md). +More details you will find in [rate limit +filters](../reference/filters.md#rate-limit) section and in our +[ratelimit tutorial](../tutorials/ratelimit.md). #### Client Ratelimits The example shows 20 calls per hour per client, based on X-Forwarded-For header or IP in case there is no X-Forwarded-For header -set, are allowed to each skipper instance for the given ingress. +set, are allowed to each Skipper instance for the given ingress. ```yaml apiVersion: networking.k8s.io/v1 @@ -705,7 +729,7 @@ apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: - zalando.org/skipper-filter: clientRatelimit(20, "1h", "auth") + zalando.org/skipper-filter: clientRatelimit(20, "1h", "authorization") name: app spec: rules: @@ -849,6 +873,7 @@ If you want to test a new replacement of a production service with production load, you can copy incoming requests to your new endpoint and ignore the responses from your new backend. This can be done by the [tee()](../reference/filters.md#tee) and [teenf()](../reference/filters.md#teenf) filters. +See also our [shadow traffic tutorial](../tutorials/shadow-traffic.md). ```yaml apiVersion: networking.k8s.io/v1 @@ -936,16 +961,23 @@ spec: pathType: ImplementationSpecific ``` -### IP Whitelisting +### IP Allow Listing + +This ingress route will only allow traffic from networks 1.2.3.0/24 +and 195.168.0.0/17 Before you use this in production please understand +your deployment and check the difference between the following +options: -This ingress route will only allow traffic from networks 1.2.3.0/24 and 195.168.0.0/17 +- [ClientIP](../reference/predicates.md#clientip) +- [Source](../reference/predicates.md#source) +- [SourceFromLast](../reference/predicates.md#sourcefromlast) ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: - zalando.org/skipper-predicate: Source("1.2.3.0/24", "195.168.0.0/17") + zalando.org/skipper-predicate: ClientIP("1.2.3.0/24", "195.168.0.0/17") name: app spec: rules: @@ -1113,7 +1145,7 @@ For more advanced blue-green deployments, check out our [stackset-controller](ht ## Chaining Filters and Predicates -You can set multiple filters in a chain similar to the [eskip format](https://godoc.org/github.com/zalando/skipper/eskip). +You can set multiple filters in a chain similar to the [eskip format](https://pkg.go.dev/github.com/zalando/skipper/eskip). ```yaml apiVersion: networking.k8s.io/v1 diff --git a/docs/reference/filters.md b/docs/reference/filters.md index d22546b95e..bc858894cc 100644 --- a/docs/reference/filters.md +++ b/docs/reference/filters.md @@ -3263,7 +3263,7 @@ tracingTag("http.flow_id", "${request.header.X-Flow-Id}") ### tracingTagFromResponse -This filter works just like [tracingTag](#tracingTag), but is applied after the request was processed. In particular, [template placeholders](#template-placeholders) referencing the response can be used in the parameters. +This filter works just like [tracingTag](#tracingtag), but is applied after the request was processed. In particular, [template placeholders](#template-placeholders) referencing the response can be used in the parameters. ### tracingSpanName