In declarative mode, you describe the desired state of your resources in declarative configuration files and kongctl calculates and applies the diff.
This is the recommended approach for most AI Gateway configuration because it lets you store configuration in source control and apply it safely at any time.
The AI Gateway how-to guides use this approach.
Use the following workflow to manage AI Gateway resources declaratively:
- Write a configuration file describing the resources you want.
- Run
kongctl plan -f example.yaml to preview what will change (optional but recommended).
- Run
kongctl apply -f example.yaml to create or update resources.
- Run
kongctl sync -f example.yaml when you want kongctl to also create, update, or delete resources.
See the kongctl sync reference for more detail on sync behavior.
For example, this configuration file creates an AI Gateway:
_defaults:
kongctl:
namespace: my-namespace
ai_gateways:
- ref: my-ai-gateway
name: my-ai-gateway
Save this as ai-gateway.yaml, then preview what will change:
kongctl diff --mode apply -f ai-gateway.yaml --pat "$KONNECT_TOKEN"
Then apply, confirming the changes if you approve:
kongctl apply -f ai-gateway.yaml --pat "$KONNECT_TOKEN"
For a step-by-step guide, see Get started with AI Gateway, which walks through creating an AI Provider and AI Model using kongctl apply.
For the full declarative configuration reference, see Declarative configuration with kongctl.
To look up field names and required fields for any resource type, use kongctl explain:
kongctl explain ai_gateway_model_providers
Use kongctl scaffold to generate starter YAML for a resource type:
kongctl scaffold ai_gateway_model_providers
See the kongctl declarative resource reference for all supported resource types.
If you create an AI Gateway using declarative configuration, kongctl tracks it in the namespace automatically.
If an AI Gateway already exists in Kong Konnect (for example, one provisioned outside of kongctl), use kongctl adopt to bring it into a namespace before managing it declaratively:
kongctl adopt ai-gateway "$AI_GATEWAY_ID" \
--namespace my-namespace \
--pat "$KONNECT_TOKEN"
adopt registers the existing AI Gateway with a kongctl namespace so it can be tracked.
Pre-existing resources need to be adopted before kongctl includes them in plan and sync operations.
After adopting, run kongctl dump declarative to export the current configuration as a YAML file you can use as the starting point for declarative management:
kongctl dump declarative \
--default-namespace my-namespace \
--resources ai_gateways,ai_gateway_models,ai_gateway_model_providers \
--pat "$KONNECT_TOKEN" > ai-gateway.yaml
From here you can edit ai-gateway.yaml, commit it to source control, and manage the resource going forward with commands like kongctl apply or kongctl sync.
When a resource already exists in Kong Konnect but isn’t managed by your current configuration file, you can reference it without taking ownership.
kongctl provides two ways to do this: _external and !lookup.
- Use
_external when multiple child resources in the same file share the same parent, so you only need to write the lookup once and reference it by ref.
- Use
!lookup when you only need the parent’s ID in a single field and want to keep the config concise.
_external declares the resource as a named block with a ref you can reuse multiple times in the same file:
ai_gateways:
- ref: my-ai-gateway
_external:
selector:
matchFields:
name: "my-ai-gateway"
ai_gateway_model_providers:
- ref: openai-primary
ai_gateway: my-ai-gateway
name: openai-primary
type: openai
config:
auth:
type: basic
headers:
- name: Authorization
value: !secret {source: !env OPENAI_API_KEY}
!lookup is a concise inline tag that performs the same lookup directly in a field value:
ai_gateway_model_providers:
- ref: openai-primary
ai_gateway: !lookup name:my-ai-gateway
name: openai-primary
type: openai
config:
auth:
type: basic
headers:
- name: Authorization
value: !secret {source: !env OPENAI_API_KEY}
In both situations, kongctl resolves the external resource’s ID at plan time and uses it to scope the child resources.
The external resource itself is not modified or deleted by sync.
These are the commands you’ll use most often in a declarative workflow:
|
Command
|
Description
|
When to use
|
adopt
|
Adds a namespace label to an existing Konnect resource that was created outside of kongctl, bringing it under declarative management without modifying any other fields.
|
Use before your first dump or plan, when you need to bring a manually created or UI-created resource into your configuration.
|
dump
|
Exports the current state of Konnect resources to a declarative YAML configuration file.
|
Use when bootstrapping a new declarative configuration from existing live resources, or when generating a starting point for a new configuration file.
|
plan
|
Compares your local configuration files against live Konnect state and generates a JSON plan artifact describing the changes to be made.
|
Use before applying changes, especially in CI/CD pipelines, to produce a reviewable and reusable plan artifact.
|
diff
|
Displays a human-readable preview of the changes between the current live state and the desired state in your configuration files, or from a saved plan artifact.
|
Use during development to inspect what apply or sync would change before committing.
|
apply
|
Creates and updates resources to match the desired state. Does not delete resources.
|
Use to incrementally apply configuration without risk of deleting anything. Use sync instead when you want deletes as well.
|
sync
|
Applies the full desired state from your configuration files. Creates, updates, and deletes resources.
|
Use for full reconciliation between your configuration and live state, including deletions. Use apply if you only want creates and updates.
|
delete
|
Plans and executes deletion of all resources defined in the input configuration files.
|
Use for tearing down a known set of resources, such as resetting a test environment. Not a typical step in the day-to-day declarative workflow.
|
get
|
Retrieves Konnect resources.
|
Use to inspect live state after applying configuration, or to look up resource IDs and names.
|