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
Copied to clipboard!

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"
Copied to clipboard!

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 "-")

Copied to clipboard!

Did this doc help?

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!