diff --git a/app/_assets/stylesheets/index.css b/app/_assets/stylesheets/index.css index 2bbfb167..d06c5053 100644 --- a/app/_assets/stylesheets/index.css +++ b/app/_assets/stylesheets/index.css @@ -227,10 +227,10 @@ } .success, .warning, .danger, .info, .neutral { - @apply rounded-md p-4 gap-2 border-l-[3px] text-primary flex; + @apply rounded-md p-4 gap-2 border-l-[3px] text-primary flex flex-col pl-11 relative; &:not(.no-icon)::before { - @apply text-base content-['\f05a']; + @apply text-base content-['\f05a'] absolute left-4; font-family: "Font Awesome", FontAwesome; } } diff --git a/app/_data/products/api-ops.yml b/app/_data/products/api-ops.yml new file mode 100644 index 00000000..a0521d12 --- /dev/null +++ b/app/_data/products/api-ops.yml @@ -0,0 +1 @@ +name: APIOps \ No newline at end of file diff --git a/app/_how-tos/custom-deck-object-defaults.md b/app/_how-tos/custom-deck-object-defaults.md new file mode 100644 index 00000000..91351888 --- /dev/null +++ b/app/_how-tos/custom-deck-object-defaults.md @@ -0,0 +1,119 @@ +--- +title: Customize object defaults in decK + +works_on: + - on-prem + - konnect + +products: + - api-ops + +tools: + - deck + +related_resources: + - text: decK object defaults reference + url: /deck/object-defaults + +tldr: + q: | + How do I set custom default values for Kong Gateway entities? + a: | + You can configure your own custom Kong Gateway defaults via decK to + enforce a set of standard values and avoid repetition in your configuration. + +--- + +You can set custom configuration defaults for the following core +{{site.base_gateway}} objects: +- Service +- Route +- Upstream +- Target + +Default values get applied to both new and existing objects. See the +[order of precedence](/deck/object-defaults/#value-order-of-precedence) for more detail on how they +get applied. + +You can choose to define custom default values for any subset of entity fields, +or define all of them. decK still finds the default values using a +combination of your defined fields and the object's schema, based on the +order of precedence. + +decK supports setting custom object defaults both in self-managed +{{site.base_gateway}} and with {{site.konnect_saas}}. + +{:.warning} +> **Important:** This feature has the following limitations: +* Custom plugin object defaults are not supported. +* If an existing property's default value changes in a future {{site.base_gateway}} release, +decK has no way of knowing that this change has occurred, as its `defaults` +configuration would overwrite the value in your environment. + +## 1. Define default properties + +Define the properties you want to customize for {{site.base_gateway}} objects. +See the [object defaults reference](/deck/object-defaults) for all configurable objects and default values. + +In the `deck_files` directory you created in the [prerequisites](#prerequisites), create a `defaults.yaml` file +and add an `_info` section with `defaults`. +You can define a few select properties for a supported entity, such as a service: + +```yaml +_format_version: "3.0" +_info: + defaults: + service: + port: 8080 + protocol: https + retries: 10 +``` +{: data-file="defaults.yaml" } + +Or you could define custom default values for all available fields of a service and a route: + +```yaml +_format_version: "3.0" +_info: + defaults: + route: + https_redirect_status_code: 426 + path_handling: v1 + preserve_host: false + protocols: + - http + - https + regex_priority: 0 + request_buffering: true + response_buffering: true + strip_path: true + service: + port: 8080 + protocol: https + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + retries: 10 +``` +{: data-file="defaults.yaml" } + +## 2. Validate + +Sync your changes with {{site.base_gateway}}: + +```sh +deck gateway sync kong.yaml +``` + +Response: +```sh +Summary: +Created: 0 +Updated: 0 +Deleted: 0 +``` +{:.no-copy-code} + +Whether you choose to define a subset of custom defaults or all available +options, the result is the same: the diff summary doesn't show any changes, +because no entities have actually changed in the database. diff --git a/app/_includes/components/prereqs.html b/app/_includes/components/prereqs.html index aeeacb38..17e11d0e 100644 --- a/app/_includes/components/prereqs.html +++ b/app/_includes/components/prereqs.html @@ -1,10 +1,13 @@
{% if page.products %} {% for product in page.products %} -
-{% assign product_include = 'prereqs/products/' | append: product | append: '.md' %} -{% include {{ product_include }} tier=include.tier %} -
+ {% assign product_include = 'prereqs/products/' | append: product | append: '.md' %} + {% capture product_include_exists %}{% include_exists product_include %}{% endcapture %} + {% if product_include_exists == 'true' %} +
+ {% include {{ product_include }} tier=include.tier %} +
+ {% endif %} {% endfor %} {% endif %} diff --git a/app/_landing_pages/deck.yaml b/app/_landing_pages/deck.yaml index 10abe56e..a2a17e28 100644 --- a/app/_landing_pages/deck.yaml +++ b/app/_landing_pages/deck.yaml @@ -30,7 +30,7 @@ rows: - blocks: - type: tabs config: - - title: OSX (Homebrew) + - title: OSX include_content: tools/deck/install/osx - title: Windows include_content: tools/deck/install/windows @@ -318,6 +318,8 @@ rows: - blocks: - type: how_to_list config: + products: + - "api-ops" tools: - deck quantity: 5 diff --git a/app/_plugins/hooks/sections/how-to.rb b/app/_plugins/hooks/sections/how-to.rb index 76a26a29..0768e5c1 100644 --- a/app/_plugins/hooks/sections/how-to.rb +++ b/app/_plugins/hooks/sections/how-to.rb @@ -12,12 +12,21 @@ def section_title(h2, slug, title) end def build_wrapper(section_title = '') - Nokogiri::HTML::DocumentFragment.parse <<-HTML -
+ wrapper = if section_title != '' + <<-HTML +
#{section_title}
+
+ HTML + else + <<-HTML +
+
HTML + end + Nokogiri::HTML::DocumentFragment.parse(wrapper) end end end \ No newline at end of file diff --git a/app/_plugins/tags/how_to_list.rb b/app/_plugins/tags/how_to_list.rb index d747ba92..4104cfd5 100644 --- a/app/_plugins/tags/how_to_list.rb +++ b/app/_plugins/tags/how_to_list.rb @@ -21,7 +21,8 @@ def render(context) how_tos = @site.collections['how-tos'].docs.inject([]) do |result, t| match = (!config.key?('tags') || t.data.fetch('tags', []).intersect?(config['tags'])) && - (!config.key?('products') || t.data.fetch('products', []).intersect?(config['products'])) + (!config.key?('products') || t.data.fetch('products', []).intersect?(config['products'])) && + (!config.key?('tools') || t.data.fetch('tools', []).intersect?(config['tools'])) result << t if match break result if result.size == quantity diff --git a/app/_plugins/tags/include_exists.rb b/app/_plugins/tags/include_exists.rb new file mode 100644 index 00000000..cc7ce209 --- /dev/null +++ b/app/_plugins/tags/include_exists.rb @@ -0,0 +1,16 @@ +module Jekyll + class IncludeExistsTag < Liquid::Tag + def initialize(tag_name, file, tokens) + super + @file = file.strip + end + + def render(context) + site_source = context.registers[:site].source + file_path = File.join(site_source, '_includes', context[@file]) + File.exist?(file_path).to_s + end + end +end + +Liquid::Template.register_tag('include_exists', Jekyll::IncludeExistsTag) \ No newline at end of file diff --git a/app/deck/distributed-config.md b/app/deck/distributed-config.md new file mode 100644 index 00000000..024f81f3 --- /dev/null +++ b/app/deck/distributed-config.md @@ -0,0 +1,115 @@ +--- +title: Distributed Configuration for Kong using decK + +content_type: reference +layout: reference + +works_on: + - on-prem + - konnect + +productss: + - api-ops + +tools: + - deck +--- + +decK can operate on a subset of configuration instead of +managing the entire configuration of {{site.base_gateway}}. +You can do this by breaking up the configuration into multiple files and managing them using tags. + +With tags, you can use decK's `select-tag` feature to export, sync, or reset +only a subset of configuration. + +## Use cases + +Distributed configuration management can be very useful in a variety of scenarios. +For example: + +| Use case | Description | +|----------|-------------| +| Single Kong installation whose configuration is built by multiple teams | For example, one team manages the inventory API, while another team manages the users API. Both APIs are exposed via {{site.base_gateway}}.
Team Inventory needs to manage its configuration without worrying about the configuration of the other team, and vice versa. The two teams can push out configuration changes on their own schedules. | +| Very large configuration | You have a large set of entities - hundreds, maybe thousands - and it's very difficult to manage them all in one file. You can use decK to break up the configuration into different files with specific purposes. | +| Separation of consumer management | You want to declaratively manage all of the configuration for Kong except consumers and their credentials. This could be for any number of reasons:
- The consumers are being managed by another service
- The consumers are dynamically created
- The number of consumers is so large that it makes no sense to manage them in a declarative fashion | + +## Methods for managing distributed configuration + +### Tags + +Tags provide a way to associate metadata with entities +in {{site.base_gateway}}. You can also filter entities by tags on the list endpoints in {{site.base_gateway}}. + +Using this feature, decK associates tags with entities and can manage a group +of entities which share a common tag(s). + +When multiple tags are specified in decK, decK `AND`s those tags together, +meaning only entities containing all the tags will be managed by decK. +You can specify a combination of up to 5 tags, but we recommend using +fewer or only one tag, for performance reasons in Kong's codebase. + +### Gateway dump + +You can export a subset of entities in {{site.base_gateway}} by specifying common tags +using the `--select-tag` flag. + +For example, the following command generates a `kong.yaml` file with all entities +which have both of the specified tags: + +```shell +deck gateway dump --select-tag foo-tag --select-tag bar-tag +``` + +If you observe the file generated by decK, you will see the following section: + +```yaml +_info: + select_tags: + - foo-tag + - bar-tag +``` + +This sub-section tells decK to filter out entities containing select-tags during +a sync operation. + +### Gateway sync + +You don't need to specify `--select-tag` in `sync` and `diff` commands. +The commands will use the tags present in the state file and perform the diff +accordingly. + +Since the state files contain the tagging information, different teams can +make updates to the part of configuration in Kong without worrying about +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 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 +configuration file itself in order to provide a practical declarative file. +The tagging information and entity definitions should be present in one place, +else an error in supplying the wrong tag via the CLI can break the +configuration. + +### Gateway reset + +You can delete only a subset of entities sharing a tag using the `--select-tag` +flag on the `gateway reset` command. + +## Troubleshooting initial setup + +When you initially get started with a distributed configuration +management, you will likely run into a problem where the related entities +you would like to manage don't share a single database. + +To get around this problem, you can use one of the following approaches: + +- Go through each entity in Kong, and patch those entities with the common + tag(s) you'd like, then use decK's `dump` command to export by different + tags. +- Export the entire configuration of Kong, and divide up the configuration + into different files. Then, add the `select_tags` info to the file. + This will require re-creation of the database now, since decK will not + detect any of the entities present (as they are missing the common tag). diff --git a/app/deck/environment-variables.md b/app/deck/environment-variables.md new file mode 100644 index 00000000..af142c70 --- /dev/null +++ b/app/deck/environment-variables.md @@ -0,0 +1,69 @@ +--- +title: Using environment variables with decK + +content_type: reference +layout: reference + +works_on: + - on-prem + - konnect + +products: + - api-ops + +tools: + - deck +--- + +To manage any values in decK files with environment varaibles, you can create environment variables +with the `DECK_` prefix and reference them as `{%raw%}${{ env "DECK_*" }}{%endraw%}` in your state file. + +When you use decK to apply configurations to {{site.base_gateway}}, +decK reads data in plain text from a state file by default. To improve security, you +can also store sensitive information, for example `apiKey` or `client_secret`, in +environment variables. decK can then read data directly from the environment +variables and apply it. + +{:.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. + +Create an environment variable: + +```sh +export DECK_API_KEY={YOUR_API_KEY} +``` + +You can use now reference the environment variable in the relevant value in any state file. +For example, this snippet enables the Key Authentication plugin globally and creates +a consumer named `demo` with an API key. The API key is pulled from the `DECK_API_KEY` +environment variable instead of being exposed in the state file: + +```yaml +_format_version: "3.0" +consumers: +- keyauth_credentials: + - key: {%raw%}${{ env "DECK_API_KEY" }}{%endraw%} + username: demo + id: 36718320-e67d-4162-8b50-aa685e06c64c +plugins: +- config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + name: key-auth + protocols: + - grpc + - grpcs + - http + - https +``` diff --git a/app/deck/manage-deck-with-docker.md b/app/deck/manage-deck-with-docker.md new file mode 100644 index 00000000..9853692b --- /dev/null +++ b/app/deck/manage-deck-with-docker.md @@ -0,0 +1,92 @@ +--- +title: Manage decK with Docker + +content_type: reference +layout: reference + +tools: + - deck + +works_on: + - on-prem + - konnect + +tags: + - docker + +products: + - api-ops +--- + +If you used the [kong/deck](https://hub.docker.com/r/kong/deck) Docker image to +install decK, you can use the same Docker image to manage decK. + +Adjust `KONG_ADMIN_HOST` and the port `8001` in the following examples to the +host and port of your own {{site.base_gateway}} instance. + +## 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:8001 \ + --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: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: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:8001 \ + --headers kong-admin-token:KONG_ADMIN_TOKEN \ + gateway sync /deck/kong.yaml +``` +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 +``` diff --git a/app/deck/object-defaults.md b/app/deck/object-defaults.md new file mode 100644 index 00000000..20888aa8 --- /dev/null +++ b/app/deck/object-defaults.md @@ -0,0 +1,242 @@ +--- +title: Object defaults reference + +content_type: reference +layout: reference + +works_on: + - on-prem + - konnect + +products: + - api-ops + +tools: + - deck + +related_resources: + - text: Customize decK object defaults + url: /how-to/custom-deck-object-defaults +--- + +Kong Gateway sets some default values for most objects, including Kong +plugins. You can see what the defaults are for each object in the +[Admin API reference](/gateway/latest/admin-api/), or use the +[`/schemas`](#find-defaults-for-an-object) endpoint to +check the latest object schemas for your instance of the Kong Gateway. + +decK recognizes value defaults and doesn't interpret them as changes to +configuration. If you push a config for an object to Kong Gateway with +`sync`, Kong Gateway applies its default values to the object, +but a further `diff` or `sync` does not show any changes. + +If you upgrade Kong Gateway to a version that introduces a new +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. + +## Value order of precedence + +decK assigns values in the following order of precedence, from highest to lowest: + +1. Values set for a specific instance of an object in the state file +(for example, for a service named `example_service` defined in `kong.yml`). +2. Values set in the `{_info: defaults:}` object in the state file. +3. Self-managed {{site.base_gateway}} only: Values are checked against the Kong +Admin API schemas. +4. {{site.konnect_short_name}} Cloud only: Values are checked against the Kong Admin API for plugins, +and against hardcoded defaults for Service, Route, Upstream, and Target objects. + +## Find defaults for an object + +{{site.base_gateway}} defines all the defaults it applies in object schema files. +Check the schemas to find the most up-to-date default values for an object. + +If you want to completely avoid differences between the configuration file and +the {{site.base_gateway}}, set all possible default values for an object in your +`kong.yaml` file. + +{% navtabs %} +{% navtab "Route" %} + +Use the Kong Admin API `/schemas` endpoint to find default values: + +```sh +curl -i http://localhost:8001/schemas/routes +``` + +In your `kong.yaml` file, set the default values you want to use across all Routes. +For example: + +```yaml +_info: + defaults: + route: + https_redirect_status_code: 426 + path_handling: v0 + preserve_host: false + protocols: + - http + - https + regex_priority: 0 + request_buffering: true + response_buffering: true + strip_path: true +``` + +{:.note} +> **Note:** If the Route protocols include `grpc` and `grpcs`, the `strip_path` +schema value must be `false`. If set to `true`, deck returns a schema +violation error. + +For documentation on all available properties, see the +[Route object](/gateway/api/admin-ee/latest/#/Routes/list-route/) documentation. + +{% endnavtab %} +{% navtab "Service" %} + +Use the Kong Admin API `/schemas` endpoint to find default values: + +```sh +curl -i http://localhost:8001/schemas/services +``` + +In your `kong.yaml` file, set the default values you want to use across all +Services. For example: + +```yaml +_info: + defaults: + service: + port: 80 + protocol: http + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + retries: 5 +``` + +For documentation on all available properties, see the +[Service object](/gateway/api/admin-ee/latest/#/Services) documentation. + +{% endnavtab %} +{% navtab "Upstream" %} + +Use the Kong Admin API `/schemas` endpoint to find default values: + +```sh +curl -i http://localhost:8001/schemas/upstreams +``` + +In your `kong.yaml` file, set the default values you want to use across all +Upstreams. For example: + +```yaml +_info: + defaults: + upstream: + slots: 10000 + algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 +``` + +For documentation on all available properties, see the +[Upstream object](/gateway/api/admin-ee/latest/#/Upstreams/list-upstream/) documentation. + +{% endnavtab %} +{% navtab "Target" %} + +Use the Kong Admin API `/schemas` endpoint to find default values: + +```sh +curl -i http://localhost:8001/schemas/targets +``` + +In your `kong.yaml` file, set the default values you want to use across all +Targets. For example: + +```yaml +_info: + defaults: + target: + weight: 100 +``` +For all available properties, see the +[Target object](/gateway/api/admin-ee/latest/#/Targets/list-target-with-upstream/) documentation. + +{% endnavtab %} +{% navtab "Plugins" %} + +Use the Kong Admin API `/schemas` endpoint to find default values: + +```sh +curl -i http://localhost:8001/schemas/plugins/ +``` + +decK doesn't support setting custom default values for the plugin object. + +{% endnavtab %} +{% endnavtabs %}