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

@@ -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

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

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

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

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

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

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

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

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

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 %}

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.

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 :)

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
 ```
 

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 

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:
 

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.

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.

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

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