Sync Scope

Goal

You will understand how YAML key presence, namespaces, and parent identity define what a sync-mode plan can delete.

Scope makes sync safe

Unlike apply mode, sync mode can delete managed resources that are missing from the desired state. kongctl limits that behavior to collections explicitly present in the input.

An omitted collection and an empty collection are intentionally different.

Give zero resources a namespace

An empty collection has no resource entry carrying kongctl metadata. Use _defaults to identify the namespace where the desired count is zero:

_defaults:
  kongctl:
    namespace: aigw-learning

ai_gateways: []

In sync mode, this configuration plans deletion of every managed AI Gateway in the aigw-learning namespace. AI Gateways in other namespaces are outside the plan’s scope. Without an explicit namespace, the default namespace is used.

Give an empty child its parent identity

Parent and child collections have separate sync scope. Omitting models leaves existing models alone:

ai_gateways:
  - ref: my-aigw
    name: my-aigw

An explicit empty list declares that this AI Gateway should have no models:

ai_gateways:
  - ref: my-aigw
    name: my-aigw
    models: []

IMPORTANT: The empty child list must be nested so kongctl knows which AI Gateway owns the collection. A root-level ai_gateway_models: [] is rejected because no model entry provides an ai_gateway parent identity.

Preview desired zero

Create a separate sync input for the learning namespace:

cat > empty-ai-gateways.yaml <<'YAML'
_defaults:
  kongctl:
    namespace: aigw-learning

ai_gateways: []
YAML

Generate and inspect a sync-mode plan:

kongctl plan \
  --mode sync \
  -f empty-ai-gateways.yaml \
  --output-file sync-plan.json
kongctl diff --plan sync-plan.json

If the namespace still contains managed AI Gateways, the plan includes their deletion. If you completed the Working Example first, it reports no changes because that lesson already removed its resources. Creating and inspecting the plan does not change Konnect.