decK Release 1.16 (#4648)

* [DOCU-2620] Deck Updates  (#4640)

* fix formatting

* placeholder

* deck updates

* add changes to convert

* fix content-type to content_type

* [DOCU-2754] Overriding _plugin_configs for specific entities with decK (#4662)

* add info about overriding specific fields in _plugin_configs

* Update src/deck/guides/deduplicate-plugin-configuration.md

Co-authored-by: Angel <Guaris@users.noreply.github.com>

Co-authored-by: Angel <Guaris@users.noreply.github.com>

* [DOCU-2595] decK upgrade guide: correct descriptions for sync, diff, validate (#4666)

fix description of deck sync, diff, and validate commands in upgrade guide

* [DOCU-2601] Secrets management with decK (#4661)

* document secrets management with decK

* rephrase

* another rephrase

* fix link

* Apply suggestions from code review

Co-authored-by: Angel <Guaris@users.noreply.github.com>

* apply feedback; temp best practices section that needs filling out

* split table comparing env variables with secrets into separate topic:

* fill out best practices section

* apply reviewer feedback

Co-authored-by: Angel <Guaris@users.noreply.github.com>

* decK: add env variable masking flag (#4749)

* add --no-mask-deck-env-vars-value flag for 1.16

* formatting; appease vale

Co-authored-by: lena.larionova <yelena.larionova@gmail.com>
Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com>

app/_data/docs_nav_deck_1.16.x.yml

@@ -0,0 +1,85 @@
+product: deck
+release: 1.16.x
+generate: true
+items:
+  - title: Introduction
+    icon: /assets/images/icons/documentation/icn-flag.svg
+    url: /deck/1.16.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: 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: 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: decK CLI Reference
+    icon: /assets/images/icons/documentation/icn-references-color.svg
+    url: /reference/deck
+    items:
+      - text: deck completion
+        url: /reference/deck_completion
+      - 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
+      - text: deck version
+        url: /reference/deck_version
+
+  - title: FAQ
+    icon: /assets/images/icons/documentation/icn-faq-color.svg
+    url: /faqs

app/_data/kong_versions.yml

@@ -227,7 +227,12 @@
 - release: "1.15.x"
   version: "1.15.0"
   edition: "deck"
-- release: "1.0.x"
+-
+  release: "1.16.x"
+  version: "1.16.0"
+  edition: "deck"
+-
+  release: "1.0.x"
   version: "1.0.4"
   edition: "mesh"
 - edition: "konnect"

src/deck/3.0-upgrade.md

@@ -82,10 +82,10 @@ It assumes that the paths have been correctly transformed, either via Kong migra
 
 `deck diff`, `deck validate` (with `--online` flag only), or `deck sync`
 : decK performs a check to ensure all regex routes are correctly prefixed.
-If not, the behavior depends on the control plane type:
-* Self-managed {{site.base_gateway}} 2.x (`_format_version: 1.1` or earlier): Prints an error and stops the operation.
-* Self-managed {{site.base_gateway}} 3.x (`_format_version: 3.0`): Prints a warning and goes ahead with the `diff`, `sync`, or `validate` operation as usual.
-* {{site.konnect_short_name}}: Prints a warning and goes ahead with the `diff`, `sync`, or `validate` operation as usual.
+The behavior of the command depends on the format version in the declarative configuration file:
+* `_format_version: 1.1` or earlier: Prints an error and stops the operation.
+* `_format_version: 3.0` with _incorrectly_ prefixed routes: Prints a warning and goes ahead with the `diff`, `sync`, or `validate` operation as usual.
+* `_format_version: 3.0` with _correctly_ prefixed routes: Goes ahead with the `diff`, `sync`, or `validate` operation as usual.
 
 `deck convert`
 : Includes `--from` and `--to` flags for converting state files between major versions.

src/deck/availability-stages.md

@@ -1,6 +1,6 @@
 ---
 title: Stages of software availability
-content-type: reference
+content_type: reference
 ---
 
 {% include_cached /md/availability-stages.md %}

src/deck/compatibility-promise.md

@@ -1,6 +1,6 @@
 ---
 title: Compatibility Promise
-content-type: explanation
+content_type: explanation
 ---
 
 decK's compatibility guarantees are:

src/deck/design-architecture.md

@@ -1,6 +1,6 @@
 ---
 title: Design & Architecture
-content-type: explanation
+content_type: explanation
 ---
 
 ## Underlying architecture

src/deck/faqs.md

@@ -1,6 +1,6 @@
 ---
 title: Frequently Asked Questions (FAQs)
-content-type: reference
+content_type: reference
 ---
 
 ### I use Terraform to configure Kong, why should I care about decK?

src/deck/guides/backup-restore.md

@@ -1,6 +1,6 @@
 ---
 title: Backup and Restore of Kong's Configuration
-content-type: how-to
+content_type: how-to
 ---
 
 You can use decK to back up and restore a subset or the entirety of

src/deck/guides/best-practices.md

@@ -1,6 +1,6 @@
 ---
 title: Best Practices when using decK
-content-type: explanation
+content_type: explanation
 ---
 
 - Always ensure that you have one decK process running at any time. Multiple

src/deck/guides/ci-driven-configuration.md

@@ -1,6 +1,6 @@
 ---
 title: CI-driven Configuration
-content-type: explanation
+content_type: explanation
 ---
 
 ## Configuration as code

src/deck/guides/deduplicate-plugin-configuration.md

@@ -1,6 +1,6 @@
 ---
 title: De-duplicate Plugin Configuration
-content-type: how-to
+content_type: how-to
 ---
 
 In some use cases, you might want to create a number of plugins associated with
@@ -9,10 +9,12 @@ if you change anything in the configuration of the plugin, you will have to
 repeat it for each instance of the plugin.
 
 In other use cases, the plugin configuration could be decided by a different
-team (Operations in some cases), and the configuration is directly used by
-an API owner.
+team, while the main {{site.base_gateway}}
+configuration is directly used by an API owner.
 
-decK has support for both of these use cases.
+decK supports both of these use cases.
+
+## Set up de-deduplicated plugin configuration
 
 Let's take an example configuration file:
 
@@ -133,8 +135,7 @@ server, then we have to edit the configuration of each and every instance of
 the plugin.
 
 To reduce this repetition, you can de-duplicate plugin configuration and
-reference it where we you need to use it.
-Please do note that this works across multiple files as well.
+reference it where we you need to use it. This works across multiple files as well.
 
 The above file now becomes:
 
@@ -220,3 +221,50 @@ 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
 apply those to your Kong clusters.
+
+## Overriding fields in plugin configs
+
+Settings configured in `_plugin_configs` are applied to all plugins with the same tag.
+While those settings provide the baseline configuration, you can change specific
+fields as needed for the entities that consume them.
+
+Specific values set for entities take precedence over values defined in `_plugin_configs`.
+
+For example, say that consumer `fub` in the previous example is still in the
+`gold-tier-limit`, but needs a rate limit of `50` minutes instead of `20`.
+You can change this value just for that specific consumer:
+
+```yaml
+- username: fub
+  tags:
+  - gold-tier
+  plugins:
+  - name: rate-limiting
+    _config: gold-tier-limit
+    config:
+      minute: 50
+    enabled: true
+    protocols:
+    - http
+    - https
+```
+
+Now compare the two gold tier consumers, `baz` and `fub`.
+
+First check `baz`:
+
+```sh
+curl -i -X http://localhost:8001/consumers/baz/plugins
+```
+
+Find the `minute` configuration in the result. This consumer picks up the
+setting of the `gold-tier-limit`, which is `minute: 20`.
+
+Now check `fub`:
+
+```sh
+curl -i -X http://localhost:8001/consumers/fub/plugins
+```
+
+Find the `minute` configuration in the result.
+This consumer has its own rate limit, `minute: 50`.

src/deck/guides/defaults-v2.md

@@ -1,6 +1,6 @@
 ---
 title: Set Up Object Defaults
-content-type: how-to
+content_type: how-to
 ---
 Use object defaults to enforce a set of standard values and avoid
 repetition in your configuration.

src/deck/guides/defaults.md

@@ -1,6 +1,6 @@
 ---
 title: Object Defaults
-content-type: how-to
+content_type: how-to
 ---
 
 {{site.base_gateway}} sets some default values for most objects, including Kong

src/deck/guides/distributed-configuration.md

@@ -1,6 +1,6 @@
 ---
 title: Distributed Configuration for Kong using decK
-content-type: explanation
+content_type: explanation
 ---
 
 decK can operate on a subset of configuration instead of taking care
@@ -74,7 +74,7 @@ configuration of other teams. You no longer need to maintain Kong's
 configuration in a single repository, where multiple teams need to
 co-ordinate.
 
-> The `--select-tag` flag is present on those two commands for use cases where
+The `--select-tag` flag is present on those two commands for use cases where
 the file cannot have `select_tags` defined inside it. It is strongly advised
 that you do not supply select-tags to sync and diff commands via flags.
 This is because the tag information should be part of the declarative

src/deck/guides/environment-variables.md

@@ -1,6 +1,6 @@
 ---
 title: Using environment variables with decK
-content-type: how-to
+content_type: how-to
 ---
 
 When you use decK to apply configurations to {{site.base_gateway}},
@@ -12,11 +12,18 @@ variables and apply it.
 Create environment variables with the `DECK_` prefix and reference them as
 `{%raw%}${{ env "DECK_*" }}{%endraw%}` in your state file.
 
+{:.note}
+> For storing {{site.base_gateway}} secrets in environment variables, see [Secrets Management with decK](/deck/latest/guides/vaults/).
+The reference format for secrets is _not_ the same as references for environment variables used by decK.
+
 The following example demonstrates how to apply an API key stored in an environment variable.
 You can use this method for any sensitive content.
 
 1. Create an environment variable:
-    <div class="copy-code-snippet"><pre><code>export DECK_API_KEY=<div contenteditable="true">{API_KEY}</div></code></pre></div>
+
+    ```sh
+    export DECK_API_KEY={YOUR_API_KEY}
+    ```
 
 2. Save the following snippet into a `env-demo.yaml` file:
 

src/deck/guides/kong-enterprise.md

@@ -1,6 +1,6 @@
 ---
 title: decK and Kong Gateway (Enterprise)
-content-type: explanation
+content_type: explanation
 ---
 
 All features of decK work with both {{site.ce_product_name}} and {{site.ee_product_name}}.

src/deck/guides/multi-file-state.md

@@ -1,6 +1,6 @@
 ---
 title: Using Multiple Files to Store Configuration
-content-type: explanation
+content_type: explanation
 ---
 
 decK can construct a state by combining multiple JSON or YAML files inside a

src/deck/guides/security.md

@@ -0,0 +1,12 @@
+---
+title: Securing sensitive data
+content_type: reference
+---
+
+With decK, you can manage sensitive values such as credentials or certificates
+using one of the following options:
+
+Option | Description | Why use this method?
+-------|-------------|---------------------
+[decK environment variables](/deck/{{page.kong_version}}/guides/environment-variables/) | Store values as environment variables and access them directly through decK. | • You can use this option for environment-specific values. <br><br> • This method can store any configuration values used by {{site.base_gateway}} entities. <br><br> • Available for all {{site.base_gateway}} packages: open-source, Enterprise Free mode, and Enterprise licensed mode.
+[Secrets in {{site.base_gateway}}](/deck/{{page.kong_version}}/guides/vaults/) | Store values as secrets in a vault, then reference the secrets with a `vault` reference. In this case, the {{site.base_gateway}} data plane manages the secrets with a `vaults` entity. <br>The environment variable vault can be used in Free mode without a license, while all other vault backends require a license. | • Is a secure way to manage sensitive information in one of the following vaults: AWS, GCP, HashiCorp Vault, or environment variables. <br><br> • You can use secrets to store many sensitive values, including parameters in Kong's configuration (`kong.conf`). See [Secrets Management in {{site.base_gateway}}](/gateway/latest/kong-enterprise/secrets-management/#what-can-be-stored-as-a-secret) for a full list. <br><br> • Secrets management is only available for {{site.base_gateway}} Enterprise packages. It is not available for open-source {{site.base_gateway}}.