deck file namespace

Uses: deck

When practicing federated configuration management, there is a high chance of endpoint collision where two teams unexpectedly use the same API path.

To avoid this, you can namespace each API using a path prefix or have each API listen on a specific host.

By default, the deck file namespace command operates on all Routes in a file. To target specific Routes, pass the --selector flag.

Path prefix

The simplest way to prevent collisions is to prefix each API Route with a static path. In this case, all Routes in /path/to/config will be exposed under a /billing path:

deck file namespace --path-prefix=/billing -s ./config.yaml

To remain transparent to the backend Services, the added path prefix must be removed from the path before the request is routed to the Service. To remove the prefix, the following approaches are used (in order):

  1. If the Route has strip_path=true, then the added prefix will already be stripped.
  2. If the related Service has a path property that matches the prefix, then the service.path property is updated to remove the prefix.
  3. A pre-function plugin will be added to remove the prefix from the path.

If a pre-function is used, this will take priority over any global pre-function plugin that you have configured.

Custom host

An alternate way to namespace APIs is to have each API listen on a different hostname, for example, http://service1.api.example.com/somepath, http://service2.api.example.com/somepath.

The following command updates all Route definitions in a file to listen only when a request is made to service1.api.example.com. If the Route already has a hosts entry, the new domain is appended to the list.

deck file namespace --host service1.api.example.com

If you need to ensure that the API only listens on the hostname provided, you can pass the --clear-hosts flag:

deck file namespace --host service1.api.example.com --clear-hosts

Command usage

Usage:
  deck file namespace [flags]

Examples:
# Apply namespace to a deckfile, path and host:
deck file namespace --path-prefix=/kong --host=konghq.com --state=deckfile.yaml

# Apply namespace to a deckfile, and write to a new file
# Example file 'kong.yaml':
routes:
- paths:
  - ~/tracks/system$
  strip_path: true
- paths:
  - ~/list$
  strip_path: false

# Apply namespace to the deckfile, and write to stdout:
cat kong.yaml | deck file namespace --path-prefix=/kong

# Output:
routes:
- paths:
  - ~/kong/tracks/system$
  strip_path: true
  hosts:
  - konghq.com
- paths:
  - ~/kong/list$
  strip_path: false
  hosts:
  - konghq.com
  plugins:
  - name: pre-function
    config:
      access:
      - "local ns='/kong' -- this strips the '/kong' namespace from the path\nlocal <more code here>"



Flags:
      --allow-empty-selectors   Do not error out if the selectors return empty
  -c, --clear-hosts             Clear existing hosts.
      --format string           Output format: yaml or json. (default "yaml")
  -h, --help                    help for namespace
      --host stringArray        Hostname to add for host-based namespacing. Repeat for multiple hosts.
  -o, --output-file string      Output file to write. Use - to write to stdout. (default "-")
  -p, --path-prefix string      The path based namespace to apply.
      --selector stringArray    json-pointer identifying element to patch. Repeat for multiple selectors. Defaults to selecting all routes.
  -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!