--- title: Using kongctl to manage AI Gateway description: Learn how to use kongctl to create and inspect AI Gateway resources in Kong Konnect. url: "/ai-gateway/kongctl/" canonical_url: "/ai-gateway/kongctl/" content_type: reference min_version: ai-gateway: '2.0' products: - AI Gateway tools: - kongctl tags: - declarative-config - cli canonical: true works_on: - konnect --- # Using kongctl to manage AI Gateway kongctl is the CLI for managing [AI Gateway resources](/ai-gateway/entities/) in Kong Konnect. It supports two modes of operation: declarative configuration for managing resources as code, and imperative commands for one-off operations and inspection. > **Note**: > kongctl manages AI Gateway on Kong Konnect. > decK manages Kong Gateway entities (Services, Routes, Plugins, and so on) on self-managed deployments. > If you're coming from AI Gateway 1.x, which used decK and Gateway plugins, see the [v2 migration guide](/ai-gateway/v2-migration-guide/) for how to move to the kongctl-managed entity model. AI Gateway resources are regional. Make sure your active kongctl profile's `konnect.region` matches the region where your AI Gateway lives (`us`, `eu`, `au`, `me`, `in`, or `sg`). See [Configuration of kongctl](/kongctl/config/) for how to set this. ## Declarative configuration 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](/how-to/?products=ai-gateway) use this approach. ### Workflow 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](/kongctl/sync/) for more detail on sync behavior. For example, this configuration file creates an AI Gateway: ```yaml _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: ```bash kongctl diff --mode apply -f ai-gateway.yaml --pat "$KONNECT_TOKEN" ``` Then apply, confirming the changes if you approve: ```bash kongctl apply -f ai-gateway.yaml --pat "$KONNECT_TOKEN" ``` For a step-by-step guide, see [Get started with AI Gateway](/ai-gateway/get-started/), which walks through creating an AI Provider and AI Model using `kongctl apply`. For the full declarative configuration reference, see [Declarative configuration with kongctl](/kongctl/declarative/). ### Resource schemas To look up field names and required fields for any resource type, use `kongctl explain`: ```bash kongctl explain ai_gateway_model_providers ``` Use `kongctl scaffold` to generate starter YAML for a resource type: ```bash kongctl scaffold ai_gateway_model_providers ``` See the [kongctl declarative resource reference](/kongctl/supported-resources/#ai-gateway) for all supported resource types. ### Adopting an existing AI Gateway 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`](/kongctl/adopt/) to bring it into a namespace before managing it declaratively: ```sh 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: ```bash 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`. ### Referencing external resources 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: ```yaml 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: ```yaml 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`. ### Commands reference These are the commands you'll use most often in a declarative workflow: ### [`adopt`](/kongctl/adopt/) Description: 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. When to use: Use before your first `dump` or `plan`, when you need to bring a manually created or UI-created resource into your configuration. ### [`dump`](/kongctl/dump/) Description: Exports the current state of Konnect resources to a declarative YAML configuration file. When to use: Use when bootstrapping a new declarative configuration from existing live resources, or when generating a starting point for a new configuration file. ### [`plan`](/kongctl/plan/) Description: Compares your local configuration files against live Konnect state and generates a JSON plan artifact describing the changes to be made. When to use: Use before applying changes, especially in CI/CD pipelines, to produce a reviewable and reusable plan artifact. ### [`diff`](/kongctl/diff/) Description: 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. When to use: Use during development to inspect what `apply` or `sync` would change before committing. ### [`apply`](/kongctl/apply/) Description: Creates and updates resources to match the desired state. Does not delete resources. When to use: Use to incrementally apply configuration without risk of deleting anything. Use `sync` instead when you want deletes as well. ### [`sync`](/kongctl/sync/) Description: Applies the full desired state from your configuration files. Creates, updates, and deletes resources. When to use: Use for full reconciliation between your configuration and live state, including deletions. Use `apply` if you only want creates and updates. ### [`delete`](/kongctl/delete/) Description: Plans and executes deletion of all resources defined in the input configuration files. When to use: 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`](/kongctl/get/) Description: Retrieves Konnect resources. When to use: Use to inspect live state after applying configuration, or to look up resource IDs and names. ## Imperative commands For inspection and one-off operations, use [`kongctl get`](/kongctl/get/), [`kongctl create`](/kongctl/create/), and [`kongctl delete`](/kongctl/delete/) directly. These commands don't require a configuration file and take effect immediately without going through a plan. List all AI Gateway instances in your organization: ```sh kongctl get ai-gateways ``` List resources scoped to a specific AI Gateway, for example: ```sh kongctl get ai-gateway model-providers --gateway-name "my-ai-gateway" kongctl get ai-gateway models --gateway-name "my-ai-gateway" kongctl get ai-gateway policies --gateway-name "my-ai-gateway" kongctl get ai-gateway consumers --gateway-name "my-ai-gateway" kongctl get ai-gateway mcp-servers --gateway-name "my-ai-gateway" ``` Pass `--help` to any subcommand to see available flags and filtering options. For example, passing it to `kongctl get ai-gateway` will give you a list of all AI Gateway resources kongctl can manage: ```sh kongctl get ai-gateway --help ``` ## Related Resources - [Get started with AI Gateway](/ai-gateway/get-started/) - [Declarative configuration with kongctl](/kongctl/declarative/) - [kongctl and decK](/kongctl/kongctl-and-deck/) - [AI Gateway v2 migration guide](/ai-gateway/v2-migration-guide/) - [kongctl supported resources](/kongctl/supported-resources/) - [Configuration of kongctl](/kongctl/config/) ## Next Steps - [Get started with AI Gateway](/ai-gateway/get-started/)