-
Notifications
You must be signed in to change notification settings - Fork 141
/
configuration.md
208 lines (150 loc) · 8.15 KB
/
configuration.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
---
title: "Traefik Mesh Configuration"
description: "The configuration for Traefik Mesh is broken down into two parts: the static configuration, and the dynamic configuration. Read the docs to learn more."
---
# Configuration
The configuration for Traefik Mesh is broken down into two parts: the static configuration, and the dynamic configuration.
The static configuration is configured when the service mesh is installed and is configured via the `values.yaml` file in the Helm install.
## Static configuration
- The controller image version as well as the Traefik image version used by mesh proxies can be manually defined if needed.
- Logging level and format for the controller and proxies can be defined.
- The default mesh mode can be configured. If this is not set, the default mode will be HTTP.
This means that new mesh services that are not specified will default to operate in HTTP mode.
- Tracing can be enabled.
- Access-Control List (ACL) mode can be enabled.
This configures Traefik Mesh to run in ACL mode, where all traffic is forbidden unless explicitly allowed via an SMI
[TrafficTarget](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-access/v1alpha2/traffic-access.md#traffictarget). Please see
the [SMI Specification](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-access/v1alpha2/traffic-access.md) for more information.
## Dynamic configuration
Dynamic configuration can be provided to Traefik Mesh using annotations on Kubernetes services and via SMI objects.
| Features | ACL disabled | ACL enabled |
|-----------------------|--------------|-------------|
| Traffic-Type | ✔ | ✔ |
| Scheme | ✔ | ✔ |
| Retry | ✔ | ✔ |
| Circuit-Breaker | ✔ | ✔ |
| Rate-Limit | ✔ | ✔ |
| Traffic-Split (SMI) | ✔ | ✔ |
| Traffic-Target (SMI) | ✘ | ✔ |
### Kubernetes Service Annotations
Annotations on services give the ability to configure how Traefik Mesh interprets them.
#### Traffic type
The traffic type can be configured by using the following annotation:
```yaml
mesh.traefik.io/traffic-type: "http"
```
This annotation can be set to either `http`, `tcp` or `udp` and will specifies the mode for that service operation.
If this annotation is not present, the mesh service will operate in the default mode specified in the static configuration.
!!! Info
For now, the `udp` traffic type does not work when ACL mode is enabled. In ACL mode, all traffic is forbidden unless it
is explicitly allowed with a [TrafficTarget](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-access/v1alpha2/traffic-access.md#traffictarget) and
unfortunately the SMI specification does not yet define a [Traffic Spec](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-specs/v1alpha4/traffic-specs.md) for `UDP`.
#### Scheme
The scheme used to define custom scheme for request:
```yaml
mesh.traefik.io/scheme: "h2c"
```
This annotation can be set to either `http`, `https` or `h2c` and is available for `mesh.traefik.io/traffic-type: "http"`.
??? Note "Limitations"
Please keep in mind, that if you set the scheme to `https` your service needs to expose itself via HTTPS as there is no
mTLS in Traefik Mesh.
#### Retry
Retries can be enabled by using the following annotation:
```yaml
mesh.traefik.io/retry-attempts: "2"
```
This annotation sets the number of retry attempts that Traefik Mesh will make if a network error occurs.
Please note that this value is a string, and needs to be quoted.
#### Circuit breaker
Circuit breaker can be enabled by using the following annotation:
```yaml
mesh.traefik.io/circuit-breaker-expression: "Expression"
```
This annotation sets the expression for circuit breaking.
The circuit breaker protects your system from stacking requests to unhealthy services (resulting in cascading failures).
When your system is healthy, the circuit is closed (normal operations). When your system becomes unhealthy, the circuit opens, and requests are no longer forwarded (but handled by a fallback mechanism).
All configuration options are available [here](https://doc.traefik.io/traefik/v2.0/middlewares/circuitbreaker/#configuration-options).
#### Rate Limit
Rate limiting can be enabled by using the following annotations:
```yaml
mesh.traefik.io/ratelimit-average: "100"
mesh.traefik.io/ratelimit-burst: "200"
```
These annotation sets average and burst requests per second limit for the service.
Please note that this value is a string, and needs to be quoted.
Further details about the rate limiting can be found [here](https://doc.traefik.io/traefik/v2.0/middlewares/ratelimit/#configuration-options).
### Service Mesh Interface
#### Access Control
The first step is to describe what the traffic of our server application looks like.
```yaml
---
apiVersion: specs.smi-spec.io/v1alpha3
kind: HTTPRouteGroup
metadata:
name: server-routes
namespace: server
spec:
matches:
- name: api
pathRegex: /api
methods: ["*"]
- name: metrics
pathRegex: /metrics
methods: ["GET"]
```
In this example, we define a set of HTTP routes for our `server` application.
More precisely, the `server` app is composed by two routes:
- The `api` route under the `/api` path, accepting all methods.
- The `metrics` routes under the `/metrics` path, accepting only `GET` requests.
Other types of route groups and detailed information are available [in the SMI specification](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-specs/v1alpha3/traffic-specs.md).
By default, all traffic is denied so we need to grant access to clients to our application. This is done by defining a `TrafficTarget`.
!!! Note "TrafficTarget Source & Destination"
Please note that TrafficTarget is a namespaced resource.
If the destination namespace is not populated, the TrafficTarget namespace will be used as the destination namespace.
The source namespace must be populated, as it cannot be inferred.
```yaml
---
apiVersion: access.smi-spec.io/v1alpha2
kind: TrafficTarget
metadata:
name: client-server-target
namespace: server
spec:
destination:
kind: ServiceAccount
name: server
namespace: server
rules:
- kind: HTTPRouteGroup
name: server-routes
matches:
- api
sources:
- kind: ServiceAccount
name: client
namespace: client
```
In this example, we grant access to all pods running with the service account `client` under the namespace `client` to the HTTP route `api` specified by on the group `server-routes` on all pods running with the service account `server` under the namespace `server`.
Any client running with the service account `client` under the `client` namespace accessing `server.server.traefik.mesh/api` is allowed to access the `/api` resource. Others will receive 404 answers from the Traefik Mesh node.
More information can be found [in the SMI specification](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-access/v1alpha2/traffic-access.md).
#### Traffic Splitting
SMI defines the `TrafficSplit` resource which allows to direct subsets of the traffic to different services.
```yaml
apiVersion: split.smi-spec.io/v1alpha3
kind: TrafficSplit
metadata:
name: server-split
namespace: server
spec:
service: server
backends:
- service: server-v1
weight: 80
- service: server-v2
weight: 20
```
In this example, we define a traffic split for our server service between two versions of our server, v1 and v2.
`server.server.traefik.mesh` directs 80% of the traffic to the server-v1 pods, and 20% of the traffic to the server-v2 pods.
More information can be found [in the SMI specification](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-split/v1alpha3/traffic-split.md).
#### Traffic Metrics
At the moment, Traefik Mesh does not implement the [Traffic Metrics specification](https://github.com/servicemeshinterface/smi-spec/blob/master/apis/traffic-metrics/v1alpha1/traffic-metrics.md).