Release: decK 1.28 (#6420)

* bump deck version to 1.28 * reference updates for deck 1.28.x * fix typo * formatting&phrasing edits from reviews Co-authored-by: Angel <[email protected]> Co-authored-by: Rick Spurgeon <[email protected]> * bump version to 1.28.1 * move related links into an include --------- Co-authored-by: Angel <[email protected]> Co-authored-by: Rick Spurgeon <[email protected]>
Kong · Nov 3, 2023 · cbdc0ad · cbdc0ad
1 parent a02b864
commit cbdc0ad
Show file tree

Hide file tree

Showing 36 changed files with 908 additions and 85 deletions.
diff --git a/app/_data/docs_nav_deck_1.28.x.yml b/app/_data/docs_nav_deck_1.28.x.yml
@@ -0,0 +1,135 @@
+product: deck
+release: 1.28.x
+generate: true
+items:
+  - title: Introduction
+    icon: /assets/images/icons/documentation/icn-flag.svg
+    url: /deck/1.28.x/
+    absolute_url: true
+    items:
+      - text: Terminology
+        url: /terminology/
+      - text: Architecture
+        url: /design-architecture/
+      - text: Compatibility Promise
+        url: /compatibility-promise/
+
+  - title: Changelog
+    icon: /assets/images/icons/documentation/icn-references-color.svg
+    url: https://github.com/kong/deck/blob/main/CHANGELOG.md
+    absolute_url: true
+
+  - title: Installation
+    icon: /assets/images/icons/documentation/icn-deployment-color.svg
+    url: /installation
+
+  - title: Guides
+    icon: /assets/images/icons/documentation/icn-solution-guide.svg
+    items:
+      - text: Getting Started with decK
+        url: /guides/getting-started/
+      - text: Backup and Restore
+        url: /guides/backup-restore/
+      - text: Upgrade to Kong Gateway 3.x
+        url: /3.0-upgrade/
+      - text: Configuration as Code and GitOps
+        url: /guides/ci-driven-configuration/
+      - text: APIOps with decK
+        url: /guides/apiops/
+      - text: Distributed Configuration
+        url: /guides/distributed-configuration/
+      - text: Best Practices
+        url: /guides/best-practices/
+      - text: Using decK with Kong Gateway (Enterprise)
+        url: /guides/kong-enterprise/
+      - text: Using decK with Konnect
+        url: /guides/konnect/
+      - text: Run decK with Docker
+        url: /guides/run-with-docker/
+      - text: Using Multiple Files to Store Configuration
+        url: /guides/multi-file-state/
+      - text: De-duplicate Plugin Configuration
+        url: /guides/deduplicate-plugin-configuration/
+      - text: Set Up Object Defaults
+        url: /guides/defaults/
+      - text: Security
+        items:
+          - text: Overview
+            url: /guides/security/
+          - text: Secret Management with decK
+            url: /guides/vaults/
+          - text: Using Environment Variables with decK
+            url: /guides/environment-variables/
+
+  - title: Reference
+    icon: /assets/images/icons/documentation/icn-references-color.svg
+    items:
+      - text: Entities Managed by decK
+        url: /reference/entities/
+      - text: decK CLI
+        url: /reference/deck/
+      - text: deck completion
+        url: /reference/deck_completion/
+      - text: deck file
+        url: /reference/deck_file/
+        items:
+          - text: deck file add-plugins
+            url: /reference/deck_file_add-plugins/
+          - text: deck file add-tags
+            url: /reference/deck_file_add-tags/
+          - text: deck file convert
+            url: /reference/deck_file_convert/
+          - text: deck file lint
+            url: /reference/deck_file_lint/
+          - text: deck file list-tags
+            url: /reference/deck_file_list-tags/
+          - text: deck file merge
+            url: /reference/deck_file_merge/
+          - text: deck file openapi2kong
+            url: /reference/deck_file_openapi2kong/
+          - text: deck file patch
+            url: /reference/deck_file_patch/
+          - text: deck file remove-tags
+            url: /reference/deck_file_remove-tags/
+          - text: deck file render
+            url: /reference/deck_file_render/
+          - text: deck file validate
+            url: /reference/deck_file_validate/
+      - text: deck gateway
+        url: /reference/deck_gateway/
+        items:
+          - text: deck gateway diff
+            url: /reference/deck_gateway_diff/
+          - text: deck gateway dump
+            url: /reference/deck_gateway_dump/
+          - text: deck gateway ping
+            url: /reference/deck_gateway_ping/
+          - text: deck gateway reset
+            url: /reference/deck_gateway_reset/
+          - text: deck gateway sync
+            url: /reference/deck_gateway_sync/
+          - text: deck gateway validate
+            url: /reference/deck_gateway_validate/
+      - text: deck version
+        url: /reference/deck_version/
+      - text: Deprecated commands
+        items: 
+          - text: deck convert
+            url: /reference/deck_convert/
+          - text: deck diff
+            url: /reference/deck_diff/
+          - text: deck dump
+            url: /reference/deck_dump/
+          - text: deck ping
+            url: /reference/deck_ping/
+          - text: deck reset
+            url: /reference/deck_reset/
+          - text: deck sync
+            url: /reference/deck_sync/
+          - text: deck validate
+            url: /reference/deck_validate/
+
+
+  - title: FAQ
+    icon: /assets/images/icons/documentation/icn-faq-color.svg
+    url: /faqs/
diff --git a/app/_data/kong_versions.yml b/app/_data/kong_versions.yml
@@ -179,6 +179,9 @@
 - release: "1.27.x"
   version: "1.27.1"
   edition: "deck"
+- release: "1.28.x"
+  version: "1.28.1"
+  edition: "deck"
 - edition: "konnect"
 - edition: "contributing"
 - release: "1.0.x"

diff --git a/app/_includes/md/deck-reference-links.md b/app/_includes/md/deck-reference-links.md
@@ -0,0 +1,45 @@
+{% if include.general_links == "true" %}
+General:
+* [deck completion](/deck/{{page.kong_version}}/reference/deck_completion/)	 - Generate completion script
+* [deck version](/deck/{{page.kong_version}}/reference/deck_version/) - Print the decK version
+{% endif %}
+
+{% if include.gateway_links == "true" %}
+Gateway subcommands:
+* [deck gateway diff](/deck/{{page.kong_version}}/reference/deck_gateway_diff/)	- Performs a diff to determine the differences between the current entities in Kong and the ones on disk.
+* [deck gateway dump](/deck/{{page.kong_version}}/reference/deck_gateway_dump/)	- Export Kong configuration to a file
+* [deck gateway ping](/deck/{{page.kong_version}}/reference/deck_gateway_ping/)	- Verify connectivity with Kong
+* [deck gateway reset](/deck/{{page.kong_version}}/reference/deck_gateway_reset/) - Deletes all entities in Kong
+* [deck gateway sync](/deck/{{page.kong_version}}/reference/deck_gateway_sync/)	- Sync performs operations to get Kong's configuration to match the state file
+* [deck gateway validate](/deck/{{page.kong_version}}/reference/deck_gateway_validate/)	- Validate the state file
+{% endif %}
+
+{% if include.file_links == "true" %}
+File subcommands:
+* [deck file add-plugins](/deck/{{page.kong_version}}/reference/deck_file_add-plugins)	 - Add plugins to objects in a decK file
+* [deck file add-tags](/deck/{{page.kong_version}}/reference/deck_file_add-tags)	 - Add tags to objects in a decK file
+{%- if_version gte:1.28.x -%}
+* [deck file convert](/deck/{{page.kong_version}}/reference/deck_file_convert)	 - Convert files from one format into another format
+* [deck file lint](/deck/{{page.kong_version}}/reference/deck_file_lint)	 - Validate a file against a ruleset
+{% endif_version %}
+* [deck file list-tags](/deck/{{page.kong_version}}/reference/deck_file_list-tags)	 - List current tags from objects in a decK file
+* [deck file merge](/deck/{{page.kong_version}}/reference/deck_file_merge)	 - Merge multiple decK files into one
+* [deck file openapi2kong](/deck/{{page.kong_version}}/reference/deck_file_openapi2kong)	 - Convert OpenAPI specifications to Kong's decK format
+* [deck file patch](/deck/{{page.kong_version}}/reference/deck_file_patch)	 - Apply patches on top of a decK file
+* [deck file remove-tags](/deck/{{page.kong_version}}/reference/deck_file_remove-tags)	 - Remove tags from objects in a decK file
+{%- if_version gte:1.28.x -%}
+* [deck file render](/deck/{{page.kong_version}}/reference/deck_file_render)	 - Combines multiple complete configuration files and renders them as one Kong declarative config file.
+* [deck file validate](/deck/{{page.kong_version}}/reference/deck_file_validate)	 - Locally validates the state file for basic structure or relationship errors.
+{% endif_version %}
+{% endif %}
+
+{% if include.deprecated_links == "true" %}
+Deprecated:
+* [deck convert](/deck/{{page.kong_version}}/reference/deck_convert/)
+* [deck diff](/deck/{{page.kong_version}}/reference/deck_diff/)
+* [deck dump](/deck/{{page.kong_version}}/reference/deck_dump/)
+* [deck ping](/deck/{{page.kong_version}}/reference/deck_ping/)
+* [deck reset](/deck/{{page.kong_version}}/reference/deck_reset/)
+* [deck sync](/deck/{{page.kong_version}}/reference/deck_sync/)
+* [deck validate](/deck/{{page.kong_version}}/reference/deck_validate/)
+{% endif %}
diff --git a/app/_src/deck/reference/deck.md b/app/_src/deck/reference/deck.md
@@ -13,7 +13,20 @@ It can be used to export, import, or sync entities to Kong.
 
 {% include_cached /md/deck-global-flags.md kong_version=page.kong_version %}
 
-## See also
+## decK CLI commands
+
+<!--vale off -->
+
+{% if_version gte:1.28.x %}
+
+{% include /md/deck-reference-links.md general_links='true' gateway_links='true' file_links='true' deprecated_links='true' %}
+
+{% endif_version %}
+
+
+<!-- ################ PRE 1.28 REFACTORING ################## -->
+
+{% if_version lte:1.27.x %}
 
 {% if_version gte:1.8.x %}
 * [deck completion](/deck/{{page.kong_version}}/reference/deck_completion/)	 - Generate completion script
@@ -29,3 +42,15 @@ It can be used to export, import, or sync entities to Kong.
 * [deck sync](/deck/{{page.kong_version}}/reference/deck_sync/)	 - Sync performs operations to get Kong's configuration to match the state file
 * [deck validate](/deck/{{page.kong_version}}/reference/deck_validate/)	 - Validate the state file
 * [deck version](/deck/{{page.kong_version}}/reference/deck_version/)	 - Print the decK version
+{% if_version gte:1.24.x %}
+* [deck file](/deck/{{page.kong_version}}/reference/deck_file_add-plugins)	 - Subcommand to host the decK file operations
+* [deck file add-plugins](/deck/{{page.kong_version}}/reference/deck_file_add-plugins)	 - Add plugins to objects in a decK file
+* [deck file add-tags](/deck/{{page.kong_version}}/reference/deck_file_add-tags)	 - Add tags to objects in a decK file
+* [deck file list-tags](/deck/{{page.kong_version}}/reference/deck_file_list-tags)	 - List current tags from objects in a decK file
+* [deck file merge](/deck/{{page.kong_version}}/reference/deck_file_merge)	 - Merge multiple decK files into one
+* [deck file openapi2kong](/deck/{{page.kong_version}}/reference/deck_file_openapi2kong)	 - Convert OpenAPI files to Kong's decK format
+* [deck file patch](/deck/{{page.kong_version}}/reference/deck_file_patch)	 - Apply patches on top of a decK file
+* [deck file remove-tags](/deck/{{page.kong_version}}/reference/deck_file_remove-tags)	 - Remove tags from objects in a decK file
+{% endif_version %}
+
+{% endif_version %}
diff --git a/app/_src/deck/reference/deck_completion.md b/app/_src/deck/reference/deck_completion.md
@@ -4,10 +4,13 @@ source_url: https://github.com/Kong/deck/tree/main/cmd/completion.go
 content_type: reference
 ---
 
+Generate completion script.
+
+## Examples
 
 {% navtabs %}
 {% navtab Bash %}
-### Bash
+
 ```sh
 source <(deck completion bash)
 ```
@@ -31,7 +34,6 @@ deck completion bash > /usr/local/etc/bash_completion.d/deck
 {% endnavtab %}
 {% navtab Zsh%}
 
-### Zsh
 If shell completion is not already enabled in your environment,
 you will need to enable it. You can execute the following once:
 ```sh
@@ -48,8 +50,6 @@ You will need to start a new shell for this setup to take effect.
 {% endnavtab %}
 {% navtab fish %}
 
-### fish
-
 ```sh
 deck completion fish | source
 ```
@@ -62,8 +62,6 @@ deck completion fish > ~/.config/fish/completions/deck.fish
 {% endnavtab %}
 {% navtab Powershell %}
 
-### PowerShell
-
 ```powershell
 PS> deck completion powershell | Out-String | Invoke-Expression
 ```
@@ -77,8 +75,6 @@ Then source this file from your PowerShell profile.
 {% endnavtab %}
 {% endnavtabs %}
 
-
-
 ## Syntax
 
 ```
@@ -88,7 +84,7 @@ deck completion [command-specific flags] [global flags]
 ## Flags
 
 `-h`, `--help`
-:  help for completion (Default: `false`)
+:  help for completion 
 
 
 ## Global flags

diff --git a/app/_src/deck/reference/deck_convert.md b/app/_src/deck/reference/deck_convert.md
@@ -1,9 +1,15 @@
 ---
 title: deck convert
-source_url: https://github.com/Kong/deck/tree/main/cmd/convert.go
 content_type: reference
+short_desc: The convert command changes configuration files from one format into another compatible format.
 ---
 
+{% if_version gte:1.28.x %}
+{:.warning}
+> **Warning**: This command is deprecated and will be removed in a future version.
+Use [deck file convert](/deck/{{page.kong_version}}/reference/deck_file_convert/) instead.
+{% endif_version %}
+
 The convert command changes configuration files from one format
 into another compatible format. For example, a configuration for `kong-gateway`
 can be converted into a `konnect` configuration file.
@@ -22,7 +28,7 @@ deck convert [command-specific flags] [global flags]
    if_version gte:1.7.x lte:1.14.x %}`kong-gateway`{% endif_version %}
 
 `-h`, `--help`
