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.

Sign up for GitHub

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

doc: review and update ingress usage docs #3094

Merged
merged 5 commits into from
Jun 3, 2024
Merged

doc: review and update ingress usage docs #3094

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3cf9faf
doc: review and update ingress usage docs
szuecs Jun 3, 2024
ac8348b
fix: mkdocs link
szuecs Jun 3, 2024
bc187f6
fix: broken link
szuecs Jun 3, 2024
190eddf
fix: uppercase handling of Skipper and Kubernetes
szuecs Jun 3, 2024
c69b373
fix: target link
szuecs Jun 3, 2024
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
118 changes: 75 additions & 43 deletions docs/kubernetes/ingress-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) -> <shunt>` | extra custom routes
zalando.org/skipper-routes | `Method("OPTIONS") -> status(200) -> <shunt>` | 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
Expand All @@ -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
--- | --- | ---
Expand Down Expand Up @@ -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.

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

Expand All @@ -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
Expand Down Expand Up @@ -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 `<shunt>`. The use of
`<shunt>` recommends the use in combination with `status()` filter, to
not respond with the default http code, which defaults to 404. To
Expand All @@ -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)
Expand Down Expand Up @@ -351,7 +353,7 @@ directly with a HTTP status code 200:

```
zalando.org/skipper-routes: |
Path("/") -> setResponseHeader("X", "bar") -> inlineContent("<html><body>hello</body></html>") -> status(200) -> <shunt>
PathRegexp("/") -> setResponseHeader("X", "bar") -> inlineContent("<html><body>hello</body></html>") -> status(200) -> <shunt>
szuecs marked this conversation as resolved.
Show resolved Hide resolved
```

Keep in mind that you need a valid backend definition to backends
Expand Down Expand Up @@ -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: |
Expand Down Expand Up @@ -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.

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

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

Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/filters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading