Skip to content

Commit c4605e5

Browse files
christiangoerdeschristiangoerdes
authored
Add 7.1 migration guide (#2774)
* Add 7.1 migration guide * Update migration guide with ApiKey extractor renaming details * Expand migration guide with YAML syntax updates and renaming examples for 7.1 * Expand migration guide with YAML syntax improvements, renamed fields, and configuration changes for 7.1 * Expand migration guide with YAML syntax updates, field renaming examples, and configuration changes for 7.1 * wip * Expand migration guide with detailed YAML migration strategy, interceptor changes, and removal updates for 7.1 * Reorganize migration guide for clarity, reintroduce detailed 6.x to 7.x migration steps, and expand YAML configuration examples
1 parent 88a1e21 commit c4605e5

1 file changed

Lines changed: 323 additions & 11 deletions

File tree

‎docs/MIGRATION-GUIDE.md‎

Lines changed: 323 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,313 @@
1+
# Migrate to Membrane 7.1
2+
3+
This guide explains how to migrate existing Membrane installations to **Membrane 7.1**.
4+
Most breaking changes in **7.1** are **YAML-related**, so they mainly affect upgrades from **Membrane 7.x (YAML)** to **7.1**.
5+
6+
## Recommended Migration Strategy
7+
8+
1. **Start from your current version:**
9+
* **Coming from Membrane 6.x:** follow the [Migration Guide from Membrane 6.X to 7](#migration-guide-from-membrane-6x-to-7) first, then apply the 7.1 changes from this guide.
10+
* **Already on Membrane 7.x:** apply the changes from this guide.
11+
12+
2. **Decide on your configuration format**
13+
* **Staying on XML:** remove deprecated interceptors/syntax as listed and apply only the non-YAML changes.
14+
* **Using / moving to YAML:** migrate your YAML to the 7.1 syntax described here. If you’re coming from 6.x, use this guide as the “target YAML syntax”, but don’t skip the additional breaking changes covered in the [Migration Guide from Membrane 6.X to 7](#migration-guide-from-membrane-6x-to-7) .
15+
16+
## Removed Interceptors and Plugins
17+
18+
The following legacy interceptors have been removed:
19+
20+
| Removed | Replacement |
21+
|-----------------------------|-------------|
22+
| `MethodOverrideInterceptor` | - |
23+
24+
Remove these elements from your configuration and replace them with modern equivalents.
25+
26+
## Groovy
27+
- Return string from script does not set a content type of `text/html` anymore. User has to set the content type manually.
28+
29+
## ApiKey extractors:
30+
- Rename `headerExtractor` to `header`
31+
- Rename `queryParamExtractor` to `query`
32+
```yaml
33+
# before
34+
apiKey:
35+
extractors:
36+
- headerExtractor:
37+
name: X-API-KEY
38+
- queryParamExtractor:
39+
name: api-key
40+
41+
# now
42+
apiKey:
43+
extractors:
44+
- header:
45+
name: X-API-KEY
46+
- query:
47+
name: api-key
48+
```
49+
50+
## fileUserDataProvider
51+
- rename `fileUserDataProvider` to `htpasswdFileProvider`
52+
- rename `htpasswdPath` to `location`
53+
```yaml
54+
# before
55+
fileUserDataProvider:
56+
htpasswdPath: .htpasswd
57+
58+
# now
59+
htpasswdFileProvider:
60+
location: .htpasswd
61+
```
62+
63+
## YAML configuration syntax in list elements
64+
65+
* List items can now be written in *inline form* if the list accepts **exactly one** allowed element type (no polymorphic candidates) and the element is neither `collapsed` nor `noEnvelope`.
66+
* The old wrapper form remains supported: `- <kind>: { ... }`.
67+
68+
```yaml
69+
# before
70+
properties:
71+
- property:
72+
name: driverClassName
73+
value: org.h2.Driver
74+
- property:
75+
name: url
76+
value: jdbc:h2:./membranedb;AUTO_SERVER=TRUE
77+
78+
# now
79+
properties:
80+
- name: driverClassName
81+
value: org.h2.Driver
82+
- name: url
83+
value: jdbc:h2:./membranedb;AUTO_SERVER=TRUE
84+
```
85+
86+
87+
## OpenApi
88+
Renamed `specs` to `openapi`.
89+
90+
**Before:**
91+
```yaml
92+
# before
93+
api:
94+
port: 2000
95+
specs:
96+
- openapi:
97+
location: fruitshop-api.yml
98+
validateRequests: "yes"
99+
100+
# now (using the inline list item form)
101+
api:
102+
port: 2000
103+
openapi:
104+
- location: fruitshop-api.yml
105+
validateRequests: "yes"
106+
```
107+
108+
## setCookie
109+
- Use `noEnvelope` for `cookies` list
110+
```yaml
111+
# before
112+
setCookies:
113+
cookies:
114+
- cookie:
115+
name: foo
116+
value: bar
117+
secure: false
118+
119+
# now (using the inline list item form)
120+
setCookies:
121+
- name: foo
122+
value: bar
123+
secure: false
124+
```
125+
126+
## balancer
127+
- `clustersFromSpring` was renamed to `clusters`
128+
- the extra `clusters` list layer was removed (you now define clusters directly)
129+
```yaml
130+
# before
131+
balancer:
132+
clustersFromSpring:
133+
- clusters:
134+
- cluster:
135+
nodes:
136+
- node:
137+
host: localhost
138+
port: 4000
139+
- node:
140+
host: localhost
141+
port: 4001
142+
143+
# now (using the inline list item form)
144+
balancer:
145+
clusters:
146+
- nodes:
147+
- host: localhost
148+
port: 4000
149+
- host: localhost
150+
port: 4001
151+
```
152+
153+
## choose
154+
- `cases:` is gone (the case list is now **noEnvelope** under `choose`)
155+
- `otherwise` is now a **list item** inside `choose`
156+
- Only **one** `otherwise` is allowed, and it must be the **last** item of the list
157+
```yaml
158+
# before
159+
choose:
160+
cases:
161+
- case:
162+
test: foo
163+
flow:
164+
- log: {}
165+
otherwise:
166+
- return: {}
167+
168+
# now
169+
choose:
170+
- case:
171+
test: foo
172+
flow:
173+
- log: {}
174+
- otherwise:
175+
- return: {}
176+
```
177+
178+
## chainDef and chain
179+
- `chainDef` was removed.
180+
- Define chains with `chain` and reference them like any other component via `$ref`.
181+
```yaml
182+
# before
183+
components:
184+
log:
185+
chainDef:
186+
flow:
187+
- log: {}
188+
---
189+
api:
190+
port: 2000
191+
flow:
192+
- chain:
193+
ref: '#/components/log'
194+
195+
```
196+
```yaml
197+
# now
198+
components:
199+
log:
200+
chain:
201+
- log: {}
202+
---
203+
api:
204+
port: 2000
205+
flow:
206+
- $ref: '#/components/log'
207+
```
208+
209+
### YAML configuration for Elements with exactly one configurable Attribute
210+
Some Elements with **exactly one** configurable Attribute can now be configured inline. This **does not** apply to all elements with exactly one configurable Attribute.
211+
212+
The supported elements are: `api.description`, `publicURL`, `headerFilter.include`, `headerFilter.exclude`, `keyTable`, `scopeTable`, `accessControl.allow`, `accessControl.deny`, `counter`, `mutation`
213+
214+
#### headerFilter
215+
```yaml
216+
# before
217+
headerFilter:
218+
rules:
219+
- include:
220+
pattern: "X-XSS-Protection"
221+
- exclude:
222+
pattern: "X-.*"
223+
224+
# now
225+
headerFilter:
226+
rules:
227+
- include: "X-XSS-Protection"
228+
- exclude: "X-.*"
229+
```
230+
231+
#### mutation
232+
```yaml
233+
# before
234+
graphQLProtection:
235+
disallow:
236+
- mutation:
237+
name: foo
238+
239+
# now
240+
graphQLProtection:
241+
disallow:
242+
- mutation: foo
243+
```
244+
245+
#### counter
246+
```yaml
247+
# before
248+
counter:
249+
name: mock1
250+
251+
# now
252+
counter: mock1
253+
```
254+
255+
#### keyTable
256+
```yaml
257+
# before
258+
apiKey:
259+
stores:
260+
- databaseApiKeyStore:
261+
keyTable:
262+
name: foo
263+
264+
# now
265+
apiKey:
266+
stores:
267+
- databaseApiKeyStore:
268+
keyTable: foo
269+
```
270+
271+
#### scopeTable
272+
```yaml
273+
# before
274+
apiKey:
275+
stores:
276+
- databaseApiKeyStore:
277+
scopeTable:
278+
name: foo
279+
280+
# now
281+
apiKey:
282+
stores:
283+
- databaseApiKeyStore:
284+
scopeTable: foo
285+
```
286+
287+
#### publicURL
288+
```yaml
289+
# before
290+
publicURL:
291+
publicURL: /foo
292+
293+
# now
294+
publicURL: /foo
295+
```
296+
297+
#### api.description
298+
```yaml
299+
# before
300+
api:
301+
description:
302+
content: Demo Api
303+
304+
# now
305+
api:
306+
description: Demo Api
307+
```
308+
309+
---
310+
1311
# Migration Guide from Membrane 6.X to 7
2312

3313
This guide describes how to migrate existing Membrane installations from version 6 to version 7.
@@ -27,24 +337,24 @@ Example:
27337
<!-- before -->
28338
<router production="true" />
29339
30-
<!-- now -->
340+
<!-- now -->
31341
<router>
32-
<configuration production="true" />
342+
<configuration production="true" />
33343
</router>
34344
```
35345

36346
## 3. Removed Interceptors and Plugins
37347

38348
The following legacy interceptors have been removed:
39349

40-
| Removed | Replacement |
41-
|--------|-----------------------------------------------------------------------------|
42-
| `gateKeeperClient` | Gatekeeper is not supported anymore |
43-
| `wadl` | Use OpenAPI |
44-
| `xmlSessionIdExtractor` | Use language based session handling. See examples/loadbalancing/4-session |
350+
| Removed | Replacement |
351+
|---------------------------|-----------------------------------------------------------------------------|
352+
| `gateKeeperClient` | Gatekeeper is not supported anymore |
353+
| `wadl` | Use OpenAPI |
354+
| `xmlSessionIdExtractor` | Use language based session handling. See examples/loadbalancing/4-session |
45355
| `telekomSMSTokenProvider` | The SMS provider doesn't offer the needed SMS service anymore. |
46-
| `groovyTemplate` | `template` offers the same functionality including Groovy language support. |
47-
| `urlNormalizer` | - |
356+
| `groovyTemplate` | `template` offers the same functionality including Groovy language support. |
357+
| `urlNormalizer` | - |
48358

49359
Remove these elements from your configuration and replace them with modern equivalents.
50360

@@ -74,7 +384,7 @@ api:
74384
- deny: 127.0.0.1
75385
- allow: ::1
76386
```
77-
387+
78388

79389
## 5. Internal Routing
80390

@@ -136,6 +446,8 @@ The JMX ObjectName format has changed to: `io.membrane-api:00=routers, name=`
136446
```
137447
- `HttpClientInterceptor.setAdjustHeader(boolean)` has been removed. Header adjustment is now configured via `HttpClientConfiguration`.
138448

449+
---
450+
139451
# Migration from 5.X to 6
140452

141453
## Swagger 2
@@ -205,5 +517,5 @@ Default naming scheme for `<serviceProxys>` has changed. This might affect exist
205517
- `ConditionalInterceptor` is renamed in `IfInterceptor`
206518

207519
## `jwtSign`
208-
- `expiryTime` has been renamed to `expirySeconds`.
520+
- `expiryTime` has been renamed to `expirySeconds`.
209521
- HTTP response in case of JWT validation failure was changed to Problem JSON.

0 commit comments

Comments
 (0)