Declarative Configuration

Resource Identity

Goal

You will understand how ref identifies resources inside declarative configuration and connects related resources.

Local and remote identities

A resource can have several identifiers:

Identifier Meaning
ref kongctl local identifier, never sent to Konnect. Must be unique across the entire set of declarative input files per command.
id Common Konnect UUID field used to identify resources in URL routes, for example ai-gateways/<id>/models.
name Common Konnect field with resource-specific uniqueness rules. Not all Konnect resources have a name, and not all name fields have uniqueness constraints.

Every declarative resource requires a unique ref identifier:

ai_gateways:
  - ref: my-aigw
    name: my-aigw
    display_name: My AI Gateway

Cross-resource references with ref

The ref field lets resources relate to each other within a configuration.

The !ref YAML tag reads a field from another declared resource. This relationship targets the Konnect ID that will belong to my-aigw:

ai_gateway_models:
  - ref: chat-model
    ai_gateway: !ref my-aigw#id

kongctl uses these references to order dependent operations and establish relationships within Konnect.