From 439b30399db8cc054241e8a5dfc526d443559576 Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 9 Nov 2022 14:34:54 -0500 Subject: [PATCH] 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 Co-authored-by: Angel * [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 * 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 * 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 Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> --- app/_data/docs_nav_deck_1.16.x.yml | 85 ++++++++++++ app/_data/kong_versions.yml | 7 +- src/deck/3.0-upgrade.md | 8 +- src/deck/availability-stages.md | 2 +- src/deck/compatibility-promise.md | 2 +- src/deck/design-architecture.md | 2 +- src/deck/faqs.md | 2 +- src/deck/guides/backup-restore.md | 2 +- src/deck/guides/best-practices.md | 2 +- src/deck/guides/ci-driven-configuration.md | 2 +- .../deduplicate-plugin-configuration.md | 60 +++++++- src/deck/guides/defaults-v2.md | 2 +- src/deck/guides/defaults.md | 2 +- src/deck/guides/distributed-configuration.md | 4 +- src/deck/guides/environment-variables.md | 11 +- src/deck/guides/kong-enterprise.md | 2 +- src/deck/guides/multi-file-state.md | 2 +- src/deck/guides/security.md | 12 ++ src/deck/guides/vaults.md | 131 ++++++++++++++++++ src/deck/index.md | 2 +- src/deck/reference/deck.md | 2 +- src/deck/reference/deck_completion.md | 2 +- src/deck/reference/deck_convert.md | 7 +- src/deck/reference/deck_diff.md | 7 +- src/deck/reference/deck_dump.md | 2 +- src/deck/reference/deck_konnect.md | 2 +- src/deck/reference/deck_konnect_diff.md | 7 +- src/deck/reference/deck_konnect_dump.md | 2 +- src/deck/reference/deck_konnect_ping.md | 2 +- src/deck/reference/deck_konnect_sync.md | 7 +- src/deck/reference/deck_ping.md | 2 +- src/deck/reference/deck_reset.md | 7 +- src/deck/reference/deck_sync.md | 10 +- src/deck/reference/deck_validate.md | 2 +- src/deck/reference/deck_version.md | 2 +- .../secrets-management/advanced-usage.md | 90 ++++++------ .../secrets-management/backends/aws-sm.md | 23 +++ .../secrets-management/backends/env.md | 29 +++- .../secrets-management/backends/gcp-sm.md | 25 +++- .../backends/hashicorp-vault.md | 37 ++++- 40 files changed, 518 insertions(+), 91 deletions(-) create mode 100644 app/_data/docs_nav_deck_1.16.x.yml create mode 100644 src/deck/guides/security.md create mode 100644 src/deck/guides/vaults.md diff --git a/app/_data/docs_nav_deck_1.16.x.yml b/app/_data/docs_nav_deck_1.16.x.yml new file mode 100644 index 000000000000..51cf2192aeca --- /dev/null +++ b/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 diff --git a/app/_data/kong_versions.yml b/app/_data/kong_versions.yml index f58f9f7b6c16..a72038bda300 100644 --- a/app/_data/kong_versions.yml +++ b/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" diff --git a/src/deck/3.0-upgrade.md b/src/deck/3.0-upgrade.md index c0adc66b76fe..c64963c5b772 100644 --- a/src/deck/3.0-upgrade.md +++ b/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. diff --git a/src/deck/availability-stages.md b/src/deck/availability-stages.md index 29c582eadfcc..cfb7e9422cd2 100644 --- a/src/deck/availability-stages.md +++ b/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 %} diff --git a/src/deck/compatibility-promise.md b/src/deck/compatibility-promise.md index 8b096025c8ce..2a90818fdb5b 100644 --- a/src/deck/compatibility-promise.md +++ b/src/deck/compatibility-promise.md @@ -1,6 +1,6 @@ --- title: Compatibility Promise -content-type: explanation +content_type: explanation --- decK's compatibility guarantees are: diff --git a/src/deck/design-architecture.md b/src/deck/design-architecture.md index c28fea99b1b6..dc2a3eed4c67 100644 --- a/src/deck/design-architecture.md +++ b/src/deck/design-architecture.md @@ -1,6 +1,6 @@ --- title: Design & Architecture -content-type: explanation +content_type: explanation --- ## Underlying architecture diff --git a/src/deck/faqs.md b/src/deck/faqs.md index 3bf37dc15974..36c71e930d1d 100644 --- a/src/deck/faqs.md +++ b/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? diff --git a/src/deck/guides/backup-restore.md b/src/deck/guides/backup-restore.md index 7bb1efc4a8a6..ad5b1a5b0301 100644 --- a/src/deck/guides/backup-restore.md +++ b/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 diff --git a/src/deck/guides/best-practices.md b/src/deck/guides/best-practices.md index e3267c5726c3..9c92eaed2936 100644 --- a/src/deck/guides/best-practices.md +++ b/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 diff --git a/src/deck/guides/ci-driven-configuration.md b/src/deck/guides/ci-driven-configuration.md index 50ca10815560..cf1976f309e8 100644 --- a/src/deck/guides/ci-driven-configuration.md +++ b/src/deck/guides/ci-driven-configuration.md @@ -1,6 +1,6 @@ --- title: CI-driven Configuration -content-type: explanation +content_type: explanation --- ## Configuration as code diff --git a/src/deck/guides/deduplicate-plugin-configuration.md b/src/deck/guides/deduplicate-plugin-configuration.md index d039fcc69105..f630963c978f 100644 --- a/src/deck/guides/deduplicate-plugin-configuration.md +++ b/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`. diff --git a/src/deck/guides/defaults-v2.md b/src/deck/guides/defaults-v2.md index 22e0dc23c516..6054294e1175 100644 --- a/src/deck/guides/defaults-v2.md +++ b/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. diff --git a/src/deck/guides/defaults.md b/src/deck/guides/defaults.md index c8ab4442b260..68db352de095 100644 --- a/src/deck/guides/defaults.md +++ b/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 diff --git a/src/deck/guides/distributed-configuration.md b/src/deck/guides/distributed-configuration.md index 10cd71ff69ce..8a389baa151c 100644 --- a/src/deck/guides/distributed-configuration.md +++ b/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 diff --git a/src/deck/guides/environment-variables.md b/src/deck/guides/environment-variables.md index eaf9bcc96840..a4c5631fb114 100644 --- a/src/deck/guides/environment-variables.md +++ b/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: - 
export DECK_API_KEY=
{API_KEY}
+ + ```sh + export DECK_API_KEY={YOUR_API_KEY} + ``` 2. Save the following snippet into a `env-demo.yaml` file: diff --git a/src/deck/guides/kong-enterprise.md b/src/deck/guides/kong-enterprise.md index ec70e76d6e19..8a4aa36f4145 100644 --- a/src/deck/guides/kong-enterprise.md +++ b/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}}. diff --git a/src/deck/guides/multi-file-state.md b/src/deck/guides/multi-file-state.md index 1bc17ad7c693..8d05fe8d95ab 100644 --- a/src/deck/guides/multi-file-state.md +++ b/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 diff --git a/src/deck/guides/security.md b/src/deck/guides/security.md new file mode 100644 index 000000000000..8e95e46cd33f --- /dev/null +++ b/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.

