Labels (#129)

Labels are key:value pairs which are case sensitive attributes associated with entities. Labels allow an organization to specify metadata on an entity that can be used for filtering an entity list or for searching across entity types. Note: search across entity types will be addressed in a future AIP.

This AIP is heavily influenced by the Kubernetes labels system which our audience is expected to be familiar with. Some of the design decisions are taken from k8s to stick to the principle of least astonishment.

User metadata has previously been implemented using tags. This approach is no longer recommended at Kong.

Guidance

APIs must provide labeling metadata on all entities present in Konnect.

• New entities introduced in Konnect must support labeling.
  • "Addressable entities" must support labels. (eg: /books/123)
  • "Singleton resources" should not support labels. (eg: /config)
  • "Relationships" do not require labels. (eg: memberships and associations)
• Existing entities in Konnect must retroactively add labeling by a product defined date.
• Labeling on Core Gateway entities is currently not defined or required.
• List endpoints must support filtering by labels in accordance with the filtering AIP.

Field Naming

When labels are supported, labels should be present in the labels field on an entity. labels is an object, and must return an empty object ({}) when no labels are set.

A previous version of this AIP placed labels in the metadata.labels field. This pattern is now deprecated and should be removed in the next major version of any APIs that implement metadata.labels

{
  "id": "10sjf30rf3",
  "name": "Example service",
  "labels": {
    "environment": "production",
    "release": "beta",
    "team": "mobile"
  }
}

Validation

1. A maximum of 50 user-defined labels are allowed on each resource.
2. Keys must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.
3. Keys must not start with kong, konnect, insomnia, mesh, kic or _, which are reserved for Kong
4. Values must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.
5. Values must not be empty
6. Keys are case-sensitive

Backwards compatibility

Tools that have interfaces designed around tags can also be used with labels. To filter using labels, concatenate the key and value with a : character e.g. environment:production