Tags

Uses: Kong Gateway decK

What is a tag?

Tags are strings that provide a way to associate metadata with entities in Kong Gateway. You can apply tags to an entity when creating or editing it, and you can filter entities by tags when using the list (GET) endpoints of the Kong Admin API.

Most Kong Gateway entities can be tagged via their tags attribute. Check the schema of the entity you’re interested in to find out if it supports tagging.

Tag requirements

Tags can contain almost all UTF-8 characters, with the following exceptions:

, and / are reserved for filtering tags with AND and OR, so they are not allowed in tags.
Non-printable ASCII (for example, the space character) is not allowed.

Add tags to an entity

The following example shows how you would tag a Gateway Service, however most Kong Gateway entities can be tagged in the same way:

echo '
_format_version: "3.0"
services:
  - name: example_service
    url: https://httpbin.konghq.com
    tags:
    - example
    - test
' | deck gateway apply -

Filtering entities using tags

You can use tags to filter most entities via the ?tags querystring parameter.

Filtering requirements and considerations:

A maximum of 5 tags can be queried simultaneously in a single request with the , (AND) or / (OR) operators.
Mixing operators is not supported. If you try to mix , with / in the same querystring, you will receive an error.
You may need to quote or escape some characters when using them from the command line.
Filtering by tags is not supported in foreign key relationship endpoints. For example, the tags parameter will be ignored in a request such as GET /services/foo/routes?tags=a,b.
offset parameters are not guaranteed to work if the tags parameter is altered or removed.

Filtering examples

The following examples show how you would filter Gateway Services based on the tags example and admin:

Use case	Example
Get the list of all Services tagged `example` by passing the `example` tag as a querystring parameter	`GET /services?tags=example`
Filter Services with the AND (`,`) delimiter to get all entities that match multiple tags	`GET /services?tags=example,admin`
Filter Services with the OR (`/`) delimiter to get entities that only match one of the specified tags	`GET /services?tags=example/admin`