Skip to content

Commit 09c088c

Browse files
lena-larionovacloudjumpercat
lena-larionova
and
cloudjumpercat
authored
feat(deck): deck file convert for LTS (#2733)
* deck file convert for LTS * move instruction to more accurate location during upgrade process * fix typo * add plugin conversions for 2.8 to 3.4 * add new_in * split conversion steps into how-tos * Apply suggestions from code review Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --------- Co-authored-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
1 parent ee4c87d commit 09c088c

File tree

9 files changed

+363
-42
lines changed

9 files changed

+363
-42
lines changed

‎app/_how-tos/convert-gateway-lts-2.8-3.4.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Convert Gateway entity configuration from 2.8 to 3.4
3+
content_type: how_to
4+
5+
description: Use decK to upgrade from {{ site.base_gateway }} 2.8 LTS to 3.4 LTS
6+
7+
permalink: /gateway/upgrade/convert-lts-28-34/
8+
9+
products:
10+
- gateway
11+
12+
works_on:
13+
- on-prem
14+
- konnect
15+
16+
min_version:
17+
gateway: '3.4'
18+
19+
tags:
20+
- upgrade
21+
22+
tldr:
23+
q: How do I convert Gateway entity configuration from 2.8 to 3.4, as part of my upgrade process?
24+
a: Run `deck file convert` and review the results.
25+
tools: []
26+
27+
prereqs:
28+
skip_product: true
29+
inline:
30+
- title: "{{site.base_gateway}} {% new_in 2.8 %}"
31+
content: "You have {{site.base_gateway}} running on version 2.8."
32+
- title: |
33+
decK &nbsp; {% new_in 1.47 %}
34+
content: |
35+
decK is a CLI tool for managing {{site.base_gateway}} declaratively with state files.
36+
To complete this tutorial, install [decK](/deck/) **version 1.47** or later.
37+
38+
This guide uses `deck gateway apply`, which directly applies entity configuration to your Gateway instance.
39+
We recommend upgrading your decK installation to take advantage of this tool.
40+
41+
You can check your current decK version with `deck version`.
42+
43+
related_resources:
44+
- text: deck file convert
45+
url: /deck/file/convert/
46+
- text: Convert Gateway entity configuration from 3.4 to 3.10
47+
url: /gateway/upgrade/convert-lts-34-310/
48+
- text: Gateway LTS 2.8 to 3.4 upgrade
49+
url: /gateway/upgrade/lts-upgrade-28-34/
50+
- text: Gateway LTS 3.4 to 3.10 upgrade
51+
url: /gateway/upgrade/lts-upgrade-34-310/
52+
53+
faqs:
54+
- q: I ran `deck file convert` but there are still errors or warnings, what do I do?
55+
a: Manually validate the file, then make any necessary updates to your state file.
56+
- q: Can I still apply configuration if there are warnings?
57+
a: |
58+
If you have validated the configuration and found no issues but are still getting a warning, the warning may be a false positive.
59+
You can still apply the configuration, but do so at your own risk.
60+
61+
If you run into false positives, [file an issue](https://github.com/Kong/deck/issues) to let us know.
62+
63+
automated_tests: false
64+
---
65+
66+
67+
You can use `deck file convert` to automatically perform many of the changes that occurred between {{site.base_gateway}} 2.8 LTS and 3.4 LTS versions.
68+
69+
See the [deck file convert](/deck/file/convert/) reference for a list of all the conversions that decK will perform.
70+
71+
{:.info}
72+
> **Note:** Update your decK version to 1.47 or later before converting files.
73+
74+
## Export configuration
75+
76+
Use an existing backup file, or export the entity configuration an existing installation, for example 3.4:
77+
78+
```sh
79+
deck gateway dump -o kong-2.8.yaml \
80+
--konnect-token "$YOUR_KONNECT_PAT" \
81+
--konnect-control-plane-name $YOUR_CP_NAME
82+
```
83+
{: data-deployment-topology="konnect" }
84+
85+
```sh
86+
deck gateway dump -o kong-2.8.yaml --all-workspaces
87+
```
88+
{: data-deployment-topology="on-prem" }
89+
90+
91+
## Convert configuration
92+
93+
Use `deck file convert` with version flags to convert the entity configuration:
94+
95+
```sh
96+
deck file convert \
97+
--from 2.8 \
98+
--to 3.4 \
99+
--input-file kong-2.8.yaml \
100+
--output-file kong-3.4.yaml
101+
```
102+
103+
## Review and validate
104+
105+
1. Review the output of the command.
106+
107+
`deck file convert` creates a new file and prints warnings and errors for any changes that can't be made automatically.
108+
These changes require some manual work, so adjust your configuration accordingly.
109+
110+
1. Validate the converted file in a test environment.
111+
112+
Make sure to manually audit the generated file before applying the configuration in production.
113+
These changes may not be fully correct or exhaustive, so manual validation is strongly recommended.
114+
115+
## Apply configuration
116+
117+
Upload your new configuration to a {{site.konnect_short_name}} control plane:
118+
{: data-deployment-topology="konnect" }
119+
120+
```sh
121+
deck gateway sync kong-3.4.yaml \
122+
--konnect-token "$YOUR_KONNECT_PAT" \
123+
--konnect-control-plane-name $YOUR_CP_NAME
124+
```
125+
{: data-deployment-topology="konnect" }
126+
127+
Upload your new configuration to the new environment:
128+
{: data-deployment-topology="on-prem" }
129+
130+
```sh
131+
deck gateway sync kong-3.4.yaml \
132+
--workspace default
133+
```
134+
{: data-deployment-topology="on-prem" }

‎app/_how-tos/convert-gateway-lts-3.4-3.10.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Convert Gateway entity configuration from 3.4 to 3.10
3+
content_type: how_to
4+
5+
description: Use decK to upgrade from {{ site.base_gateway }} 3.4 LTS to 3.10 LTS
6+
7+
permalink: /gateway/upgrade/convert-lts-34-310/
8+
9+
products:
10+
- gateway
11+
12+
works_on:
13+
- on-prem
14+
- konnect
15+
16+
min_version:
17+
gateway: '3.10'
18+
19+
tags:
20+
- upgrade
21+
22+
tldr:
23+
q: How do I convert Gateway entity configuration from 3.4 to 3.10, as part of my upgrade process?
24+
a: Run `deck file convert` and review the results.
25+
tools: []
26+
27+
prereqs:
28+
skip_product: true
29+
inline:
30+
- title: "{{site.base_gateway}} {% new_in 3.4 %}"
31+
content: "You have {{site.base_gateway}} running on version 3.4."
32+
- title: |
33+
decK &nbsp; {% new_in 1.51 %}
34+
content: |
35+
decK is a CLI tool for managing {{site.base_gateway}} declaratively with state files.
36+
To complete this tutorial, install [decK](/deck/) **version 1.51** or later.
37+
38+
This guide uses `deck gateway apply`, which directly applies entity configuration to your Gateway instance.
39+
We recommend upgrading your decK installation to take advantage of this tool.
40+
41+
You can check your current decK version with `deck version`.
42+
43+
related_resources:
44+
- text: deck file convert
45+
url: /deck/file/convert/
46+
- text: Convert Gateway entity configuration from 2.8 to 3.4
47+
url: /deck/reference/3.0-upgrade/
48+
- text: Gateway LTS 3.4 to 3.10 upgrade guide
49+
url: /gateway/upgrade/lts-upgrade-28-34/
50+
- text: Gateway LTS 3.10 to 3.10 upgrade guide
51+
url: /gateway/upgrade/lts-upgrade-34-310/
52+
53+
faqs:
54+
- q: I ran `deck file convert` but there are still errors or warnings, what do I do?
55+
a: Manually validate the file, then make any necessary updates to your state file.
56+
- q: Can I still apply configuration if there are warnings?
57+
a: |
58+
If you have validated the configuration and found no issues but are still getting a warning, the warning may be a false positive.
59+
You can still apply the configuration, but do so at your own risk.
60+
61+
If you run into false positives, [file an issue](https://github.com/Kong/deck/issues) to let us know.
62+
63+
automated_tests: false
64+
---
65+
66+
67+
You can use `deck file convert` to automatically perform many of the changes that occurred between {{site.base_gateway}} 3.4 LTS and 3.10 LTS versions.
68+
69+
See the [deck file convert](/deck/file/convert/) reference for a list of all the conversions that decK will perform.
70+
71+
{:.info}
72+
> **Note:** Update your decK version to 1.51 or later before converting files.
73+
74+
## Export configuration
75+
76+
Use an existing backup file, or export the entity configuration an existing installation, for example 3.10:
77+
78+
```sh
79+
deck gateway dump -o kong-3.4.yaml \
80+
--konnect-token "$YOUR_KONNECT_PAT" \
81+
--konnect-control-plane-name $YOUR_CP_NAME
82+
```
83+
{: data-deployment-topology="konnect" }
84+
85+
```sh
86+
deck gateway dump -o kong-3.4.yaml --all-workspaces
87+
```
88+
{: data-deployment-topology="on-prem" }
89+
90+
91+
## Convert configuration
92+
93+
Use `deck file convert` with version flags to convert the entity configuration:
94+
95+
```sh
96+
deck file convert \
97+
--from 3.4 \
98+
--to 3.10 \
99+
--input-file kong-3.4.yaml \
100+
--output-file kong-3.10.yaml
101+
```
102+
103+
## Review and validate
104+
105+
1. Review the output of the command.
106+
107+
`deck file convert` creates a new file and prints warnings and errors for any changes that can't be made automatically.
108+
These changes require some manual work, so adjust your configuration accordingly.
109+
110+
1. Validate the converted file in a test environment.
111+
112+
Make sure to manually audit the generated file before applying the configuration in production.
113+
These changes may not be fully correct or exhaustive, so manual validation is strongly recommended.
114+
115+
## Apply configuration
116+
117+
Upload your new configuration to a {{site.konnect_short_name}} control plane:
118+
{: data-deployment-topology="konnect" }
119+
120+
```sh
121+
deck gateway sync kong-3.10.yaml \
122+
--konnect-token "$YOUR_KONNECT_PAT" \
123+
--konnect-control-plane-name $YOUR_CP_NAME
124+
```
125+
{: data-deployment-topology="konnect" }
126+
127+
Upload your new configuration to the new environment:
128+
{: data-deployment-topology="on-prem" }
129+
130+
```sh
131+
deck gateway sync kong-3.10.yaml \
132+
--workspace default
133+
```
134+
{: data-deployment-topology="on-prem" }

‎app/_includes/upgrade/lts-upgrade.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Read this document thoroughly to successfully complete the upgrade process, as i
3333
* [Kubernetes version and Helm prerequisites](/kubernetes-ingress-controller/support/)
3434
* [Hardware resources](/gateway/resource-sizing-guidelines/)
3535
* [Database and dependency versions](/gateway/third-party-support/)
36-
* If you're using decK, [upgrade it to the latest version](/deck/).
36+
* [decK installed and upgraded to the latest version](/deck/).
3737

3838
{% if include.lts_version_from == "2.8" %}
3939
{:.info}

‎app/deck/file/convert.md‎

Lines changed: 44 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,12 @@ breadcrumbs:
1919
related_resources:
2020
- text: decK gateway commands
2121
url: /deck/gateway/
22-
22+
- text: Upgrade to {{ site.base_gateway }} 3.x with decK
23+
url: /deck/reference/3.0-upgrade/
24+
- text: Convert Gateway entity config from 2.8 LTS to 3.4 LTS
25+
url: /gateway/upgrade/convert-lts-28-34/
26+
- text: Convert Gateway entity config from 3.4 LTS to 3.10 LTS
27+
url: /gateway/upgrade/convert-lts-34-310/
2328
tags:
2429
- declarative-config
2530
---
@@ -32,9 +37,44 @@ deck file convert --input-file kong2x.yaml --from kong-gateway-2.x --to kong-gat
3237

3338
## Applied transformations
3439

35-
- `kong-gateway-2.x` to `kong-gateway-3.x`
36-
- Prefix any paths that look like a regular expression with a `~`
37-
- Generate default values for missing `namespace` fields in any Rate Limiting Advanced plugins
40+
The following table lists the transformations that `deck file convert` performs:
41+
42+
{% table %}
43+
columns:
44+
- title: Conversion path
45+
key: path
46+
- title: Applied transformations
47+
key: transforms
48+
rows:
49+
- path: "`kong-gateway-2.x` to `kong-gateway-3.x`"
50+
transforms: |
51+
- Prefix any paths that look like a regular expression with a `~`
52+
- Generate default values for missing `namespace` fields in any Rate Limiting Advanced plugins
53+
- Convert decK file `_format_version` from 1.1 to 3.0
54+
- path: |
55+
`2.8` to `3.4` {% new_in 1.47.0 %}
56+
transforms: |
57+
- Prefix any paths that look like a regular expression with a `~`
58+
- Generate default values for missing `namespace` fields in any Rate Limiting Advanced plugins
59+
- Convert decK file `_format_version` from 1.1 to 3.0
60+
- ACL, Bot Detection, IP Restriction, and Canary plugins:
61+
- Convert `config.blacklist` to `config.deny`
62+
- Convert `config.whitelist` to `config.allow`
63+
- AWS Lambda plugin:
64+
- Remove the deprecated `config.proxy_scheme` parameter
65+
- Pre-Function and Post-Function plugins:
66+
- Convert `config.functions` to `config.access`
67+
- path: |
68+
`3.4` to `3.10` {% new_in 1.51.0 %}
69+
transforms: |
70+
- Any plugins that use Redis configurations:
71+
- Transform `redis.cluster_addresses` into `redis.cluster_nodes`
72+
- Transform `redis.sentinel_addresses` into `redis.sentinel_nodes`
73+
- AI plugins:
74+
- Transform `model.options.upstream_path` into `model.options.upstream_url`
75+
- AI Rate Limiting Advanced plugin:
76+
- Transform `llm_providers.window_size` from a single value to a list
77+
{% endtable %}
3878

3979
## Command usage
4080

0 commit comments

Comments
 (0)