-:  help for convert (Default: `false`)
+:  help for convert 
 
 `--input-file`
 :  configuration file to be converted. Use `-` to read from stdin.

diff --git a/app/_src/deck/reference/deck_diff.md b/app/_src/deck/reference/deck_diff.md
@@ -1,9 +1,15 @@
 ---
 title: deck diff
-source_url: https://github.com/Kong/deck/tree/main/cmd/diff.go
 content_type: reference
+short_desc: The diff command is similar to a dry run of the decK sync command.
 ---
 
+{% if_version gte:1.28.x %}
+{:.warning}
+> **Warning**: This command is deprecated and will be removed in a future version.
+Use [deck gateway diff](/deck/{{page.kong_version}}/reference/deck_gateway_diff/) instead.
+{% endif_version %}
+
 The diff command is similar to a dry run of the 'decK sync' command.
 
 It loads entities from Kong and performs a diff with
@@ -20,7 +26,7 @@ deck diff [command-specific flags] [global flags]
 ## Flags
 
 `-h`, `--help`
-:  help for diff (Default: `false`)
+:  help for diff 
 
 {% if_version gte:1.16.x %}
 `--no-mask-deck-env-vars-value`
@@ -36,7 +42,7 @@ and exit code 1 if an error occurs. (Default: `false`)
 :  Maximum number of concurrent operations. (Default: `10`)
 
 `--rbac-resources-only`
-:  sync only the RBAC resources (Kong Enterprise only). (Default: `false`)
+:  sync only the RBAC resources **{{site.ee_product_name}} only**. (Default: `false`)
 
 `--select-tag`
 :  only entities matching tags specified via this flag are diffed.
@@ -65,7 +71,7 @@ This flag can be specified multiple times for multiple files.
 Use `-` to read from stdin. (Default: `[kong.yaml]`)
 
 `-w`, `--workspace`
-:  Diff configuration with a specific workspace (Kong Enterprise only).
+:  Diff configuration with a specific workspace ({{site.ee_product_name}} only).
 This takes precedence over _workspace fields in state files.