From d69ac21e44c5e113c263f9f9e13c541ecfe68026 Mon Sep 17 00:00:00 2001 From: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Date: Thu, 27 Jun 2024 13:24:06 -0700 Subject: [PATCH] Feat: decK gateway CLI (#7585) * update deck commands in deck docs * update deck commands in all product docs except deck * appease vale * update some missed commands --- app/_data/docs_nav_deck_1.28.x.yml | 1 + app/_data/docs_nav_deck_1.29.x.yml | 1 + app/_data/docs_nav_deck_1.30.x.yml | 1 + app/_data/docs_nav_deck_1.34.x.yml | 1 + app/_data/docs_nav_deck_1.35.x.yml | 1 + app/_data/docs_nav_deck_1.36.x.yml | 1 + app/_data/docs_nav_deck_1.37.x.yml | 1 + app/_data/docs_nav_deck_1.38.x.yml | 1 + app/_data/docs_nav_deck_1.39.x.yml | 1 + .../kong-inc/pre-function/how-to/_index.md | 2 +- app/_includes/md/gateway/db-less-upgrade.md | 2 +- app/_src/deck/design-architecture.md | 3 - app/_src/deck/faqs.md | 6 +- app/_src/deck/guides/apiops.md | 26 ++++++- app/_src/deck/guides/backup-restore.md | 30 ++++++++ app/_src/deck/guides/best-practices.md | 14 ++-- .../deck/guides/ci-driven-configuration.md | 10 +-- .../deduplicate-plugin-configuration.md | 2 +- app/_src/deck/guides/defaults-v2.md | 34 +++++++-- app/_src/deck/guides/defaults.md | 59 +++++++++++---- .../deck/guides/distributed-configuration.md | 13 +++- app/_src/deck/guides/environment-variables.md | 13 +++- app/_src/deck/guides/getting-started.md | 71 +++++++++++++++++-- app/_src/deck/guides/kong-enterprise.md | 37 +++++++++- app/_src/deck/guides/konnect.md | 49 +++++++++++-- app/_src/deck/guides/multi-file-state.md | 50 ++++++++++--- app/_src/deck/guides/run-with-docker-1.28.md | 63 ++++++++++++++++ app/_src/deck/guides/vaults.md | 11 ++- app/_src/deck/reference/deck_gateway_diff.md | 2 +- app/_src/deck/reference/deck_gateway_sync.md | 2 +- .../deck/reference/deck_gateway_validate.md | 2 +- app/_src/gateway/breaking-changes/30x.md | 4 +- .../plugin-ordering/get-started.md | 6 +- .../gateway/migrate-cassandra-to-postgres.md | 4 +- app/_src/gateway/upgrade-v3.md | 4 +- .../gateway/upgrade/backup-and-restore.md | 22 +++--- app/konnect/dev-portal/troubleshoot/index.md | 2 +- app/konnect/gateway-manager/backup-restore.md | 14 ++-- .../control-plane-groups/conflicts.md | 2 +- .../control-plane-groups/migrate.md | 19 +++-- .../gateway-manager/declarative-config.md | 36 +++++----- 41 files changed, 496 insertions(+), 127 deletions(-) create mode 100644 app/_src/deck/guides/run-with-docker-1.28.md diff --git a/app/_data/docs_nav_deck_1.28.x.yml b/app/_data/docs_nav_deck_1.28.x.yml index 59ac97f2a7fe..7c1532d5faf7 100644 --- a/app/_data/docs_nav_deck_1.28.x.yml +++ b/app/_data/docs_nav_deck_1.28.x.yml @@ -46,6 +46,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.29.x.yml b/app/_data/docs_nav_deck_1.29.x.yml index ded99ff804b3..d753008259ef 100644 --- a/app/_data/docs_nav_deck_1.29.x.yml +++ b/app/_data/docs_nav_deck_1.29.x.yml @@ -46,6 +46,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.30.x.yml b/app/_data/docs_nav_deck_1.30.x.yml index 2f3d74bd1c0b..5c1cb90e36c3 100644 --- a/app/_data/docs_nav_deck_1.30.x.yml +++ b/app/_data/docs_nav_deck_1.30.x.yml @@ -46,6 +46,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.34.x.yml b/app/_data/docs_nav_deck_1.34.x.yml index b19f4f7e53fc..dde0c70af84f 100644 --- a/app/_data/docs_nav_deck_1.34.x.yml +++ b/app/_data/docs_nav_deck_1.34.x.yml @@ -46,6 +46,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.35.x.yml b/app/_data/docs_nav_deck_1.35.x.yml index 661bcd899c29..aa736d9febb4 100644 --- a/app/_data/docs_nav_deck_1.35.x.yml +++ b/app/_data/docs_nav_deck_1.35.x.yml @@ -49,6 +49,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.36.x.yml b/app/_data/docs_nav_deck_1.36.x.yml index 4397dddc9d1a..c86291655009 100644 --- a/app/_data/docs_nav_deck_1.36.x.yml +++ b/app/_data/docs_nav_deck_1.36.x.yml @@ -48,6 +48,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.37.x.yml b/app/_data/docs_nav_deck_1.37.x.yml index 03bbc1cd465b..d73b507e85c7 100644 --- a/app/_data/docs_nav_deck_1.37.x.yml +++ b/app/_data/docs_nav_deck_1.37.x.yml @@ -48,6 +48,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.38.x.yml b/app/_data/docs_nav_deck_1.38.x.yml index 713e8a9d098e..84a082cbc92e 100644 --- a/app/_data/docs_nav_deck_1.38.x.yml +++ b/app/_data/docs_nav_deck_1.38.x.yml @@ -48,6 +48,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_data/docs_nav_deck_1.39.x.yml b/app/_data/docs_nav_deck_1.39.x.yml index 7f07e5cd0fcd..3404330a8f93 100644 --- a/app/_data/docs_nav_deck_1.39.x.yml +++ b/app/_data/docs_nav_deck_1.39.x.yml @@ -48,6 +48,7 @@ items: url: /guides/konnect/ - text: Run decK with Docker url: /guides/run-with-docker/ + src: /deck/guides/run-with-docker-1.28 - text: Using Multiple Files to Store Configuration url: /guides/multi-file-state/ - text: De-duplicate Plugin Configuration diff --git a/app/_hub/kong-inc/pre-function/how-to/_index.md b/app/_hub/kong-inc/pre-function/how-to/_index.md index 7d87fae91659..2f383be0c09d 100644 --- a/app/_hub/kong-inc/pre-function/how-to/_index.md +++ b/app/_hub/kong-inc/pre-function/how-to/_index.md @@ -103,7 +103,7 @@ Let's test out the Pre-function plugin by filtering requests based on header nam 1. Sync the file to your {{site.base_gateway}} instance: ```sh - deck sync + deck gateway sync kong.yaml ``` {% endnavtab %} diff --git a/app/_includes/md/gateway/db-less-upgrade.md b/app/_includes/md/gateway/db-less-upgrade.md index afc0ae018b48..de7841862d4b 100644 --- a/app/_includes/md/gateway/db-less-upgrade.md +++ b/app/_includes/md/gateway/db-less-upgrade.md @@ -3,6 +3,6 @@ In DB-less mode, each independent {{site.base_gateway}} node loads a copy of dec configuration data into memory without persistent database storage, so failure of some nodes doesn't spread to other nodes. Deployments in this mode should use the [rolling upgrade](/gateway/{{include.release}}/upgrade/rolling-upgrade/) strategy. -You could parse the validity of the declarative YAML contents with version Y, using the `deck validate` or the `kong config parse` command. +You could parse the validity of the declarative YAML contents with version Y, using the `deck gateway validate` or the `kong config parse` command. You must back up your current `kong.yaml` file before starting the upgrade. diff --git a/app/_src/deck/design-architecture.md b/app/_src/deck/design-architecture.md index 286eba952da5..f8413ce1ff19 100644 --- a/app/_src/deck/design-architecture.md +++ b/app/_src/deck/design-architecture.md @@ -72,7 +72,4 @@ decK is written in Go because: - Go's compiler spits out a static compiled binary, meaning no other dependency need to be installed on the system. This gives a very good end-user experience as installing, downloading, and copying a single binary is easy and fast. -- decK's original goal was much larger than what it is today. If we decide to - pursue larger goals (think a control-plane for Kong) in future, - Go is probably the best language available to write that type of software. - The original author was familiar with Go :) diff --git a/app/_src/deck/faqs.md b/app/_src/deck/faqs.md index 532f97857cfb..9943da86faae 100644 --- a/app/_src/deck/faqs.md +++ b/app/_src/deck/faqs.md @@ -58,8 +58,8 @@ If you are using Kong alongside a database, you need decK because: the config file is the same. This feature is designed in decK to integrate decK with a CI system or a `cronjob` which periodically checks for drifts and alerts a team if needed. -- `decK dump` outputs a more human-readable configuration file compared - to Kong's `db_import`. +- `deck dump` or `deck gateway dump` outputs a more human-readable configuration file + compared to Kong's `db_import`. However, decK has the following limitations which might or might not affect your use case: @@ -117,7 +117,7 @@ It is derived from the combination of words 'declarative' and 'Kong'. Yes. The decK team maintains a JSON schema that you can use to validate YAML files on [Github](https://github.com/Kong/go-database-reconciler/blob/main/pkg/file/kong_json_schema.json). You can use the schema with a text editor to provide JIT YAML validation. For example, to use the JSON schema with VS Code: 1. Install the Red Hat YAML extension: -```console +```sh code --install-extension redhat.vscode-yaml ``` diff --git a/app/_src/deck/guides/apiops.md b/app/_src/deck/guides/apiops.md index 83f61a489ecd..a81546c050fb 100644 --- a/app/_src/deck/guides/apiops.md +++ b/app/_src/deck/guides/apiops.md @@ -83,11 +83,18 @@ upstreams: [] > **Note**: The {{site.base_gateway}} [getting started guide](/gateway/latest/get-started/) can help you quickly run a gateway in Docker to follow along with these instructions. -You can synchronize this directly to the gateway using `deck sync`: +You can synchronize this directly to the gateway using `sync`: +{% if_version lte:1.27.x %} ```sh deck sync -s httpbin.yaml ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway sync httpbin.yaml +``` +{% endif_version %} Which creates the service and route: @@ -171,18 +178,35 @@ deck file patch --state merged-kong.yaml \ The final `kong.yaml` file is a full configuration you can synchronize to the gateway: +{% if_version lte:1.27.x %} ```sh deck sync -s kong.yaml ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway sync kong.yaml +``` +{% endif_version %} Here is an example of putting the above together in a Unix-style pipeline: +{% if_version lte:1.27.x %} ```sh deck file openapi2kong --spec oas.yaml --output-file httpbin.yaml && deck file merge httpbin.yaml another-httpbin.yaml | deck file patch --selector "$.services[*]" --value 'protocol: "https"' | deck sync -s - ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck file openapi2kong --spec oas.yaml --output-file httpbin.yaml && + deck file merge httpbin.yaml another-httpbin.yaml | + deck file patch --selector "$.services[*]" --value 'protocol: "https"' | + deck gateway sync +``` +{% endif_version %} Most commonly, you will use the commands from CI/CD tools built into your version control system to bring full and partial {{site.base_gateway}} configurations together to create APIOps for your diff --git a/app/_src/deck/guides/backup-restore.md b/app/_src/deck/guides/backup-restore.md index 5d59938ebd41..90edce290953 100644 --- a/app/_src/deck/guides/backup-restore.md +++ b/app/_src/deck/guides/backup-restore.md @@ -13,13 +13,22 @@ to find out which entity configurations can be backed up. To back up {{site.base_gateway}}'s configuration, use the `dump` command: +{% if_version lte:1.27.x %} ```sh deck dump ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway dump -o kong.yaml +``` +{% endif_version %} + This generates a `kong.yaml` file with the entire configuration of {{site.base_gateway}}, if possible. Then, restore this file back to {{site.base_gateway}} using the `sync` command: +{% if_version lte:1.27.x %} 1. Preview the changes that decK will perform: ```sh @@ -31,6 +40,20 @@ Then, restore this file back to {{site.base_gateway}} using the `sync` command: ```sh deck sync ``` +{% endif_version %} +{% if_version gte:1.28.x %} +1. Preview the changes that decK will perform: + + ```sh + deck gateway diff kong.yaml + ``` + +2. Re-create the entities in {{site.base_gateway}}: + + ```sh + deck gateway sync kong.yaml + ``` +{% endif_version %} ## Manage a subset of configuration @@ -44,9 +67,16 @@ in {{site.base_gateway}} share a common tag(s). Assuming you have such a common tag (for example, let's call it `foo-tag`), you can use it to export only a subset of the configuration: +{% if_version lte:1.27.x %} ```sh deck dump --select-tag foo-tag ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway dump -o kong.yaml --select-tag foo-tag +``` +{% endif_version %} If you observe the file generated by decK, you will see the following section: diff --git a/app/_src/deck/guides/best-practices.md b/app/_src/deck/guides/best-practices.md index b4290859b418..e65e3a610e34 100644 --- a/app/_src/deck/guides/best-practices.md +++ b/app/_src/deck/guides/best-practices.md @@ -5,16 +5,16 @@ content_type: explanation - Always ensure that you have one decK process running at any time. Multiple processes step on each other and can corrupt Kong's configuration. -- Do not mix up decK's declarative configuration with `cURL` or any other +- Do not mix up decK's declarative configuration with cURL or any other script. Either manage the configuration with decK or manage it with your homegrown script. Mixing the two on the same dataset is cumbersome and error-prone. - If you have a very large installation, you can split out your configuration into smaller subsets. You can find more info for it in the guide to practicing [distributed configuration](/deck/{{page.release}}/guides/distributed-configuration/). -- Always use a pinned version of decK and Kong. +- Always use a pinned version of decK and {{site.base_gateway}}. Use a specific version of decK in production to achieve declarative - configuration. If you upgrade to a new version of decK or Kong, + configuration. If you upgrade to a new version of decK or {{site.base_gateway}}, please safely test the changes in a staging environment first. - decK does not manage encryption of sensitive information. The state file stores the private keys of your certificates and credentials of consumers in @@ -26,17 +26,17 @@ content_type: explanation or manage them using decK. Declarative configuration is only meant for entity configuration. It is not meant for end-user data, which can easily grow into hundreds of thousands or millions of records. -- Always run a `deck diff` command before running a `deck sync` +- Always run a `diff` command before running a `sync` to ensure that the change is correct. - Adopt a [CI-driven configuration](/deck/{{page.release}}/guides/ci-driven-configuration/) practice. - Always secure Kong's Admin API with a reliable authentication method. - Do not write the state file by hand to avoid errors. - Use Kong's Admin API to configure Kong for the first time, then + Use Kong's Admin API to configure {{site.base_gateway}} for the first time, then export the configuration to a declarative configuration file. Any subsequent changes should be made by manually editing the file and pushing - the change via CI. If you're making a larger change, make the change in Kong first, then + the change via CI. If you're making a larger change, make the change in {{site.base_gateway}} first, then export the new file. Then you can `diff` the two state files to review the changes being made. -- Configure a `cronjob` to run `deck diff` periodically to ensure that Kong's +- Configure a `cronjob` to run `diff` periodically to ensure that {{site.base_gateway}}'s database is in sync with the state file checking into your Git repositories. Trigger an alert if decK detects a drift in the configuration. diff --git a/app/_src/deck/guides/ci-driven-configuration.md b/app/_src/deck/guides/ci-driven-configuration.md index cf1976f309e8..9c44a866b59e 100644 --- a/app/_src/deck/guides/ci-driven-configuration.md +++ b/app/_src/deck/guides/ci-driven-configuration.md @@ -13,13 +13,13 @@ Version Control System, or VCS) and then perform GitOps on Kong's configuration: - Any time a change needs to be performed, ask the developer to open a Pull or Merge Request, which can be reviewed by other humans. - You should use `deck validate` and `deck diff` commands in the CI to validate + You should use decK's `validate` and `diff` commands in the CI to validate and see if the target changes will be performed or not. - Although unlikely, it is possible that a `deck sync` command might fail + Although unlikely, it is possible that a `sync` command might fail even if the above two pass. If this happens, a human has to intervene and resolve the conflict or error manually. -- Once the configuration change is merged in, the CI should execute `deck diff` - again (to have a log of what is changing), followed by `deck sync`. +- Once the configuration change is merged in, the CI should execute `diff` + again (to have a log of what is changing), followed by `sync`. You should also have a `cronjob` in your CI or any other system, which verifies if the source of truth, meaning Kong's database is in the exact same state as @@ -29,5 +29,5 @@ as your are configure Kong but are never verifying. The system could be out of sync and can go undetected until another change is performed. Any time you use decK within an automated environment, including a -`deck ping` command in the beginning of your script can ease debugging +`ping` command in the beginning of your script can ease debugging in the future, as it usually rules out connectivity issues between decK and Kong. diff --git a/app/_src/deck/guides/deduplicate-plugin-configuration.md b/app/_src/deck/guides/deduplicate-plugin-configuration.md index f630963c978f..227b0a8fafa2 100644 --- a/app/_src/deck/guides/deduplicate-plugin-configuration.md +++ b/app/_src/deck/guides/deduplicate-plugin-configuration.md @@ -219,7 +219,7 @@ consumers: Now, you can edit plugin configuration in a single place and you can see its effect across multiple entities. Under the hood, decK takes the change and applies it to each entity which references the plugin configuration that has -been changed. As always, use `deck diff` to inspect the changes before you +been changed. As always, use `diff` to inspect the changes before you apply those to your Kong clusters. ## Overriding fields in plugin configs diff --git a/app/_src/deck/guides/defaults-v2.md b/app/_src/deck/guides/defaults-v2.md index 2d505b3d0bbb..d1ba3eacdf55 100644 --- a/app/_src/deck/guides/defaults-v2.md +++ b/app/_src/deck/guides/defaults-v2.md @@ -37,7 +37,7 @@ retrieve the latest object schemas for your instance of the {{site.base_gateway} Configuring your own defaults is a good way to keep updated on potential breaking changes between versions. If you upgrade {{site.base_gateway}} to a -version which introduces a new property with a default value, a `deck diff` +version which introduces a new property with a default value, a `diff` will catch the difference. If defaults are not set in the declarative configuration file, any newly @@ -55,9 +55,7 @@ want to use, skip to [setting defaults](#set-defaults). ### Create a file and test without defaults -1. Create a `kong.yaml` configuration file. - -2. Add the following sample service and route to the file: +1. Create a `kong.yaml` configuration file with the following sample contents: ```yaml _format_version: "3.0" @@ -74,9 +72,16 @@ want to use, skip to [setting defaults](#set-defaults). {% capture deck_diff1 %} {% navtabs codeblock %} {% navtab Command %} +{% if_version lte:1.27.x %} ```sh deck diff ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml +``` +{% endif_version %} {% endnavtab %} {% navtab Response %} ```sh @@ -97,18 +102,32 @@ Summary: 4. Sync your changes with {{site.base_gateway}}: + {% if_version lte:1.27.x %} ```sh deck sync ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway sync kong.yaml + ``` + {% endif_version %} 5. Now, run another diff and note the difference in the response: {% capture deck_diff2 %} {% navtabs codeblock %} {% navtab Command %} +{% if_version lte:1.27.x %} ```sh deck diff ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml +``` +{% endif_version %} {% endnavtab %} {% navtab Response %} ```sh @@ -226,9 +245,16 @@ Summary: {% capture deck_diff3 %} {% navtabs codeblock %} {% navtab Command %} +{% if_version lte:1.27.x %} ```sh deck diff ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml +``` +{% endif_version %} {% endnavtab %} {% navtab Response %} ```sh diff --git a/app/_src/deck/guides/defaults.md b/app/_src/deck/guides/defaults.md index 441cae935405..fb51a5e56840 100644 --- a/app/_src/deck/guides/defaults.md +++ b/app/_src/deck/guides/defaults.md @@ -11,11 +11,11 @@ check the latest object schemas for your instance of the {{site.base_gateway}}. decK recognizes value defaults and doesn't interpret them as changes to configuration. If you push a config for an object to {{site.base_gateway}} with -`deck sync`, {{site.base_gateway}} applies its default values to the object, +`sync`, {{site.base_gateway}} applies its default values to the object, but a further `diff` or `sync` does not show any changes. If you upgrade {{site.base_gateway}} to a version that introduces a new -property with a default value, a `deck diff` will catch the difference. +property with a default value, a `diff` will catch the difference. You can also configure your own [custom defaults](#set-custom-defaults) to enforce a set of standard values and avoid repetition in your configuration. @@ -38,9 +38,8 @@ Create a sample `kong.yaml` file with a service, route, and plugin, push it to {{site.base_gateway}}, and then pull {{site.base_gateway}}'s configuration down again to see how decK interprets default values. -1. Create a `kong.yaml` configuration file. - -1. Add the following sample service, route, and plugin to the file: +1. Create a `kong.yaml` configuration file with the following +sample service, route, and plugin: ```yaml _format_version: "3.0" @@ -61,9 +60,16 @@ again to see how decK interprets default values. {% capture deck_diff1 %} {% navtabs codeblock %} {% navtab Command %} +{% if_version lte:1.27.x %} ```sh deck diff ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml +``` +{% endif_version %} {% endnavtab %} {% navtab Response %} ```sh @@ -86,18 +92,32 @@ Summary: 1. Sync your changes with {{site.base_gateway}}: - ```sh - deck sync - ``` + {% if_version lte:1.27.x %} + ```sh + deck sync + ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway sync kong.yaml + ``` + {% endif_version %} 1. Now, run another diff and note the response: {% capture deck_diff2 %} {% navtabs codeblock %} {% navtab Command %} +{% if_version lte:1.27.x %} ```sh deck diff ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml +``` +{% endif_version %} {% endnavtab %} {% navtab Response %} ```sh @@ -119,11 +139,19 @@ Summary: {{site.base_gateway}}'s object configuration into a file. If you want to avoid overwriting your current state file, specify a different filename: + {% if_version lte:1.27.x %} ```sh deck dump -o kong-test.yaml ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway dump -o kong-test.yaml + ``` + {% endif_version %} - Even though `deck diff` didn't show any changes, the result now has + + Even though `diff` didn't show any changes, the result now has default values populated for the service, route, and Basic Auth plugin: ```yaml @@ -274,9 +302,16 @@ configuration would overwrite the value in your environment. 1. Sync your changes with {{site.base_gateway}}: - ```sh - deck sync - ``` + {% if_version lte:1.27.x %} + ```sh + deck sync + ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway sync kong.yaml + ``` + {% endif_version %} 1. Run a diff and note the response: diff --git a/app/_src/deck/guides/distributed-configuration.md b/app/_src/deck/guides/distributed-configuration.md index 8a389baa151c..af3aedb8b77e 100644 --- a/app/_src/deck/guides/distributed-configuration.md +++ b/app/_src/deck/guides/distributed-configuration.md @@ -43,12 +43,19 @@ fewer or only one tag, for performance reasons in Kong's codebase. You can export a subset of entities in Kong by specifying common tags using the `--select-tag` flag. -For example: +For example, the following command generates a `kong.yaml` file with all entities +which have both of the specified tags: +{% if_version lte:1.27.x %} ```shell -$ deck dump --select-tag foo-tag --select-tag bar-tag -# generates a kong.yaml file with all entities which have both the tags +deck dump --select-tag foo-tag --select-tag bar-tag ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```shell +deck gateway dump --select-tag foo-tag --select-tag bar-tag +``` +{% endif_version %} If you observe the file generated by decK, you will see the following section: diff --git a/app/_src/deck/guides/environment-variables.md b/app/_src/deck/guides/environment-variables.md index a4c5631fb114..aac751d63b1d 100644 --- a/app/_src/deck/guides/environment-variables.md +++ b/app/_src/deck/guides/environment-variables.md @@ -54,7 +54,18 @@ You can use this method for any sensitive content. ``` This snippet enables the [key authentication][key-auth] plugin globally and creates a consumer named `demo` with an API key. -3. Run `deck sync -s env-demo.yaml` to sync this file. +3. Run the following command to sync this file: + + {% if_version lte:1.27.x %} + ```sh + deck sync -s env-demo.yaml + ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway sync env-demo.yaml + ``` + {% endif_version %} The output should look something like this, where `abc` is the API key stored in the environment variable: diff --git a/app/_src/deck/guides/getting-started.md b/app/_src/deck/guides/getting-started.md index e6162e0d82a6..a2630413c9e3 100644 --- a/app/_src/deck/guides/getting-started.md +++ b/app/_src/deck/guides/getting-started.md @@ -103,22 +103,36 @@ If you already have {{site.base_gateway}} set up with the configuration of your 1. Check that decK recognizes your {{site.base_gateway}} installation: + {% if_version lte:1.27.x %} ```sh deck ping ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway ping + ``` + {% endif_version %} If the connection is successful, the terminal displays your gateway version: ```sh Successfully connected to Kong! - Kong version: 2.5.1 + Kong version: 3.7.1 ``` 2. Export {{site.base_gateway}}'s configuration: - ```shell + {% if_version lte:1.27.x %} + ```sh deck dump ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway dump -o kong.yaml + ``` + {% endif_version %} 3. Open the generated `kong.yaml` file. If you're using the sample configuration in this guide, the file should look like this: @@ -205,17 +219,32 @@ plugins: 1. Run the diff command: - ```shell + {% if_version lte:1.27.x %} + ```sh deck diff ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway diff kong.yaml + ``` + {% endif_version %} + You should see decK reporting that the properties you had changed in the file are going to be changed by decK in {{site.base_gateway}}'s database. 2. Apply the changes: + {% if_version lte:1.27.x %} ```sh deck sync ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway sync kong.yaml + ``` + {% endif_version %} 3. Curl Kong's Admin API to see the updated route and service in {{site.base_gateway}}: @@ -225,9 +254,16 @@ plugins: 4. Run the diff command again, which should report no changes: + {% if_version lte:1.27.x %} ```sh deck diff ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway diff kong.yaml + ``` + {% endif_version %} ## Drift detection using decK @@ -252,9 +288,16 @@ plugins: 2. Check what decK reports on a diff now: - ```shell + {% if_version lte:1.27.x %} + ```sh deck diff ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway diff kong.yaml + ``` + {% endif_version %} Response: ```sh @@ -266,9 +309,16 @@ plugins: 3. Run the sync process: - ```shell + {% if_version lte:1.27.x %} + ```sh deck sync ``` + {% endif_version %} + {% if_version gte:1.28.x %} + ```sh + deck gateway sync kong.yaml + ``` + {% endif_version %} 4. Now, looking up the consumer in {{site.base_gateway}}'s database returns a `404`: @@ -286,7 +336,7 @@ plugins: Access-Control-Allow-Origin: * Content-Length: 23 X-Kong-Admin-Latency: 2 - Server: kong/2.5.1 + Server: kong/3.7.1 {"message":"Not found"} ``` @@ -301,11 +351,18 @@ You can reset the configuration of {{site.kong_gateway}} using decK. {:.warning} > **Warning**: The changes performed by this command are irreversible (unless you've created -a backup using `deck dump`), so be careful. +a backup using `dump`), so be careful. +{% if_version lte:1.27.x %} ```sh deck reset ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway reset +``` +{% endif_version %} Response: ``` diff --git a/app/_src/deck/guides/kong-enterprise.md b/app/_src/deck/guides/kong-enterprise.md index feb6fd39ddda..a72314fe5921 100644 --- a/app/_src/deck/guides/kong-enterprise.md +++ b/app/_src/deck/guides/kong-enterprise.md @@ -1,5 +1,5 @@ --- -title: decK and Kong Gateway (Enterprise) +title: decK and Kong Gateway Enterprise content_type: explanation --- @@ -27,17 +27,32 @@ RBAC token to decK so that decK can authenticate itself against the Admin API. Use the `--headers` flag to pass the RBAC token to decK. For example, you can pass the token as a string: +{% if_version lte:1.27.x %} ```sh deck diff --headers "kong-admin-token:" ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml --headers "kong-admin-token:" +``` +{% endif_version %} + However, passing the token directly is not secure and should only be used for testing. The command and all of its flags are logged to your shell's history file, potentially leaking the token. For a more secure approach, you can store the token in a file and load the file as you execute the command. For example: +{% if_version lte:1.27.x %} ```sh deck diff --headers "kong-admin-token:$(cat token.txt)" ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway diff kong.yaml --headers "kong-admin-token:$(cat token.txt)" +``` +{% endif_version %} You can also use the `DECK_HEADERS` environment variable to supply the same token with an environment variable. @@ -134,9 +149,16 @@ inside the workspace, but not the workspace itself. You can manage the configurations of all workspaces in {{site.ee_product_name}} with the `--all-workspaces` flag: +{% if_version lte:1.27.x %} ```sh deck dump --all-workspaces ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway dump -o kong.yaml --all-workspaces +``` +{% endif_version %} This creates one configuration file per workspace. @@ -146,6 +168,8 @@ However, since a `workspace` is an isolated unit of configuration, decK doesn't allow the deployment of multiple workspaces at a time. Therefore, each workspace configuration file must be deployed individually: +{% if_version lte:1.27.x %} + ```sh deck sync -s workspace1.yaml --workspace workspace1 ``` @@ -153,6 +177,17 @@ deck sync -s workspace1.yaml --workspace workspace1 ```sh deck sync -s workspace2.yaml --workspace workspace2 ``` +{% endif_version %} +{% if_version gte:1.28.x %} + +```sh +deck gateway sync workspace1.yaml --workspace workspace1 +``` + +```sh +deck gateway sync workspace2.yaml --workspace workspace2 +``` +{% endif_version %} {% endif_version %} diff --git a/app/_src/deck/guides/konnect.md b/app/_src/deck/guides/konnect.md index 4f105aa9693d..ad429da9dc55 100644 --- a/app/_src/deck/guides/konnect.md +++ b/app/_src/deck/guides/konnect.md @@ -13,7 +13,7 @@ You _cannot_ use decK to publish content to the Dev Portal, manage application r ## {{site.konnect_short_name}} flags -You can use `deck` commands such as `ping`, `diff`, or `sync` with `--konnect` flags to interact with {{site.konnect_short_name}}. +You can use decK commands such as `ping`, `diff`, or `sync` with `--konnect` flags to interact with {{site.konnect_short_name}}. If you don't pass a {{site.konnect_short_name}} flag to decK, decK looks for a local {{site.base_gateway}} instance instead. @@ -78,12 +78,21 @@ Set either `konnect-token` or `konnect-token-file` in the decK config file. ``` decK automatically uses the token from `$HOME/.deck.yaml` in any subsequent calls: - +{% if_version lte:1.27.x %} ```sh deck ping Successfully Konnected to the Example-Name organization! ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway ping + +Successfully Konnected to the Example-Name organization! +``` +{% endif_version %} + ### Authenticate using a token You can generate a token in {{site.konnect_short_name}} for authentication with decK commands. @@ -120,18 +129,34 @@ To generate a PAT for a user account in {{site.konnect_short_name}}, select your You can use the `--konnect-token` flag to pass the PAT directly in the command: +{% if_version lte:1.27.x %} ```sh deck ping \ --konnect-token YOUR_KONNECT_TOKEN ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway ping \ + --konnect-token YOUR_KONNECT_TOKEN +``` +{% endif_version %} You can save your {{site.konnect_short_name}} token to a file, then pass the filename to decK with `--konnect-token-file`: +{% if_version lte:1.27.x %} ```sh deck ping \ --konnect-token-file /PATH/TO/FILE ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway ping \ + --konnect-token-file /PATH/TO/FILE +``` +{% endif_version %} ## Target a {{site.konnect_short_name}} API @@ -174,7 +199,7 @@ or use a flag when running any decK command. ``` {% endif_version %} -{% if_version gte:1.27.x %} +{% if_version eq:1.27.x %} * Target a control plane in your state file with the `_konnect.control_plane_name` parameter: ```yaml @@ -190,6 +215,22 @@ or use a flag when running any decK command. ``` {% endif_version %} +{% if_version gte:1.28.x %} +* Target a control plane in your state file with the `_konnect.control_plane_name` parameter: + + ```yaml + _format_version: "3.0" + _konnect: + control_plane_name: staging + ``` + +* Set a control plane using the `--konnect-control-plane-name` flag: + + ```sh + deck gateway sync konnect.yaml --konnect-control-plane-name staging + ``` +{% endif_version %} + ## Troubleshoot ### Authentication with a {{site.konnect_short_name}} token file is not working @@ -243,7 +284,7 @@ _konnect: ### ACL, Key Auth, or OpenID Connect plugins and app registration You may encounter one of the following scenarios with the ACL, Key Authentication, or OpenID Connect (OIDC) plugins: -* The plugins are visible in the Gateway Manager, but don't appear in the output from a `deck dump` or `deck diff`. +* The plugins are visible in the Gateway Manager, but don't appear in the output from a decK `dump` or `diff`. * When trying to set up one of the plugins with app registration enabled, you see the following error: ``` diff --git a/app/_src/deck/guides/multi-file-state.md b/app/_src/deck/guides/multi-file-state.md index 93f56fddf184..4f82f93f6c02 100644 --- a/app/_src/deck/guides/multi-file-state.md +++ b/app/_src/deck/guides/multi-file-state.md @@ -38,14 +38,23 @@ as [distributed configuration](/deck/{{page.release}}/guides/distributed-configu You must be careful when mixing distributed configuration in multiple files and the `--select-tag` flag, as this may result in undesired outcomes. For example, imagine you have a couple of services deployed with some tags -and that you dump their configuration as follows: +and that you dump their configuration. +First dump configuration tagged with `team-svc1`: + +{% if_version lte:1.27.x %} ```sh deck dump --select-tag team-svc1 -o svc1.yaml ``` - +{% endif_version %} +{% if_version gte:1.28.x %} ```sh -$ cat svc1.yaml +deck gateway dump --select-tag team-svc1 -o svc1.yaml +``` +{% endif_version %} + +Example `svc1.yaml` file: +```yaml _format_version: "3.0" _info: defaults: {} @@ -64,12 +73,20 @@ services: write_timeout: 60000 ``` +Then dump configuration tagged with `team-svc2`: +{% if_version lte:1.27.x %} ```sh deck dump --select-tag team-svc2 -o svc2.yaml ``` - +{% endif_version %} +{% if_version gte:1.28.x %} ```sh -$ cat svc2.yaml +deck gateway dump --select-tag team-svc2 -o svc2.yaml +``` +{% endif_version %} + +Example `svc2.yaml` file: +```yaml _format_version: "3.0" _info: defaults: {} @@ -94,16 +111,31 @@ For syncing back (or diffing) the configurations, you must sync each of these fi otherwise decK merges the content of `select_tags` together and applies both tags to both services. +{% if_version lte:1.27.x %} ```sh deck sync -s svc1.yaml -Summary: - Created: 0 - Updated: 0 - Deleted: 0 ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway sync svc1.yaml +``` +{% endif_version %} +{% if_version lte:1.27.x %} ```sh deck sync -s svc2.yaml +``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway sync svc2.yaml +``` +{% endif_version %} + + +In both cases, the response should look like this: +``` Summary: Created: 0 Updated: 0 diff --git a/app/_src/deck/guides/run-with-docker-1.28.md b/app/_src/deck/guides/run-with-docker-1.28.md new file mode 100644 index 000000000000..3518e898f6eb --- /dev/null +++ b/app/_src/deck/guides/run-with-docker-1.28.md @@ -0,0 +1,63 @@ +--- +title: Run decK with Docker +content_type: how-to +--- + +If you used the `kong/deck` Docker image to install decK, you can use the Docker image to manage decK. + +## Prerequisites +decK must be installed using a [Docker image](/deck/latest/installation/#docker-image). + +## Export the configuration +Run this command to export the `kong.yaml` file: + +```bash +docker run -i \ +-v $(pwd):/deck \ +kong/deck --kong-addr http://KONG_ADMIN_HOST:KONG_ADMIN_PORT --headers kong-admin-token:KONG_ADMIN_TOKEN -o /deck/kong.yaml gateway dump +``` +Where `$(pwd)/kong.yaml` is the path to a `kong.yaml` file. + +## Export objects from all workspaces +Run this command to export objects from all the workspaces: + +```bash +docker run -i \ +-v $(pwd):/deck \ +--workdir /deck \ +kong/deck --kong-addr http://KONG_ADMIN_HOST:KONG_ADMIN_PORT:8001 --headers kong-admin-token:KONG_ADMIN_TOKEN -o /deck/kong.yaml gateway dump --all-workspaces +``` + +## Reset the configuration +Run this command to initialize Kong objects: + +```bash +docker run -i \ +-v $(pwd):/deck \ +kong/deck --kong-addr http://KONG_ADMIN_HOST:KONG_ADMIN_PORT:8001 --headers kong-admin-token:KONG_ADMIN_TOKEN gateway reset +``` + +## Import the configuration +Run this command to import `kong.yaml`: + +```bash +docker run -i \ +-v $(pwd):/deck \ +kong/deck --kong-addr http://KONG_ADMIN_HOST:KONG_ADMIN_PORT:8001 --headers kong-admin-token:KONG_ADMIN_TOKEN /deck/kong.yaml gateway sync +``` +In this example, `kong.yaml` is in `$(pwd)/kong.yaml`. + +## View help manual pages +Run this command to view all available commands: + +```bash +docker run kong/deck --help +``` + +Run the following to check available command flags: + +```bash +docker run kong/deck gateway dump --help +docker run kong/deck gateway sync --help +docker run kong/deck gateway reset --help +``` \ No newline at end of file diff --git a/app/_src/deck/guides/vaults.md b/app/_src/deck/guides/vaults.md index 467167ffb274..7760b6d09d18 100644 --- a/app/_src/deck/guides/vaults.md +++ b/app/_src/deck/guides/vaults.md @@ -119,13 +119,20 @@ vaults: - env-vault ``` -When updating the vault, `deck dump` the configuration with the `--select-tag` flag: +When updating the vault, `dump` the configuration with the `--select-tag` flag: +{% if_version lte:1.27.x %} ```sh deck dump --select-tag env-vault ``` +{% endif_version %} +{% if_version gte:1.28.x %} +```sh +deck gateway dump -o kong.yaml --select-tag env-vault +``` +{% endif_version %} -Make your changes to the vault, then push it back up with `deck sync`. +Make your changes to the vault, then push it back up with `sync`. You don't need to specify `--select-tag` in this case, as decK recognizes the tag in the declarative configuration file that you're syncing and updates those entities accordingly. diff --git a/app/_src/deck/reference/deck_gateway_diff.md b/app/_src/deck/reference/deck_gateway_diff.md index c3146475dbdf..4f0adcc7e9a9 100644 --- a/app/_src/deck/reference/deck_gateway_diff.md +++ b/app/_src/deck/reference/deck_gateway_diff.md @@ -19,7 +19,7 @@ that will be created, updated, or deleted. ## Syntax ``` -deck gateway diff [command-specific flags] [global flags] +deck gateway diff [filename] [command-specific flags] [global flags] ``` ## Flags diff --git a/app/_src/deck/reference/deck_gateway_sync.md b/app/_src/deck/reference/deck_gateway_sync.md index e551d5ccd39b..d7be8c8945b7 100644 --- a/app/_src/deck/reference/deck_gateway_sync.md +++ b/app/_src/deck/reference/deck_gateway_sync.md @@ -16,7 +16,7 @@ to get Kong's state in sync with the input state. ## Syntax ``` -deck gateway sync [command-specific flags] [global flags] +deck gateway sync [filename] [command-specific flags] [global flags] ``` ## Flags diff --git a/app/_src/deck/reference/deck_gateway_validate.md b/app/_src/deck/reference/deck_gateway_validate.md index 2e41cf9cf3b3..2056cb8a7b12 100644 --- a/app/_src/deck/reference/deck_gateway_validate.md +++ b/app/_src/deck/reference/deck_gateway_validate.md @@ -23,7 +23,7 @@ For offline validation, see `deck file validate`. ## Syntax ``` -deck gateway validate [command-specific flags] [global flags] +deck gateway validate [filename] [command-specific flags] [global flags] ``` ## Flags diff --git a/app/_src/gateway/breaking-changes/30x.md b/app/_src/gateway/breaking-changes/30x.md index 5effa75755c3..637c45a6a862 100644 --- a/app/_src/gateway/breaking-changes/30x.md +++ b/app/_src/gateway/breaking-changes/30x.md @@ -228,9 +228,9 @@ The version number (`_format_version`) of declarative configuration has been bum Declarative configurations with older versions will be upgraded to `3.0` during migrations. {:.important} -> **Do not sync (`deck sync`) declarative configuration files from 2.8 or earlier to 3.0.** +> **Do not sync (`deck gateway sync`) declarative configuration files from 2.8 or earlier to 3.0.** Old configuration files will overwrite the configuration and create compatibility issues. -To grab the updated configuration, `deck dump` the 3.0 file after migrations are completed. +To grab the updated configuration, `deck gateway dump` the 3.0 file after migrations are completed. It is no longer possible to use the `.lua` format to import a declarative configuration file from the `kong` CLI tool. Only JSON and YAML formats are supported. If your update procedure with {{site.base_gateway}} involves diff --git a/app/_src/gateway/kong-enterprise/plugin-ordering/get-started.md b/app/_src/gateway/kong-enterprise/plugin-ordering/get-started.md index a0c03f448faf..4ffc36a624a3 100644 --- a/app/_src/gateway/kong-enterprise/plugin-ordering/get-started.md +++ b/app/_src/gateway/kong-enterprise/plugin-ordering/get-started.md @@ -111,7 +111,7 @@ ordering: 2. Sync the configuration: ``` bash - deck sync + deck gateway sync kong.yaml ``` {% endnavtab %} @@ -227,8 +227,8 @@ ordering: 2. Sync the configuration: - ``` bash - deck sync + ```bash + deck gateway sync kong.yaml ``` {% endnavtab %} diff --git a/app/_src/gateway/migrate-cassandra-to-postgres.md b/app/_src/gateway/migrate-cassandra-to-postgres.md index 8d340149cdbf..51a5513bb297 100644 --- a/app/_src/gateway/migrate-cassandra-to-postgres.md +++ b/app/_src/gateway/migrate-cassandra-to-postgres.md @@ -97,8 +97,8 @@ The goal of this phase is to reproduce the {{site.base_gateway}} configuration i | Step | Name | Description | |------|-----------------------|-----------------------------------------------------------------------------------------------------------------------| -| 1 | Configuration dump | - Execute the `deck dump` command against the blue environment for each workspace to build a YAML representation of the Kong estate
- Execute `deck dump --rbac-resources-only` against the blue environment for each workspace to build a YAML representation of any RBAC resources created
- If using the Kong Dev Portal, run the `portal fetch` command via the Portal CLI to build a representation of the Dev Portal assets for a workspace | -| 2 | Configuration sync | - Change decK to work with the green environment, and execute `deck sync` to push the configuration to the green environment
- Change the Portal CLI to work against the green environment, and execute `portal deploy` to push the Dev Portal configuration against the new environment | +| 1 | Configuration dump | - Execute the `deck gateway dump` command against the blue environment for each workspace to build a YAML representation of the Kong estate
- Execute `deck gateway dump --rbac-resources-only` against the blue environment for each workspace to build a YAML representation of any RBAC resources created
- If using the Kong Dev Portal, run the `portal fetch` command via the Portal CLI to build a representation of the Dev Portal assets for a workspace | +| 2 | Configuration sync | - Change decK to work with the green environment, and execute `deck gateway sync` to push the configuration to the green environment
- Change the Portal CLI to work against the green environment, and execute `portal deploy` to push the Dev Portal configuration against the new environment | | 3 | Regression testing | Execute regression tests against the green environment backed by PostgreSQL | | 4 | Go/No Go checkpoint | If all tests pass, proceed with traffic cut over | diff --git a/app/_src/gateway/upgrade-v3.md b/app/_src/gateway/upgrade-v3.md index 3523c6c35422..63ce7af7f567 100644 --- a/app/_src/gateway/upgrade-v3.md +++ b/app/_src/gateway/upgrade-v3.md @@ -260,9 +260,9 @@ The version number (`_format_version`) of declarative configuration has been bum Declarative configurations with older versions will be upgraded to `3.0` during migrations. {:.important} -> **Do not sync (`deck sync`) declarative configuration files from 2.8 or earlier to 3.0.** +> **Do not sync (`deck gateway sync`) declarative configuration files from 2.8 or earlier to 3.0.** Old configuration files will overwrite the configuration and create compatibility issues. -To grab the updated configuration, `deck dump` the 3.0 file after migrations are completed. +To grab the updated configuration, `deck gateway dump` the 3.0 file after migrations are completed. It is no longer possible to use the `.lua` format to import a declarative configuration file from the `kong` CLI tool. Only JSON and YAML formats are supported. If your update procedure with {{site.base_gateway}} involves diff --git a/app/_src/gateway/upgrade/backup-and-restore.md b/app/_src/gateway/upgrade/backup-and-restore.md index 4991453c2233..7fcbe677e725 100644 --- a/app/_src/gateway/upgrade/backup-and-restore.md +++ b/app/_src/gateway/upgrade/backup-and-restore.md @@ -36,8 +36,8 @@ However, decK also has its limitations: * **Performance**: decK uses the Admin API to read and write entities and might take longer than expected, especially when the number of entities is very large. - You can resolve this by increasing the number of threads by passing the flag `--parallelism` to [`deck sync`](/deck/latest/reference/deck_sync/) - or [`deck diff`](/deck/latest/reference/deck_diff/), or use decK’s + You can resolve this by increasing the number of threads by passing the flag `--parallelism` to [`deck gateway sync`](/deck/latest/reference/deck_gateway_sync/) + or [`deck gateway diff`](/deck/latest/reference/deck_gateway_diff/), or use decK’s [distributed configuration](/deck/latest/guides/distributed-configuration/) feature. * **Entities managed by decK**: decK does not manage Enterprise-only entities, like RBAC roles, credentials, keyring, licence, etc. Configure these security related entities separately using Admin API or Kong Manager. @@ -74,25 +74,25 @@ For a database-backed deployment, we recommend using decK as a secondary backup 1. To back up data with decK, first make sure it successfully connects to {{site.base_gateway}}: ```sh - deck ping + deck gateway ping ``` If you have RBAC enabled, use the CLI option `--headers` to specify the admin token. You can specify this token with any decK command: ```sh - deck ping --headers “Kong-Admin-Token: ” + deck gateway ping --headers “Kong-Admin-Token: ” ``` 2. Use decK to dump the configuration and store the resulting file in a secure location. You can back up a particular workspace or all workspaces at once: ```sh - deck dump --all-workspaces -o /path/to/kong_backup.yaml + deck gateway dump --all-workspaces -o /path/to/kong_backup.yaml ``` or ```sh - deck dump --workspace it_dept -o /path/to/kong_backup.yaml + deck gateway dump --workspace it_dept -o /path/to/kong_backup.yaml ``` Store the resulting file or files in a safe location. @@ -101,7 +101,7 @@ You can back up a particular workspace or all workspaces at once: {% endnavtab %} {% navtab Traditional or hybrid mode - kong config CLI %} -As a final failsafe for a database-backed deployment, you can also back up the database using the kong config CLI. +As a final fail-safe for a database-backed deployment, you can also back up the database using the `kong config` CLI. {:.important} > Never use this method as your primary backup, as it might not accurately represent the final state of your database. @@ -168,23 +168,23 @@ In traditional or hybrid mode, use decK to restore your configuration from a bac 1. Check that {{site.base_gateway}} is online: ```sh - deck ping + deck gateway ping ``` 2. Validate the declarative config: ```sh - deck validate [--online] -s /path/to/kong_backup.yaml + deck gateway validate /path/to/kong_backup.yaml [--online] ``` 3. Once verified, restore a particular workspace or all workspaces at once: ```sh - deck sync --all-workspaces -s /path/to/kong_backup.yaml + deck gateway sync /path/to/kong_backup.yaml --all-workspaces ``` or ```sh - deck sync --workspace it_dept -s /path/to/kong_backup.yaml + deck gateway sync /path/to/kong_backup.yaml --workspace it_dept ``` {% endnavtab %} diff --git a/app/konnect/dev-portal/troubleshoot/index.md b/app/konnect/dev-portal/troubleshoot/index.md index 2fec42d6d325..08234e7fd123 100644 --- a/app/konnect/dev-portal/troubleshoot/index.md +++ b/app/konnect/dev-portal/troubleshoot/index.md @@ -41,7 +41,7 @@ To help differentiate the application registration plugins, `konnect-managed-plugin` and `konnect-app-registration`. For example, if you enable application registration from the -{{site.konnect_short_name}} web application and run `deck dump`, you should see +{{site.konnect_short_name}} web application and run `deck gateway dump`, you should see an entry like this for the ACL plugin: ```yaml diff --git a/app/konnect/gateway-manager/backup-restore.md b/app/konnect/gateway-manager/backup-restore.md index 986d905545c8..d7ca4509f0d4 100644 --- a/app/konnect/gateway-manager/backup-restore.md +++ b/app/konnect/gateway-manager/backup-restore.md @@ -6,7 +6,7 @@ content_type: how-to Use [decK](/deck/latest/installation/) to back up and restore {{site.konnect_short_name}}'s control plane configuration. -With `deck dump`, decK generates state files for each control plane, which act +With `deck gateway dump`, decK generates state files for each control plane, which act as snapshots of the control plane's configuration at that point in time. If a control plane's configuration is ever corrupted, you can then use these snapshots to restore your control plane, or bring up another control plane with the same configuration. @@ -21,10 +21,10 @@ There is currently no automated way to back up Dev Portal content. ## Back up a {{site.konnect_short_name}} control plane -Use `deck dump` to back up your configuration: +Use `deck gateway dump` to back up your configuration: ```sh -deck dump \ +deck gateway dump \ --konnect-token \ --konnect-control-plane-name \ --output-file /path/to/ @@ -63,20 +63,18 @@ Run a diff between your backup file and the control plane in {{site.konnect_shor make sure you're applying the configuration you want: ```sh -deck diff \ +deck gateway diff /path/to/ \ --konnect-token \ --konnect-control-plane-name \ ---output-file /path/to/ ``` -If you're satisfied with the diff result, run `deck sync` to sync your configuration to +If you're satisfied with the diff result, run `deck gateway sync` to sync your configuration to a control plane: ```sh -deck sync \ +deck gateway sync /path/to/ \ --konnect-token \ --konnect-control-plane-name \ ---output-file /path/to/ ``` Check your control plane in {{site.konnect_short_name}} to make sure the sync worked. diff --git a/app/konnect/gateway-manager/control-plane-groups/conflicts.md b/app/konnect/gateway-manager/control-plane-groups/conflicts.md index c1755f9b250c..b93ce3b75612 100644 --- a/app/konnect/gateway-manager/control-plane-groups/conflicts.md +++ b/app/konnect/gateway-manager/control-plane-groups/conflicts.md @@ -38,7 +38,7 @@ Duplicate names across control plane group members | Entity names within a stand Shared credentials across control plane group members | Consumer credentials in one control plane group member can be used to authenticate to everything registered in the group.| If you don't want to share credentials across the members, identify and remove those credentials. ACL group names across control plane group members | ACL groups names can be referenced across control plane group members for authorization. | If you don't want to share ACL groups across the members, identify and remove duplicates. Consumer groups across control plane group members | Consumer group names in the Rate Limiting Advanced plugin can reference group names from other control plane group members.| If you don't want to share consumer groups across the members, identify and remove duplicates. -decK dump with duplicate names found | `deck dump` will break with duplicate names across control plane group entities. | Resolve the conflict by removing or renaming one of the instances. +decK dump with duplicate names found | `deck gateway dump` will break with duplicate names across control plane group entities. | Resolve the conflict by removing or renaming one of the instances. Reference by name vs reference by ID | If the entity relationship requires [reference by ID](/konnect/gateway-manager/control-plane-groups/#configuring-core-entities), then relationships across control planes don't work. If the entity relationship is defined by a special string, relationships across control planes do work as long as you know the string. | Resolve the conflict by removing one of the instances. Multiple instances of the same global plugin | A global plugin can only be applied once in an standard control plane. However, multiple instances of the same global plugin can be combined into the control plane group. | Resolve the conflict by removing one of the instances, or setting different instance names for the plugins. diff --git a/app/konnect/gateway-manager/control-plane-groups/migrate.md b/app/konnect/gateway-manager/control-plane-groups/migrate.md index e30770a99ef7..925a041b63e3 100644 --- a/app/konnect/gateway-manager/control-plane-groups/migrate.md +++ b/app/konnect/gateway-manager/control-plane-groups/migrate.md @@ -68,10 +68,10 @@ grant access to the wrong resources to a new group of users. Assuming you already have a control plane group and a member control plane, you can export the configuration from the old control plane and apply it to the new one. -1. Export the configuration of the old control plane via `deck dump`: +1. Export the configuration of the old control plane via `deck gateway dump`: ```sh - deck dump \ + deck gateway dump \ -o old-group.yaml \ --konnect-token \ --konnect-control-plane-name old-group @@ -80,8 +80,7 @@ Assuming you already have a control plane group and a member control plane, you 1. Sync the configuration to the new group: ```sh - deck sync \ - -s old-group.yaml \ + deck gateway sync old-group.yaml \ --konnect-token \ --konnect-control-plane-name CP1 ``` @@ -95,10 +94,10 @@ Assuming you already have a control plane group and a member control plane, you Use decK to migrate a self-managed {{site.base_gateway}} workspace into a control plane group. -1. Run [`deck dump`](/deck/latest/reference/deck_dump/) to export workspace configuration into a file: +1. Run [`deck gateway dump`](/deck/latest/reference/deck_gateway_dump/) to export workspace configuration into a file: ```sh - deck dump --workspace ws1 -o ws1.yaml + deck gateway dump --workspace ws1 -o ws1.yaml ``` 1. Open the file. Remove the following: @@ -112,17 +111,17 @@ Use decK to migrate a self-managed {{site.base_gateway}} workspace into a contro * Any other [unsupported plugins](/konnect/compatibility/#plugin-compatibility) -1. Preview the import with the [`deck diff`](/deck/latest/reference/deck_diff/) +1. Preview the import with the [`deck gateway diff`](/deck/latest/reference/deck_gateway_diff/) command, pointing to the control plane that you want to target: ```sh - deck diff --konnect-control-plane-name CP1 -s ws1.yaml + deck gateway diff ws1.yaml --konnect-control-plane-name CP1 ``` -1. If you're satisfied with the preview, run [`deck sync`](/deck/latest/reference/deck_sync/): +1. If you're satisfied with the preview, run [`deck gateway sync`](/deck/latest/reference/deck_gateway_sync/): ```sh - deck sync --konnect-control-plane-name CP1 -s ws1.yaml + deck gateway sync ws1.yaml --konnect-control-plane-name CP1 ``` If you don't specify the `--konnect-control-plane-name` flag, decK targets the diff --git a/app/konnect/gateway-manager/declarative-config.md b/app/konnect/gateway-manager/declarative-config.md index 25041d14de10..5623691f0d40 100644 --- a/app/konnect/gateway-manager/declarative-config.md +++ b/app/konnect/gateway-manager/declarative-config.md @@ -44,7 +44,7 @@ Check that you can log in to {{site.konnect_short_name}} and that decK recognizes your account credentials: ```sh -deck ping \ +deck gateway ping \ --konnect-control-plane-name default \ --konnect-token {YOUR_PERSONAL_ACCESS_TOKEN} ``` @@ -77,7 +77,7 @@ The following steps all use a `.deck.yaml` file to store the Capture a snapshot of the current configuration in a file: ```sh -deck dump --konnect-control-plane-name default +deck gateway dump --konnect-control-plane-name default -o konnect.yaml ``` If you don't specify the `--konnect-control-plane-name` flag, decK will target the @@ -85,7 +85,7 @@ If you don't specify the `--konnect-control-plane-name` flag, decK will target t organization, we recommend always setting this flag to avoid accidentally pushing configuration to the wrong group. -The command creates a file named `kong.yaml`. If you have nothing +The command creates a file named `konnect.yaml`. If you have nothing configured, decK creates the file with only the format version and control plane name: @@ -99,7 +99,7 @@ You can specify a different filename or location, or export the configuration in JSON format: ```sh -deck dump --konnect-control-plane-name default \ +deck gateway dump --konnect-control-plane-name default \ --format json \ --output-file examples/konnect.json ``` @@ -109,7 +109,7 @@ deck dump --konnect-control-plane-name default \ Make any changes you like using YAML or JSON format. For this example, let's add a new service. -1. Add the following snippet to your `kong.yaml` file: +1. Add the following snippet to your `konnect.yaml` file: ```yaml _format_version: "1.1" @@ -146,7 +146,7 @@ For this example, let's add a new service. {{site.konnect_saas}}: ```sh - deck diff --konnect-control-plane-name default + deck gateway diff konnect.yaml --konnect-control-plane-name default ``` If the format and schema is correct, decK gives you a preview of what would @@ -166,7 +166,7 @@ For this example, let's add a new service. {{site.konnect_saas}}: ```sh - deck sync --konnect-control-plane-name default + deck gateway sync konnect.yaml --konnect-control-plane-name default ``` You should see the same output again: @@ -227,14 +227,14 @@ down with repeated requests. Add a global proxy cache plugin: 1. Run a diff to test your changes: ```sh - deck diff --konnect-control-plane-name default + deck gateway diff konnect.yaml --konnect-control-plane-name default ``` 1. If everything looks good, run another sync, then check {{site.konnect_saas}} to see your changes: ```sh - deck sync --konnect-control-plane-name default + deck gateway sync konnect.yaml --konnect-control-plane-name default ``` ## Test the service @@ -269,10 +269,10 @@ No API key found in request. You can also use decK to migrate or duplicate configuration between control planes. 1. Export configuration from the original control plane with -[`deck dump`](/deck/latest/reference/deck_dump) into a state file: +[`deck gateway dump`](/deck/latest/reference/deck_gateway_dump) into a state file: ```bash - deck dump \ + deck gateway dump \ --konnect-control-plane-name default \ --output-file default.yaml ``` @@ -286,22 +286,20 @@ You can also use decK to migrate or duplicate configuration between control plan ``` 1. Using the state file you just edited, preview the import with -the [`deck diff`](/deck/latest/reference/deck_diff/) +the [`deck gateway diff`](/deck/latest/reference/deck_gateway_diff/) command, pointing to the control plane that you want to target: ```sh - deck diff \ - --konnect-control-plane-name staging \ - --state default.yaml + deck gateway diff default.yaml \ + --konnect-control-plane-name staging ``` -1. If everything looks good, [`deck sync`](/deck/latest/reference/deck_sync/) +1. If everything looks good, [`deck gateway sync`](/deck/latest/reference/deck_gateway_sync/) the configuration to the new control plane: ```sh - deck sync \ - --konnect-control-plane-name staging \ - --state default.yaml + deck gateway sync default.yaml \ + --konnect-control-plane-name staging ``` You should now have two control planes in {{site.konnect_short_name}} with