Managing plugins with decK

Uses: deck

Adding or managing plugins is a common use case for platform teams. The deck file command allows you to add or update a plugin configuration programmatically.

If the plugin being added already exists, the add-plugin command won’t edit the plugin unless the --overwrite flag is provided, or overwrite: true is specified in the plugin configuration file.

The deck file add-plugins command outputs the patched file to stdout by default. You can provide a path to a file using -o ./config.yaml to write the updated configuration to a file on disk.

Add a new plugin

You can run the following examples using deck file add-plugins -s ./kong.yaml plugin1.yaml.

Multiple plugin definition files can be passed to the command e.g. deck file add-plugins -s ./kong.yaml plugin1.yaml plugin1.yaml.

# plugin.yaml
add-plugins:
  - selectors:
      - $..services[*]
    overwrite: false
    plugins:
      - name: request-termination
        config:
          status_code: 403
          message: Scheduled maintenance in progress

Update specific configuration values

The deck file add-plugins command configures a complete set of plugin configuration. To edit specific values, you can use the deck file patch command.

To update the request-termination plugin above to return a different message:

patches:
  - selectors:
      - $.services[*].plugins[?(@.name=='request-termination')].config
    values:
      message: "Installing new bits and bytes"

For more information, see the deck file patch documentation.

Command usage

Usage:
  deck file add-plugins [flags] [...plugin-files]

Examples:
# adds a plugin to all services in a deck file, except if it is already present
cat kong.yml | deck file add-plugins --selector='services[*]' \
               --config='{"name":"my-plugin","config":{"my-property":"value"}}'

# same, but now overwriting plugins if they already exist and reading from files
cat kong.yml | deck file add-plugins --overwrite plugin1.json plugin2.yml

Flags:
      --config stringArray     JSON snippet containing the plugin configuration to add. Repeat to add
                               multiple plugins.
      --format string          Output format: json or yaml (default "yaml")
  -h, --help                   help for add-plugins
  -o, --output-file string     Output file to write to. Use - to write to stdout. (default "-")
      --overwrite              Specify this flag to overwrite plugins by the same name if they already
                               exist in an array. The default behavior is to skip existing plugins.
      --selector stringArray   JSON path expression to select plugin-owning objects to add plugins to.
                               Defaults to the top-level (selector '$'). Repeat for multiple selectors.
  -s, --state string           decK file to process. Use - to read from stdin. (default "-")

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!