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.
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):
strip_path=true, then the added prefix will already be stripped.path property that matches the prefix, then the service.path property is updated to remove the prefix.pre-function plugin will be added to remove the prefix from the path.If a
pre-functionis used, this will take priority over any globalpre-functionplugin that you have configured.
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
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 "-")