• This method can store any configuration values used by {{site.base_gateway}} entities.

• 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.
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.

• 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.

• Secrets management is only available for {{site.base_gateway}} Enterprise packages. It is not available for open-source {{site.base_gateway}}. diff --git a/src/deck/guides/vaults.md b/src/deck/guides/vaults.md new file mode 100644 index 000000000000..b4e4050c3aaf --- /dev/null +++ b/src/deck/guides/vaults.md @@ -0,0 +1,131 @@ +--- +title: Secret Management with decK +content_type: how-to +--- + +decK supports secret references for encoded values in {{site.base_gateway}}. +You can store your secrets in a [vault backend](/gateway/latest/kong-enterprise/secrets-management/), +then reference them in your declarative configuration files. + +You can use secrets to store sensitive data, such as credentials. + +See [Secrets Management in {{site.base_gateway}}](/gateway/latest/kong-enterprise/secrets-management/#what-can-be-stored-as-a-secret) +for a full list of values that can be stored as secrets. + +{:.note} +> For storing configuration values as environment variables on the node running decK, +see [Using Environment Variables with decK](/deck/latest/guides/environment-variables/). +The reference format for secrets is _not_ the same as references for environment +variables used by decK. + +## Configure a secret vault + +Set up a secret vault using the {{site.base_gateway}} `vaults` entity. + +For example, add the following snippet to your +declarative configuration file (`kong.yaml` by default) to set up a vault using +environment variables as the backend, configure a prefix for the vault, and a +prefix for the reference: + +```yaml +_format_version: "3.0" +vaults: +- config: + prefix: MY_SECRET_ + description: ENV vault for secrets + name: env + prefix: my-env-vault +``` + +Key | Description +----|--- +`vaults.config` | Stores the configuration for a particular vault. The configuration values required depend on the vault that you are using. In this example, the `vaults.config.prefix` value configures the prefix for the environment variable that the value will be stored in. See the individual [vault backends](/gateway/latest/kong-enterprise/secrets-management/backends/) to find the required configuration values for your particular vault type. +`vaults.description` | An optional description for your vault. +`vaults.name` | The type of vault. Accepts one of: `env`, `gcp`, `aws`, or `hcv`. +`vaults.prefix` | The reference prefix. You need this prefix to access secrets stored in this vault. For example, `{vault://my-env-vault/}`. + +{{site.base_gateway}} also supports HashiCorp Vault, GCP, and AWS as [vault backends](/gateway/latest/kong-enterprise/secrets-management/backends/). + +{:.important} +> **Important**: Manage your vault configuration separately from other {{site.base_gateway}} +entities. See [Best Practices](#best-practices) in this topic for more information. + +## Store and reference secrets + +Store your sensitive values as secrets on the node running the {{site.base_gateway}} instance: + +```sh +export MY_SECRET_CERT="" \ +export MY_SECRET_KEY="" +``` + +Now you can reference the secret in subsequent configurations: + +```yaml +certificates: +- id: B0DBE8FD-E5E6-414A-A0DC-0160665620AB + cert: "{vault://my-env-vault/cert}" + key: "{vault://my-env-vault/key}" +``` + +{:.important} +> **Important**: If a vault reference changes, it can cause {{site.base_gateway}} to not function correctly. +If changing references, make sure to update both the vault configuration and all places +that the reference is used in. + +## Best practices + +When managing vaults with declarative configuration, you need to take certain precautions. +For larger teams with many contributors, or organizations with multiple teams, +we recommend splitting vault configuration and managing it separately. + +**Why split out vault configuration?** + +* Vault are closer to infrastructure than other {{site.base_gateway}} configurations. +Separation of routing policies from infrastructure-specific configurations helps +keep configuration organized. +* Vaults may be shared across teams. In this case, one specific team shouldn't +control the vault's configuration. One team changing the vault a can have +disastrous impact on another team. +* If a vault is deleted while in use -- that is, if there are still references to +secrets in a vault in configuration -- it can lead to total loss of proxy capabilities. +Those secrets would be unrecoverable. + +**How should I manage my vault configuration with decK?** + +To keep your environment secure and avoid taking down your proxies by accident, make sure to: + +* Manage vaults with distributed configuration via tags. +* Use a separate [RBAC role, user, and token](/gateway/latest/admin-api/rbac/reference) +to manage vaults. Don't use a generic admin user. +* Set up a separate CI pipeline for vaults. + +### Manage vaults with distributed configuration + +Avoid mixing vault configuration with other {{site.base_gateway}} entities. +Instead, manage vaults with [distributed configuration](/deck/latest/guides/distributed-configuration) via tags. + +Tag your vault in the declarative configuration file: + +```yaml +_format_version: "3.0" +vaults: +- config: + prefix: MY_SECRET_ + description: ENV vault for secrets + name: env + prefix: my-env-vault + tags: + - env-vault +``` + +When updating the vault, `deck dump` the configuration with the `--select-tag` flag: + +```sh +deck dump --select-tag env-vault +``` + +Make your changes to the vault, then push it back up with `deck 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/src/deck/index.md b/src/deck/index.md index 296e874e6a45..32680a941488 100644 --- a/src/deck/index.md +++ b/src/deck/index.md @@ -1,7 +1,7 @@ --- title: decK subtitle: Manage Konnect and Kong Gateway configuration declaratively -content-type: explanation +content_type: explanation --- decK helps manage Kong’s configuration in a declarative fashion. This means that diff --git a/src/deck/reference/deck.md b/src/deck/reference/deck.md index 152fbe943f4d..ab272f148f84 100644 --- a/src/deck/reference/deck.md +++ b/src/deck/reference/deck.md @@ -1,7 +1,7 @@ --- title: deck source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The deck tool helps you manage Kong clusters with a declarative diff --git a/src/deck/reference/deck_completion.md b/src/deck/reference/deck_completion.md index e8a53ace1792..40787971ffa5 100644 --- a/src/deck/reference/deck_completion.md +++ b/src/deck/reference/deck_completion.md @@ -1,7 +1,7 @@ --- title: deck completion source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- diff --git a/src/deck/reference/deck_convert.md b/src/deck/reference/deck_convert.md index 9f29d297b797..fd0ff84d5e25 100644 --- a/src/deck/reference/deck_convert.md +++ b/src/deck/reference/deck_convert.md @@ -1,7 +1,7 @@ --- title: deck convert source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The convert command changes configuration files from one format @@ -29,12 +29,17 @@ deck convert [command-specific flags] [global flags] `--output-file` : file to write configuration to after conversion. Use `-` to write to stdout. + {% if_version gte:1.16.x %} (Default: `"kong.yaml"`){% endif_version %} `--to` : desired format of the output, allowed formats: {% if_version gte:1.15.x %}[`konnect` `kong-gateway-3.x`]{% endif_version %}{% if_version gte:1.7.x lte:1.14.x %}`konnect`{% endif_version %} +{% if_version gte: 1.16.x %} +`--yes` +: assume `yes` to prompts and run non-interactively. (Default: `false`) +{% endif_version %} {% if_version gte:1.7.x %} diff --git a/src/deck/reference/deck_diff.md b/src/deck/reference/deck_diff.md index 75c8acc6aa21..6fe5942e235a 100644 --- a/src/deck/reference/deck_diff.md +++ b/src/deck/reference/deck_diff.md @@ -1,7 +1,7 @@ --- title: deck diff source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The diff command is similar to a dry run of the 'decK sync' command. @@ -22,6 +22,11 @@ deck diff [command-specific flags] [global flags] `-h`, `--help` : help for diff (Default: `false`) +{% if_version gte:1.16.x %} +`--no-mask-deck-env-vars-value` +: do not mask `DECK_` environment variable values at diff output. (Default: `false`) +{% endif_version %} + `--non-zero-exit-code` : return exit code 2 if there is a diff present, exit code 0 if no diff is found, diff --git a/src/deck/reference/deck_dump.md b/src/deck/reference/deck_dump.md index 007706fd9b72..611ca518dcde 100644 --- a/src/deck/reference/deck_dump.md +++ b/src/deck/reference/deck_dump.md @@ -1,7 +1,7 @@ --- title: deck dump source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The dump command reads all entities present in Kong diff --git a/src/deck/reference/deck_konnect.md b/src/deck/reference/deck_konnect.md index b4d5f55418ab..9b1625b6eedf 100644 --- a/src/deck/reference/deck_konnect.md +++ b/src/deck/reference/deck_konnect.md @@ -1,7 +1,7 @@ --- title: deck konnect source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The {{site.konnect_short_name}} command prints subcommands that can be used to diff --git a/src/deck/reference/deck_konnect_diff.md b/src/deck/reference/deck_konnect_diff.md index a32b14bd2036..66644ffded8d 100644 --- a/src/deck/reference/deck_konnect_diff.md +++ b/src/deck/reference/deck_konnect_diff.md @@ -1,7 +1,7 @@ --- title: deck konnect diff source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The {{site.konnect_short_name}} diff command is similar to a dry run of the `deck konnect sync` command. @@ -26,6 +26,11 @@ deck konnect diff [command-specific flags] [global flags] `-h`, `--help` : help for diff (Default: `false`) +{% if_version gte:1.16.x %} +`--no-mask-deck-env-vars-value` +: do not mask `DECK_` environment variable values at diff output. (Default: `false`) +{% endif_version %} + `--include-consumers` : export consumers, associated credentials and any plugins associated with consumers. (Default: `false`) diff --git a/src/deck/reference/deck_konnect_dump.md b/src/deck/reference/deck_konnect_dump.md index ad977148ef76..181e3a7d2f93 100644 --- a/src/deck/reference/deck_konnect_dump.md +++ b/src/deck/reference/deck_konnect_dump.md @@ -1,7 +1,7 @@ --- title: deck konnect dump source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The `konnect dump` command reads all entities present in {{site.konnect_short_name}} diff --git a/src/deck/reference/deck_konnect_ping.md b/src/deck/reference/deck_konnect_ping.md index a81ca9a60c12..9c9204f2e0df 100644 --- a/src/deck/reference/deck_konnect_ping.md +++ b/src/deck/reference/deck_konnect_ping.md @@ -1,7 +1,7 @@ --- title: deck konnect ping source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The {{site.konnect_short_name}} ping command can be used to verify if decK diff --git a/src/deck/reference/deck_konnect_sync.md b/src/deck/reference/deck_konnect_sync.md index c65e1af12f36..78b86d82c218 100644 --- a/src/deck/reference/deck_konnect_sync.md +++ b/src/deck/reference/deck_konnect_sync.md @@ -1,7 +1,7 @@ --- title: deck konnect sync source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The {{site.konnect_short_name}} sync command reads the state file and performs operations in {{site.konnect_short_name}} @@ -26,6 +26,11 @@ deck konnect sync [command-specific flags] [global flags] `--include-consumers` : export consumers, associated credentials and any plugins associated with consumers. (Default: `false`) +{% if_version gte:1.16.x %} +`--no-mask-deck-env-vars-value` +: do not mask `DECK_` environment variable values at diff output. (Default: `false`) +{% endif_version %} + `--parallelism` : Maximum number of concurrent operations. (Default: `100`) diff --git a/src/deck/reference/deck_ping.md b/src/deck/reference/deck_ping.md index aca7b1d3f894..1a3f82b34a2c 100644 --- a/src/deck/reference/deck_ping.md +++ b/src/deck/reference/deck_ping.md @@ -1,7 +1,7 @@ --- title: deck ping source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The ping command can be used to verify if decK diff --git a/src/deck/reference/deck_reset.md b/src/deck/reference/deck_reset.md index 2f6c66d2d224..dca160ebbdb3 100644 --- a/src/deck/reference/deck_reset.md +++ b/src/deck/reference/deck_reset.md @@ -1,7 +1,7 @@ --- title: deck reset source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The reset command deletes all entities in Kong's database.string. @@ -28,6 +28,11 @@ deck reset [command-specific flags] [global flags] `-h`, `--help` : help for reset (Default: `false`) +{% if_version gte:1.16.x %} +`--no-mask-deck-env-vars-value` +: do not mask `DECK_` environment variable values at diff output. (Default: `false`) +{% endif_version %} + `--rbac-resources-only` : reset only the RBAC resources (Kong Enterprise only). (Default: `false`) diff --git a/src/deck/reference/deck_sync.md b/src/deck/reference/deck_sync.md index 30d87b7aa4f1..befe2e51470f 100644 --- a/src/deck/reference/deck_sync.md +++ b/src/deck/reference/deck_sync.md @@ -1,7 +1,7 @@ --- title: deck sync source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The sync command reads the state file and performs operation on Kong @@ -23,6 +23,11 @@ See `db_update_propagation` in `kong.conf`. (Default: `0`) `-h`, `--help` : help for sync (Default: `false`) +{% if_version gte:1.16.x %} +`--no-mask-deck-env-vars-value` +: do not mask `DECK_` environment variable values at diff output. (Default: `false`) +{% endif_version %} + `--parallelism` : Maximum number of concurrent operations. (Default: `10`) @@ -55,7 +60,8 @@ When this setting has multiple tag values, entities must match every tag. This flag can be specified multiple times for multiple files. Use `-` to read from stdin. (Default: `[kong.yaml]`) -`--workspace` + +{% if_version gte:1.16.x %} `-w`,{% endif_version %} `--workspace` : Sync configuration to a specific workspace (Kong Enterprise only). This takes precedence over `_workspace` fields in state files. diff --git a/src/deck/reference/deck_validate.md b/src/deck/reference/deck_validate.md index e3619dd504cf..c5dd64fa5f8d 100644 --- a/src/deck/reference/deck_validate.md +++ b/src/deck/reference/deck_validate.md @@ -1,7 +1,7 @@ --- title: deck validate source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The validate command reads the state file and ensures validity. diff --git a/src/deck/reference/deck_version.md b/src/deck/reference/deck_version.md index 19f93fb2d195..b12c5517e0cf 100644 --- a/src/deck/reference/deck_version.md +++ b/src/deck/reference/deck_version.md @@ -1,7 +1,7 @@ --- title: deck version source_url: https://github.com/Kong/deck/tree/main/cmd -content-type: reference +content_type: reference --- The version command prints the version of decK along with a Git short diff --git a/src/gateway/kong-enterprise/secrets-management/advanced-usage.md b/src/gateway/kong-enterprise/secrets-management/advanced-usage.md index 9f4ecd49845c..010c66a89f55 100644 --- a/src/gateway/kong-enterprise/secrets-management/advanced-usage.md +++ b/src/gateway/kong-enterprise/secrets-management/advanced-usage.md @@ -4,6 +4,9 @@ title: Advanced Secrets Configuration Vault implementations offer a variety of advanced configuration options. +{:.warning} +> Kong Manager currently doesn't support configuring vault entities. + ## Query arguments You can configure your vault backend with query arguments. @@ -17,7 +20,7 @@ For example, the following query uses an option called `prefix` with the value ` For more information on available configuration options, refer to respective [vault backend documentation](/gateway/{{page.kong_version}}/kong-enterprise/secrets-management/backends). -## Environment Variables +## Environment variables You can configure your vault backend with `KONG_VAULT__` environment variables. @@ -31,46 +34,6 @@ export KONG_VAULT_ENV_PREFIX=SECURE_ You can configure your vault backend using the `vaults` entity. -```bash -http -f PUT :8001/vaults/my-env-vault \ - name=env \ - description="ENV vault for secrets" \ - config.prefix=SECURE_ -``` - -This lets you drop the configuration from environment variables and query arguments and use the entity name in the reference. - -```bash -{vault://my-env-vault/my-secret-config-value} -``` - -For more information, see the section on the [Vaults entity](#vaults-entity). - -## Vaults CLI - -```text -Usage: kong vault COMMAND [OPTIONS] - -Vault utilities for {{site.base_gateway}}. - -Example usage: - TEST=hello kong vault get env/test - -The available commands are: - get Retrieves a value for - -Options: - -c,--conf (optional string) configuration file - -p,--prefix (optional string) override prefix directory - --v verbose - --vv debug -``` - -## Vaults Entity - -{:.warning} -> Kong Manager currently doesn't support configuring vault entities. - The Vault entity can only be used once the database is initialized. Secrets for values that are used _before_ the database is initialized can't make use of the Vaults entity. Create a Vault entity: @@ -116,3 +79,48 @@ Result: ``` Config options depend on the associated [backend](/gateway/{{page.kong_version}}/kong-enterprise/secrets-management/backends) used. + +This lets you drop the configuration from environment variables and query arguments and use the entity name in the reference: + +```bash +{vault://my-env-vault/my-secret-config-value} +``` + +## Vaults CLI + +```text +Usage: kong vault COMMAND [OPTIONS] + +Vault utilities for {{site.base_gateway}}. + +Example usage: + TEST=hello kong vault get env/test + +The available commands are: + get Retrieves a value for + +Options: + -c,--conf (optional string) configuration file + -p,--prefix (optional string) override prefix directory + --v verbose + --vv debug +``` + +## Declarative configuration + +{:.note} +> Secrets management is supported in decK 1.16 and later. + +You can configure a vault backend with decK. For example: + +```yaml +vaults: +- config: + prefix: MY_SECRET_ + description: ENV vault for secrets + name: env + prefix: my-env-vault +``` + +For more information on configuring vaults and using secret references in declarative +configuration files, see [Secret Management with decK](/deck/latest/guides/vaults). diff --git a/src/gateway/kong-enterprise/secrets-management/backends/aws-sm.md b/src/gateway/kong-enterprise/secrets-management/backends/aws-sm.md index 97361e3fe9b2..581cc7b2d3de 100644 --- a/src/gateway/kong-enterprise/secrets-management/backends/aws-sm.md +++ b/src/gateway/kong-enterprise/secrets-management/backends/aws-sm.md @@ -44,6 +44,9 @@ Access these secrets from `my-secret-name` like this: The Vault entity can only be used once the database is initialized. Secrets for values that are used _before_ the database is initialized can't make use of the Vaults entity. +{% navtabs %} +{% navtab Admin API %} + {% navtabs codeblock %} {% navtab cURL %} @@ -82,6 +85,26 @@ Result: "updated_at": 1644942689 } ``` +{% endnavtab %} +{% navtab Declarative configuration %} + +{:.note} +> Secrets management is supported in decK 1.16 and later. + +Add the following snippet into your declarative configuration file: + +```yaml +_format_version: "3.0" +vaults: +- config: + region: us-east-1 + description: Storing secrets in AWS Secrets Manager + name: aws + prefix: my-aws-sm-vault +``` + +{% endnavtab %} +{% endnavtabs %} With the Vault entity in place, you can now reference the secrets. This allows you to drop the `AWS_REGION` environment variable. diff --git a/src/gateway/kong-enterprise/secrets-management/backends/env.md b/src/gateway/kong-enterprise/secrets-management/backends/env.md index 9f246a7352dd..07fcd658e246 100644 --- a/src/gateway/kong-enterprise/secrets-management/backends/env.md +++ b/src/gateway/kong-enterprise/secrets-management/backends/env.md @@ -42,13 +42,16 @@ This allows you to do {:.note} > The Vault entity can only be used once the database is initialized. Secrets for values that are used _before_ the database is initialized can't make use of the Vaults entity. +{% navtabs %} +{% navtab Admin API %} + {% navtabs codeblock %} {% navtab cURL %} ```bash curl -i -X PUT http://HOSTNAME:8001/vaults/my-env-vault \ - --data name=env \ - --data description="Store secrets in environment variables" + --data name=env \ + --data description="Store secrets in environment variables" ``` {% endnavtab %} @@ -80,6 +83,28 @@ Result: } ``` +{% endnavtab %} +{% navtab Declarative configuration %} + +{:.note} +> Secrets management is supported in decK 1.16 and later. + +Add the following snippet to your declarative configuration file: + +```yaml +_format_version: "3.0" +vaults: +- config: + prefix: null + description: Store secrets in environment variables + name: env + prefix: my-env-vault +``` + +{% endnavtab %} +{% endnavtabs %} + + With the entity in place you can reference secrets like this: ```bash diff --git a/src/gateway/kong-enterprise/secrets-management/backends/gcp-sm.md b/src/gateway/kong-enterprise/secrets-management/backends/gcp-sm.md index 502de879b74c..cc12c46b3312 100644 --- a/src/gateway/kong-enterprise/secrets-management/backends/gcp-sm.md +++ b/src/gateway/kong-enterprise/secrets-management/backends/gcp-sm.md @@ -60,7 +60,7 @@ Note that both the provider (`gcp`) as well as the GCP project ID (`my_project_id`) need to be specified. You can configure the project ID with an environment variable before starting {{site.base_gateway}}: -```bash +```bash export KONG_VAULT_GCP_PROJECT_ID=my_project_id ``` @@ -76,6 +76,9 @@ Then you don't need to repeat it in references: Once the database is initialized, a Vault entity can be created that encapsulates the provider and the GCP project ID: +{% navtabs %} +{% navtab Admin API %} + {% navtabs codeblock %} {% navtab cURL %} @@ -115,6 +118,26 @@ Result: "updated_at": 1657874961 } ``` +{% endnavtab %} +{% navtab Declarative configuration %} + +{:.note} +> Secrets management is supported in decK 1.16 and later. + +Add the following snippet to your declarative configuration file: + +```yaml +_format_version: "3.0" +vaults: +- config: + project_id: my_project_id + description: Storing secrets in GCP Secrets Manager + name: gcp + prefix: my-gcp-sm-vault +``` + +{% endnavtab %} +{% endnavtabs %} With the Vault entity in place, you can reference the GCP secrets through it: diff --git a/src/gateway/kong-enterprise/secrets-management/backends/hashicorp-vault.md b/src/gateway/kong-enterprise/secrets-management/backends/hashicorp-vault.md index a465d34814a9..9fa7ea8671ca 100644 --- a/src/gateway/kong-enterprise/secrets-management/backends/hashicorp-vault.md +++ b/src/gateway/kong-enterprise/secrets-management/backends/hashicorp-vault.md @@ -1,5 +1,5 @@ --- -title: Hashicorp Vault +title: HashiCorp Vault badge: enterprise --- @@ -25,13 +25,16 @@ You can also store this information in an entity. {:.note} The Vault entity can only be used once the database is initialized. Secrets for values that are used _before_ the database is initialized can't make use of the Vaults entity. +{% navtabs %} +{% navtab Admin API %} + {% navtabs codeblock %} {% navtab cURL %} ```bash curl -i -X PUT http://HOSTNAME:8001/vaults/my-hashicorp-vault \ --data name="hcv" \ - --data description="Storing secrets in Hashicorp Vault" \ + --data description="Storing secrets in HashiCorp Vault" \ --data config.protocol="https" \ --data config.host="localhost" \ --data config.port="8200" \ @@ -46,7 +49,7 @@ curl -i -X PUT http://HOSTNAME:8001/vaults/my-hashicorp-vault \ ```bash http -f PUT :8001/vaults/my-hashicorp-vault \ name="hcv" \ - description="Storing secrets in Hashicorp Vault" \ + description="Storing secrets in HashiCorp Vault" \ config.protocol="https" \ config.host="localhost" \ config.port="8200" \ @@ -71,7 +74,7 @@ Result: "token": "" }, "created_at": 1645008893, - "description": "Storing secrets in Hashicorp Vault", + "description": "Storing secrets in HashiCorp Vault", "id": "0b43d867-05db-4bed-8aed-0fccb6667837", "name": "hcv", "prefix": "my-hashicorp-vault", @@ -80,6 +83,32 @@ Result: } ``` +{% endnavtab %} +{% navtab Declarative configuration %} + +{:.note} +> Secrets management is supported in decK 1.16 and later. + +Add the following snippet to your declarative configuration file: + +```yaml +_format_version: "3.0" +vaults: +- config: + host: localhost + kv: v2 + mount: secret + port: 8200 + protocol: https + token: + description: Storing secrets in HashiCorp Vault + name: hcv + prefix: my-hashicorp-vault +``` + +{% endnavtab %} +{% endnavtabs %} + ## Examples For example, let's say you've configured a HashiCorp Vault with a path of `secret/hello` and a key=value pair of `foo=world`: