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

PATCH behavior

When using PATCH method like in AIP-134 the following rules are applied:

• absent entries are untouched
• if an entry has a null value it must be deleted
• new entries are added
• deleting an missing entry does not fail

Some examples exist in AIP-134

Public labels

Similar to labels, public labels are key:value pairs which are case sensitive attributes associated with entities. However, in contrast to labels, public label attributes are meant to be non-internal, non-sensitive information that may be exposed outside of a Konnect organization.

Public labels are also similar to labels in that they can be used for filtering an entity list or for searching across entity types.

Guidance

APIs with entities that can be publicized outside of Konnect may provide public labels for attributes that may be made available in contexts outside of a Konnect organization.

Field Naming

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

{
  "id": "03d14397-a7cc-4313-9966-aaa6722f9c1c",
  "name": "Example API",
  "labels": {
    "team": "identity"
  },
  "public_labels": {
    "collection": "accounts",
    "contact": "support@konghq.com",
    "company": "Kong, Inc."
  },
}

Validation and behavior

Public labels must follow the same validation and PATCH behavior as (internal) labels.