Skip to content

declarative-resource-reference.md

Latest commit

 

History

History
1619 lines (1465 loc) · 59.5 KB

declarative-resource-reference.md

File metadata and controls

1619 lines (1465 loc) · 59.5 KB
Raw

kongctl Declarative Resource Reference

This document is a reference for kongctl declarative configuration. It lists supported resource types and common field-level values. Resource configurations are provided as YAML files and can be expressed as one or more files passed to kongctl declarative commands.

The definitive schema for the version of kongctl you are using is generated by the CLI itself:

kongctl explain api
kongctl explain portal.identity_providers --output yaml
kongctl scaffold api

Use kongctl explain to confirm accepted field names, required fields, preferred YAML tags, root keys, and nested or root declaration support. Use kongctl scaffold to generate starter YAML for a resource path. If this page differs from the installed CLI, follow the CLI output.

See the declarative configuration guide for information on the feature, commands, and options.

File-level defaults (_defaults)

Use _defaults.kongctl to apply default namespace and protected metadata to parent resources in this file. Resource-level kongctl values override these defaults.

_defaults:
  kongctl:
    namespace: platform-team
    protected: false

Configuration templates (_templates and _extends)

Define reusable configuration blocks under the top-level _templates key and select one from a resource or nested configuration block with _extends:

_templates:
  private-portal:
    authentication_enabled: true
    default_api_visibility: private

portals:
  - _extends: private-portal
    ref: developer-portal
    name: Developer Portal

Templates are shared across all sources loaded by one command. Consumer configuration blocks recursively override inherited configuration blocks; scalars, sequences, explicit null, and values of a different type replace the inherited value. Sequences never append. See Configuration Templates for inheritance, discovery, merge, tag, and sync-scope behavior.

YAML Tags

Use YAML tags in field values to load files or reference other resources.

  • !file: Load content from a file. Supports path#extract.path and path/extract map form.
  • !env: Load string content from an environment variable. Supports VAR#extract.path and var/extract map form.
  • !secret: Declare a sensitive deferred value on a reviewed write-only field. Supports source: !env VAR, source: !file ./path, and ordered parts containing strings and deferred !env or !file sources.
  • !ref: Reference another declarative resource by ref. resource-ref#field is supported; the default field is id.
  • !lookup: Resolve an existing Konnect resource directly in a relationship field. Supports field:value and flat mapping forms.
  • !external: An exact alias for !lookup; both use the same planner-time resolver and cache.
  • !ref is intended for string fields.
  • string (uuid) and array[string(uuid)] annotations in this document describe API value types. In declarative config, prefer !ref and avoid literal UUID values.
  • For a one-off unmanaged relationship, use !lookup. Use an _external declaration plus !ref when the resource needs a reusable declarative ref or owns managed child resources.
  • Sync never changes or deletes an external parent. Its child collections placed in sync scope are still fully reconciled, including stale child deletion. Omitted child collections remain out of scope.
  • Large text/spec fields are commonly loaded with !file.
  • !file paths are resolved relative to the config file and must remain within the configured base directory boundary.

Nested tag composition is opt-in. !env can supply a direct mapping selector value inside !lookup or !external. Both !env and !file can supply deferred source values inside !secret:

portal_id: !lookup
  name: !env PORTAL_NAME

control_plane: !lookup {name: !env CONTROL_PLANE_NAME}

key: !secret {source: !file ./certs/runtime.key}
Outer tag Supported inner tags
!lookup / !external !env in direct mapping values
!secret !env or !file as source or a parts element
!env, !file, !ref None

!file, !ref, and nested lookup tags are not supported inside lookup tags. A deferred !file source is supported only within !secret; a bare !file on a reviewed write-only field is rejected. Tags are not supported in mapping keys or control fields such as var, extract, and path. Use mapping lookup syntax for composition; tags cannot be interpolated into the scalar field:value form.

Nested environment values are used only for planner-time lookup and are redacted from diagnostics. A saved plan contains the resolved ID, so execution does not reread the variable or repeat the lookup. This differs from ordinary !env fields, which remain deferred until execution.

portals:
  - ref: docs-portal
    _external:
      selector:
        matchFields:
          name: "Docs Portal"

apis:
  - ref: billing-api
    publications:
      - ref: billing-publication
        portal_id: !ref docs-portal

The target resource type is inferred from the field. Scalar values use field:value syntax and mapping selectors use AND semantics:

portal_id: !lookup {name: Docs Portal}
ai_gateway: !lookup {name: shared-ai-gateway}

API-native foreign keys such as portal_id and kongctl-added root parent selectors such as ai_gateway retain their established names. They share the same relationship resolution behavior. Parent selectors are omitted when the child is nested and the parent can be inferred.

Inline lookup targets are the resource types that support _external: Catalog APIs, application auth strategies, portals, control planes, gateway services, AI gateways, audit-log webhook destinations, organization teams, Event Gateway control planes, and Event Gateway virtual clusters. Run kongctl explain to see selectors and scope requirements for a specific field.

Audit Logs

Audit-log webhook destinations are organization-scoped Konnect resources. Declarative config supports them as external references so managed portal audit-log webhooks can point at destinations created elsewhere.

audit-logs:
  destinations:
    - ref: string
      _external:
        id: string # destination UUID, or use selector
        selector:
          matchFields:
            name: string

Only _external.id and _external.selector.matchFields.name are supported. Audit-log webhook destinations cannot declare kongctl metadata and are not created, updated, or deleted by declarative apply.

APIs

API Specification Example

apis:
  - ref: string
    name: string required (1-255 chars)
    _external: # alternative to managed API fields
      id: string # API UUID, or use selector.matchFields.name
    description: string (nullable)
    version: string (1-255 chars, nullable)
    slug: string (pattern: ^[\w-]+$, nullable)
    labels: object [string]string
      key: value
    attributes: object [string]array[string]
      key:
        - value
    versions: # https://developer.konghq.com/api/konnect/api-builder/v3/#/operations/create-api-version
      - ref: string
        version: string
        spec: !file ./specs/api.yaml # required (OpenAPI or AsyncAPI content; json or yaml)
    publications: # https://developer.konghq.com/api/konnect/api-builder/v3/#/operations/publish-api-to-portal
      - ref: string
        portal_id: string required (uuid) # prefer: !ref <portal-ref>
        auto_approve_registrations: boolean
        auth_strategy_ids: array[string(uuid)] (nullable, max 1 item) # prefer: !ref values
        visibility: One of (public | private)
    implementations: # https://developer.konghq.com/api/konnect/api-builder/v3/#/operations/create-api-implementation
      - ref: string
        type: service # optional when the service payload is present
        service:
          id: string required (uuid) # prefer: !ref <gateway-service-ref>
          control_plane_id: string required (uuid) # prefer: !ref <control-plane-ref>
      - ref: string
        type: control_plane # optional when the control_plane payload is present
        control_plane:
          # prefer: !ref <control-plane-ref>
          control_plane_id: string required (uuid)
    documents: # https://developer.konghq.com/api/konnect/api-builder/v3/#/operations/create-api-document
      - ref: string
        content: string required (markdown) # prefer: !file ./docs/page.md
        title: string
        slug: string (pattern: ^[\w-]+$)
        status: One of (published | unpublished)
        parent_document_id: string (uuid, nullable) # prefer: !ref <document-ref>
        children:
          - ref: string
            content: string required (markdown) # prefer: !file ./docs/page.md
            title: string
            slug: string (pattern: ^[\w-]+$)
            status: One of (published | unpublished)

API specifications must be declared on API versions with versions[].spec or root-level api_versions[].spec; apis[].spec_content is not supported in declarative configuration.

An external API can own managed versions, publications, implementations, and documents in the same manifest. kongctl resolves the API identity and plans only its declared children; it never creates, updates, or deletes the API. Root-level API children can use api: !lookup name:Shared API as the anonymous equivalent.

Each API implementation must define exactly one of service or control_plane. When type is present, it must match the selected payload.

Application Auth Strategies

API Specification Example

application_auth_strategies:
 - ref: string
   _external: # alternative to managed strategy fields
     id: string # strategy UUID, or use selector by name/display_name

External application auth strategies are identity-only declarations. They can be referenced from portals[].default_application_auth_strategy_id and apis[].publications[].auth_strategy_ids. For a one-off relationship, use !lookup, for example:

auth_strategy_ids:
  - !lookup name:Shared Auth

Managed application auth strategies use the following fields:

application_auth_strategies:
 - ref: string
   name: string required
   display_name: string required
   strategy_type: One of (key_auth | openid_connect) required
   configs: object required
     key-auth: # if strategy_type: key_auth
       key_names: array[string] required (1-10 items)
       ttl: object
         value: integer required (minimum: 1)
         unit: One of (days | weeks | years) required
     openid-connect: # if strategy_type: openid_connect
       issuer: string (url, max 256 chars) required
       credential_claim: array[string] required (max 10 items)
       scopes: array[string] required (max 50 items)
       auth_methods: array[string] required (max 10 items)
   dcr_provider_id: string (uuid, nullable; openid_connect only) # prefer: !ref <dcr-provider-ref>
   labels: object [string]string
     key: value

DCR Providers

API Specification

dcr_providers:
 - ref: string
   name: string required
   display_name: string
   provider_type: One of (auth0 | azureAd | curity | okta | http) required
   issuer: string (url, max 256 chars) required
   dcr_config: object required
   labels: object [string]string
     key: value

Catalog Services

API Specification Example

catalog_services:
 - ref: string
   name: string required (1-120 chars, pattern: ^[0-9a-z.-]+$)
   display_name: string required (1-120 chars)
   description: string (max 2048 chars)
   labels: object [string]string
     key: value
   custom_fields: object
     key: value

Dashboards

Custom Dashboards Example

Dashboard names do not need to be unique in Konnect, but kongctl follows the same resource matching pattern used elsewhere in declarative configuration. When planning against live state, it considers dashboards with the matching KONGCTL-namespace label and matches the desired dashboard by name. Avoid duplicate dashboard names within a kongctl namespace.

Dashboard resources are declared under the analytics grouping key.

For dashboards created in the Konnect UI, first run kongctl adopt analytics dashboard with the dashboard ID to apply the namespace label, then run kongctl dump declarative with --resources=analytics.dashboards and --default-namespace <name> to generate declarative configuration. Name-based adoption fails if the name matches multiple dashboards.

Use the dashboard definition JSON exported from Konnect as the definition value. The field accepts that API-shaped object either inline or loaded from a JSON/YAML file with !file; kongctl sends the parsed object as the dashboard definition without translating it to another schema. !file is preferred for larger dashboard definitions.

analytics:
  dashboards:
    - ref: string
      name: string required
      definition: object required # prefer: !file ./definitions/dashboard.json
        tiles: array[object] required
        preset_filters: array[object]
      labels: object [string]string
        key: value

When the exported JSON includes the full API response, use #definition to extract the payload expected by the dashboard API:

analytics:
  dashboards:
    - ref: traffic-summary
      name: Traffic Summary
      definition: !file ./exports/traffic-summary.json#definition

Control Planes

API Specification Example

control_planes:
 - ref: string
   name: string required
   description: string
   cluster_type: >-
     One of (CLUSTER_TYPE_CONTROL_PLANE |
     CLUSTER_TYPE_K8S_INGRESS_CONTROLLER |
     CLUSTER_TYPE_CONTROL_PLANE_GROUP |
     CLUSTER_TYPE_SERVERLESS |
     CLUSTER_TYPE_SERVERLESS_V1)
   auth_type: One of (pinned_client_certs | pki_client_certs)
   cloud_gateway: boolean
   proxy_urls: array[object]
     - host: string required
       port: integer required
       protocol: string required
   labels: object [string]string
     key: value
   _deck:
     files: array[string]
     flags: array[string]
   _external:
     selector:
       matchFields:
         name: string
     requires:
       deck: boolean
   gateway_services:
     - ref: string
       # _external only, Kong Gateway resources are managed by deck
       _external:
         selector:
           matchFields:
             name: string
   # API: create-dataplane-certificate
   data_plane_certificates:
     - ref: string
       cert: string required # prefer: !file ./certs/data-plane.pem

Control plane data plane certificates can also be declared as root resources. The certificate contents identify a certificate within its control plane when a certificate ID is not available. The cert field supports !file and !env.

control_plane_data_plane_certificates:
 - ref: string
   control_plane: string required # control plane ref
   cert: string required # prefer: !file ./certs/data-plane.pem

AI Gateways

This section covers the root AI Gateway resource backed by the Konnect /v1/ai-gateways API, AI Gateway Model Providers, AI Gateway Models, AI Gateway Auth Strategies, AI Gateway MCP Servers, AI Gateway Agents, AI Gateway Consumers, AI Gateway Consumer Credentials, AI Gateway Consumer Groups, AI Gateway Config Stores, AI Gateway Config Store Secrets, AI Gateway Vaults, AI Gateway Data Plane Certificates, runtime Certificates, CA Certificates, and SNIs. Use kongctl explain ai_gateway --output yaml, kongctl explain ai_gateway_model_provider --output yaml, kongctl explain ai_gateway_auth_strategy --output yaml, kongctl explain ai_gateway.agents --output yaml, kongctl explain ai_gateway.consumers --output yaml, kongctl explain ai_gateway.consumers.credentials --output yaml, kongctl explain ai_gateway.consumer_groups --output yaml, kongctl explain ai_gateway.models --output yaml, kongctl explain ai_gateway.mcp_servers --output yaml, kongctl explain ai_gateway.config_stores --output yaml, kongctl explain ai_gateway.config_stores.secrets --output yaml, kongctl explain ai_gateway.vaults --output yaml, and kongctl explain ai_gateway.data_plane_certificates --output yaml, kongctl explain ai_gateway.certificates --output yaml, kongctl explain ai_gateway.ca_certificates --output yaml, and kongctl explain ai_gateway.snis --output yaml as the authoritative schemas.

The ref value is a local declarative identifier used by kongctl for references and planning. Use name as the stable Konnect API name for the AI Gateway. Managed AI Gateways match only by name within their namespace; neither ref, UUID refs, nor display_name provide a fallback match. Changing name declares a different gateway. In sync mode, the previous gateway is eligible for deletion if it is no longer declared in the selected scope. Managed AI Gateways require an explicit name; kongctl does not derive it from ref. Use display_name for the human-readable name shown in Konnect. AI Gateway Model Providers, Auth Strategies, Policies, Agents, Consumers, Consumer Credentials, Consumer Groups, Models, MCP Servers, Config Stores, and Vaults use their required name field as the stable Konnect child name. Every managed declaration must supply name, including nested children; omitting it or setting it to an empty string fails validation even when ref is present. This applies to all model, MCP server, and vault variants. These resources match only by name within their parent gateway, except Consumer Credentials, which match within their parent consumer. UUID refs and cached IDs do not override the declared name or retain a differently named resource during sync. Config Store names are immutable after creation. AI Gateway Data Plane Certificates use their required title field as the stable Konnect child name and match only by title within their gateway. UUID refs and cached IDs do not override the declared title. A changed title declares a different certificate and sync can delete the previous one. Child entries inherit management scope from their parent resource and do not accept kongctl metadata.

When upgrading configurations that relied on UUID refs or display-name matching, explicitly set each gateway and name-bearing child's name to its existing API name before applying or syncing. A local ref can remain unchanged. Review the plan for unexpected CREATE or DELETE actions before executing it.

Changing a name declares a different resource, rather than renaming the existing one. Sync can delete the previous resource when its name is no longer declared in scope. Update references in dependent resources, including model providers, auth strategies, policies, MCP server sources, config stores, and consumer groups. Newly named config stores need secret value sources for their declared secrets; newly named credentials need their required creation fields. Existing secret values and credentials are not copied automatically. The legacy name = ref defaults for these children have been removed. For each existing declaration without a name, add name with the actual Konnect API name. If the resource was originally created using the old fallback, that name will normally equal the original ref; keep the local ref and its dependent references unchanged. Explicit names supplied by configuration templates remain supported. Dumps and scaffolded manifests include names.

Changing a consumer name declares a new consumer, not a rename. In sync mode, deleting the old consumer also removes its credentials; existing API keys for that consumer stop authenticating. Credentials for the new consumer must be configured explicitly. To change only its visible label while retaining its identity and credentials, update display_name and keep name unchanged.

For AI Gateway Policies, display_name must be explicitly provided in both nested and root-level declarations; kongctl does not infer it from name or ref.

For AI Gateway Models, targets[].provider must match an AI Gateway Model Provider name under the parent gateway. The model provider can already exist or be declared in the same gateway configuration.

For AI Gateway Agents, Consumers, Consumer Groups, Models, and MCP Servers, policies entries reference AI Gateway Policies under the same parent gateway. Existing Konnect policy names or IDs can be supplied as strings. Declarative references should use !ref <policy-ref> so the relationship is explicit and same-plan policy creates are ordered and resolved.

For AI Gateway Agents, Models, and MCP Servers, authentication is configured through AI Gateway Auth Strategies. Reference providers from access.auth_strategies with !ref <auth-strategy-ref> so same-plan provider creates are ordered and resolved. MCP Server access also supports OAuth access-token claim selection and protected-resource metadata. The conversion-only MCP Server type does not support access.

For AI Gateway Auth Strategies, Policies, Agents, Consumers, Consumer Groups, MCP Servers, Config Stores, Vaults, Data Plane Certificates, runtime Certificates, CA Certificates, and SNIs, root-level declarations must include ai_gateway, while nested declarations inherit the parent gateway. AI Gateway Consumer Credentials are children of AI Gateway Consumers; root-level declarations must include ai_gateway_consumer, while nested declarations inherit the parent consumer. Omit auth_strategies, policies, agents, consumers, credentials, consumer_groups, mcp_servers, vaults, or data_plane_certificates, certificates, ca_certificates, or snis to leave existing child resources unmanaged during sync. Config Store Secrets are children of Config Stores; root-level declarations must include ai_gateway_config_store, while nested declarations inherit the parent store. Omit secrets to leave existing secrets unmanaged. Use auth_strategies: [], policies: [], agents: [], consumers: [], credentials: [], consumer_groups: [], mcp_servers: [], config_stores: [], secrets: [], vaults: [], or data_plane_certificates: [], certificates: [], ca_certificates: [], or snis: [] under a specific parent to sync-delete that child type. Root-level ai_gateway_auth_strategies: [], ai_gateway_policies: [], ai_gateway_agents: [], ai_gateway_consumers: [], ai_gateway_consumer_credentials: [], ai_gateway_consumer_groups: [], ai_gateway_mcp_servers: [], ai_gateway_config_stores: [], ai_gateway_config_store_secrets: [], ai_gateway_vaults: [], and ai_gateway_data_plane_certificates: [], ai_gateway_certificates: [], ai_gateway_ca_certificates: [], and ai_gateway_snis: [] are rejected because they do not identify a parent resource.

ai_gateways:
 - ref: string
   name: string required
   display_name: string required
   description: string
   proxy_urls: array[object]
     - host: string required
       port: integer required
       protocol: string required
   labels: object [string]string
     key: value
   kongctl:
     namespace: string
     protected: boolean
   model_providers:
     - ref: string
       name: string required
       type: string required
       display_name: string required
       config: object required
       labels: object [string]string
         key: value
       managed_by: object [string]string
         key: value
   auth_strategies:
     - ref: string
       name: string required
       type: key-auth # or openid-connect
       display_name: string required
       config: object required
       labels: object [string]string
         key: value
       managed_by: object [string]string
         key: value
   policies:
     - ref: string
       name: string required
       type: string required
       display_name: string required
       enabled: boolean
       global: boolean
       config: object required
       labels: object [string]string
         key: value
       managed_by: object [string]string
         key: value
   agents:
    - ref: string
      name: string required
      type: a2a # or http
      display_name: string required
      enabled: boolean
      config:
        url: string required
        route: object
        max_request_body_size: integer
        logging: object
      policies:
       - !ref policy-ref
      acls: object
      labels: object [string]string
        key: value
      managed_by: object [string]string
        key: value
   consumers:
    - ref: string
      name: string required
      type: api-key # or oauth
      display_name: string required
      custom_id: string
      policies:
       - !ref policy-ref
      labels: object [string]string
        key: value
      managed_by: object [string]string
        key: value
      credentials:
       - ref: string
         name: string required
         type: api-key
         display_name: string required
         ttl: integer
         labels: object [string]string
           key: value
         managed_by: object [string]string
           key: value
   consumer_groups:
    - ref: string
      name: string required
      display_name: string required
      policies:
       - !ref policy-ref
      labels: object [string]string
        key: value
      managed_by: object [string]string
        key: value
   models:
    - ref: string
      type: model # or api
      name: string required
      display_name: string required
      enabled: boolean
      config:
        route: object required
        model: object required
      formats:
       - type: string required
      targets:
       - name: string required
         provider: string required # provider name in parent AI Gateway
         config:
           type: string required
      policies:
       - !ref policy-ref
      capabilities: array[string]
      labels: object [string]string
        key: value
      access:
        acl_attribute_type: consumer # or oauth_access_token
        access_token_claim_field: string # required for oauth_access_token
        acls: object
        default_tool_acls: object
        auth_strategies:
         - !ref auth-strategy-ref
        metadata: object
      managed_by: object
   mcp_servers:
    - ref: string
      type: conversion-only # or conversion-listener, listener,
                            # passthrough-listener, upstream-server
      name: string required
      display_name: string required
      enabled: boolean
      config:
        url: string required
      tools:
       - name: string required
         description: string required
         method: string required
         path: string
      policies:
       - !ref policy-ref
      labels: object [string]string
        key: value
      acls: object
      managed_by: object
   vaults:
    - ref: string
      type: env # or konnect, aws, gcp, azure, conjur, hcv
      name: string required
      description: string
      config: object required
      labels: object [string]string
        key: value
      managed_by: object [string]string
        key: value
   data_plane_certificates:
    - ref: string
      title: string required
      description: string
      cert: string required # prefer !file or !env for PEM data

AI Gateway Model Providers can also be declared as root resources. Root-level model provider declarations must identify the parent AI Gateway with ai_gateway. Basic authentication uses config.auth.headers, an array of name and value objects. Header value fields and other provider credentials are write-only in Konnect. Declare them with !secret; creates send them once, while updates require --write-secret or --write-secrets during plan generation.

ai_gateway_model_providers:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   name: string required
   type: string required
   display_name: string required
   config: object required
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Auth Strategies can also be declared as root resources. Root-level auth strategy declarations must identify the parent AI Gateway with ai_gateway. OpenID Connect config.client_secret values are write-only in Konnect and are skipped during diff calculation because the API does not return the stored secret. The config object documents the supported shorthand fields but also accepts additional Kong Gateway plugin configuration fields for advanced use cases. Additional fields are passed through to Konnect, which validates their names and values. Access-control fields include consumer_groups_claim and consumer_groups_optional; upstream claim mapping can use upstream_headers_claims and upstream_headers_names. Because the API updates auth strategies with PUT, kongctl merges fields returned by Konnect that are omitted from the declarative config into the update body. This keeps an unrelated update from removing existing access-control configuration.

ai_gateway_auth_strategies:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   name: string required
   type: key-auth # or openid-connect
   display_name: string required
   config: object required
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Policies can also be declared as root resources. Root-level policy declarations must identify the parent AI Gateway with ai_gateway.

ai_gateway_policies:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   name: string required
   type: string required
   display_name: string required
   enabled: boolean
   global: boolean
   config: object required
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Agents can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_agents:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   name: string required
   type: a2a # or http
   display_name: string required
   enabled: boolean
   config:
     url: string required
     route: object
     max_request_body_size: integer
     logging: object
   policies:
    - !ref policy-ref
   access:
     acls: object
     auth_strategies:
      - !ref auth-strategy-ref
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Consumers can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_consumers:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   name: string required
   type: api-key # or oauth
   display_name: string required
   custom_id: string
   policies:
    - !ref policy-ref
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Consumer Credentials can also be declared as root resources. Include ai_gateway_consumer to point at the parent consumer ref. Credential api_key values are write-only and create-only. Omit api_key so Konnect generates it, or use !secret to provide it when creating the credential. Selecting api_key on an existing credential is an error.

ai_gateway_consumer_credentials:
 - ref: string
   ai_gateway_consumer: string required # AI Gateway Consumer ref
   name: string required
   type: api-key
   display_name: string required
   api_key: string # optional; requires !secret and is create-only
   ttl: integer
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Consumer Groups can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_consumer_groups:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   name: string required
   display_name: string required
   policies:
    - !ref policy-ref
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

AI Gateway Models can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_models:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   type: model # or api
   name: string required
   display_name: string required
   enabled: boolean
   config:
     route:
       model: # selector fields are optional
         body_param: model
         values:
           - string
         # header_param: X-Model
         # values:
         #  - string
         # path_param: model
         # values:
         #  - string
     model:
       name_header: boolean
   formats:
    - type: string required
   targets:
    - name: string required
      provider: string required # provider name in parent AI Gateway
      config:
        type: string required
   policies:
    - !ref policy-ref
   capabilities: array[string]
   labels: object [string]string
     key: value
   access:
     acls: object
     auth_strategies:
       - !ref auth-strategy-ref
   managed_by: object

AI Gateway MCP Servers can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_mcp_servers:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   type: conversion-only # or conversion-listener, listener,
                         # passthrough-listener, upstream-server
   name: string required
   display_name: string required
   enabled: boolean
   config:
     url: string required
   tools:
    - name: string required
      description: string required
      method: string required
      path: string
   policies:
    - !ref policy-ref
   labels: object [string]string
     key: value
   access:
     acl_attribute_type: consumer # or oauth_access_token
     access_token_claim_field: string # required for oauth_access_token
     acls: object
     default_tool_acls: object
     auth_strategies:
      - !ref auth-strategy-ref
     metadata:
       discovery_endpoint: string
       endpoint: string
       authorization_servers: array[string]
       resource: string
       scopes_supported: array[string]
   managed_by: object

AI Gateway Config Stores can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_config_stores:
 - ref: support-store
   ai_gateway: support-gateway
   name: support-store
   display_name: Support-Store
   secrets:
    - ref: support-openai-header
      key: openai-auth-header
      value: !secret {source: !env OPENAI_AUTH_HEADER}

Secrets can also be declared at the root. The value field is write-only and must use !secret with a deferred source. A declaration or dump may omit value to represent an existing secret without requesting a write. Creating a missing secret without value is rejected. Use --write-secret support-openai-header#value or --write-secrets to rotate an existing value.

ai_gateway_config_store_secrets:
 - ref: support-openai-header
   ai_gateway_config_store: support-store
   key: openai-auth-header
   value: !secret {source: !env OPENAI_AUTH_HEADER}

Use kongctl get ai-gateway config-stores --gateway-id <id> (or --gateway-name <name>) to list Config Stores. Add a Config Store ID or name as the final argument to retrieve one store. Text, JSON, and YAML output are supported. Use kongctl get ai-gateway config-stores <store> secrets --gateway-id <id> to list safe secret metadata, and append a secret key to retrieve one secret. The list verb supports the same secret-list form. Secret values are never returned or displayed.

Konnect Vaults can reference a Config Store declared in the same configuration. The reference is resolved to the Config Store API ID and orders its creation before the Vault:

ai_gateway_vaults:
 - ref: support-vault
   ai_gateway: support-gateway
   type: konnect
   name: support-vault
   config:
     config_store_id: !ref support-store#id

AI Gateway Vaults can also be declared as root resources. Include ai_gateway to point at the parent gateway ref.

ai_gateway_vaults:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   type: env # or konnect, aws, gcp, azure, conjur, hcv
   name: string required
   description: string
   config: object required
   labels: object [string]string
     key: value
   managed_by: object [string]string
     key: value

Vault config fields follow the SDK request types for all seven variants. Use kongctl explain ai_gateway_vault --output text --extended to inspect their fields and kongctl scaffold ai_gateway_vault for examples of each branch. The same configuration works with declarative diff, apply, and sync.

  • konnect: requires config_store_id; supports Config Store references.
  • env: supports optional prefix and base64_decode.
  • aws: supports region, assume_role_arn, endpoint_url, role_session_name, and sts_endpoint_url.
  • gcp: requires project_id.
  • azure: requires vault_uri and location; also supports credentials_prefix, client_id, tenant_id, and config type.
  • conjur: requires account, endpoint_url, and login; supports write-only api_key.
  • hcv: requires host, port, and auth_method, with additional fields depending on the authentication method. Supported methods are token, cert, jwt, approle, kubernetes, gcp_iam, gcp_gce, aws_ec2, aws_iam, and azure.

As of September 15, 2026, the live API rejects the documented HashiCorp AppRole role_id and secret_id_file fields, requesting different field names absent from the SDK/specification. kongctl accepts the documented fields; live AppRole creation remains blocked by that API discrepancy.

AWS, GCP, Azure, Conjur, and HashiCorp also support base64_decode, neg_ttl, resurrect_ttl, and ttl. TTL values are seconds; the API range is 0 through 4294967295. For a nonzero ttl, use at least 60 seconds. The SDK supplies documented literal defaults, including AWS role_session_name: KongVault and Azure config type: secrets. Specify these fields to override their defaults where the API permits it.

For example, an AWS vault using role assumption:

ai_gateway_vaults:
  - ref: aws-secrets
    ai_gateway: support-gateway
    type: aws
    name: aws-secrets
    config:
      region: us-east-1
      assume_role_arn: arn:aws:iam::123456789012:role/example-role
      role_session_name: kongctl-vault
      ttl: 300

An Azure vault must include its location:

ai_gateway_vaults:
  - ref: azure-secrets
    ai_gateway: support-gateway
    type: azure
    name: azure-secrets
    config:
      vault_uri: https://example.vault.azure.net
      location: eastus
      type: secrets

HashiCorp config is selected by auth_method. For token authentication:

ai_gateway_vaults:
  - ref: hashicorp-secrets
    ai_gateway: support-gateway
    type: hcv
    name: hashicorp-secrets
    config:
      host: vault.example.net
      port: 8200
      auth_method: token
      token: !secret {source: !env HASHICORP_TOKEN}

Use deferred !secret sources for vault credentials: Conjur api_key, HashiCorp token, certificate key, client_secret, secret_access_key, and secret_id. Public vault references remain supported. Secret values are omitted from saved plans, diagnostics, and dumps; supply their sources when applying a dumped configuration that needs credentials.

Unknown config fields and fields belonging to a different vault or HashiCorp authentication branch are rejected before SDK decoding. This also applies to Conjur and HashiCorp configs, whose schemas previously allowed unrecognized keys. API value constraints remain authoritative; see the vault API specification.

AI Gateway Data Plane Certificates can also be declared as root resources. Include ai_gateway to point at the parent gateway ref. There is no update endpoint for this resource; changing cert or description for the same title replaces the certificate with a delete followed by a create.

ai_gateway_data_plane_certificates:
 - ref: string
   ai_gateway: string required # AI Gateway ref
   title: string required
   description: string
   cert: string required # prefer !file or !env for PEM data

Runtime certificates, CA certificates, and SNIs match only by their explicit name within their gateway. UUID refs and cached IDs do not override that name or retain a differently named resource during sync. Keep the existing API name when upgrading manifests; changing it declares a different resource. When changing a certificate name, update referencing SNIs. Sync rejects deletion of a certificate still referenced by an unchanged SNI; planned SNI deletion or reassignment must complete before certificate deletion.

Runtime certificates terminate or originate TLS traffic and are distinct from data plane client certificates. Private keys are write-only. Supply them with !secret; source accepts deferred !env and !file values. A dump preserves public certificate data and omits key and key_alt. Creating a certificate requires key. Updating one requires selecting its configured key with --write-secret <ref>#key or --write-secrets, because the API update payload requires the complete certificate/key pair.

ai_gateway_certificates:
 - ref: runtime-cert
   ai_gateway: support-gateway
   name: runtime-cert
   cert: !file ./certs/runtime.pem
   key: !secret {source: !file ./certs/runtime-key.pem}
   cert_alt: !file ./certs/runtime-alt.pem
   key_alt: !secret {source: !env RUNTIME_ALT_PRIVATE_KEY}

ai_gateway_ca_certificates:
 - ref: partner-ca
   ai_gateway: support-gateway
   name: partner-ca
   cert: !file ./certs/partner-ca.pem

ai_gateway_snis:
 - ref: support-sni
   ai_gateway: support-gateway
   name: support-sni
   display_name: Support TLS hostname
   hostname: support.example.com
   certificate: !ref runtime-cert#name

The SNI certificate relationship resolves to the certificate API name and orders same-plan operations safely. Gateway-scoped SNI reads are the canonical CLI surface: use kongctl get ai-gateway snis --gateway-id <id>. The equivalent commands for runtime certificates and CA certificates are certificates and ca-certificates; all support list/get by ID or name and text, JSON, and YAML output. Certificate-scoped SNI routes are not exposed because they represent the same SNI resources through a second API path.

Event Gateways

API Specification Example

This section is an overview of the Event Gateway resources supported by kongctl. Use kongctl explain event_gateway --output yaml as the authoritative schema for nested Event Gateway resources and fields, and use kongctl scaffold event_gateway to generate starter YAML.

event_gateways:
 - ref: string
   name: string required (1-255 chars)
   description: string (max 512 chars)
   min_runtime_version: string (pattern: ^\d+\.\d+$)
   labels: object [string]string
     key: value
   backend_clusters: # https://developer.konghq.com/api/konnect/event-gateway/v1/#/operations/create-event-gateway-backend-cluster
     - ref: string
       name: string required (1-255 chars)
       description: string (max 512 chars)
       authentication: object required
         type: One of (anonymous | sasl_plain | sasl_scram) required
         username: string # required for sasl_plain/sasl_scram
         password: string # required for sasl_plain/sasl_scram
         algorithm: One of (sha256 | sha512) # required for sasl_scram
       insecure_allow_anonymous_virtual_cluster_auth: boolean
       bootstrap_servers: array[string] required (address:port)
       tls: object required
         enabled: boolean required
         insecure_skip_verify: boolean
         ca_bundle: string
         tls_versions: array[One of (tls12 | tls13)]
       metadata_update_interval_seconds: integer (1-43200)
       labels: object [string]string
         key: value
   virtual_clusters: # https://developer.konghq.com/api/konnect/event-gateway/v1/#/operations/create-event-gateway-virtual-cluster
     - ref: string
       name: string required (1-255 chars)
       description: string (max 512 chars)
       destination: object required
         id: string (uuid) # oneOf; declarative: prefer !ref <backend-cluster-ref>
         name: string # oneOf
       authentication: array[object] required (min 1 item)
         - type: One of (anonymous | sasl_plain | sasl_scram | oauth_bearer) required
           mediation: string # required for sasl_plain/oauth_bearer
           principals: array[object] # for sasl_plain terminate mode
           algorithm: One of (sha256 | sha512) # for sasl_scram
           claims_mapping: object # for oauth_bearer
           jwks: object # for oauth_bearer
           validate: object # for oauth_bearer
       namespace:
         mode: One of (hide_prefix | enforce_prefix) required
         prefix: string required
         additional:
           topics: array[object]
           consumer_groups: array[object]
       acl_mode: One of (enforce_on_gateway | passthrough) required
       dns_label: string required (1-63 chars, RFC1035 label)
       labels: object [string]string
         key: value
   listeners: # https://developer.konghq.com/api/konnect/event-gateway/v1/#/operations/create-event-gateway-listener
     - ref: string
       name: string required (1-255 chars)
       description: string (max 512 chars)
       addresses: array[string] required (min 1 item)
       ports: array[integer|string] required (min 1 item)
       labels: object [string]string
         key: value
       policies: # https://developer.konghq.com/api/konnect/event-gateway/v1/#/operations/create-event-gateway-listener-policy
         - ref: string
           type: One of (tls_server | forward_to_virtual_cluster) required
           name: string
           description: string
           enabled: boolean
           labels: object [string]string
             key: value
           config: object required
             certificates: # if type=tls_server
               - certificate: string required
                 key: string required
             versions: # if type=tls_server
               min: One of (TLSv1.2 | TLSv1.3)
               max: One of (TLSv1.2 | TLSv1.3)
             allow_plaintext: boolean # if type=tls_server
             type: One of (sni | port_mapping) # if type=forward_to_virtual_cluster
             sni_suffix: string # if config.type=sni
             advertised_port: integer # if config.type=sni
             broker_host_format:
               type: One of (per_cluster_suffix | shared_suffix) # if config.type=sni
             destination:
               id: string (uuid) # if config.type=port_mapping; oneOf; declarative: prefer !ref <virtual-cluster-ref>
               name: string # if config.type=port_mapping; oneOf
             advertised_host: string # if config.type=port_mapping
             bootstrap_port: One of (none | at_start) # if config.type=port_mapping
             min_broker_id: integer # if config.type=port_mapping

Additional nested Event Gateway resources include schema_registries, static_keys, tls_trust_bundles, data_plane_certificates, cluster_policies, produce_policies, and consume_policies.

Produce policies support modify_headers, schema_validation, encrypt, and encrypt_fields. Consume policies support modify_headers, schema_validation, decrypt, skip_record, and decrypt_fields. Field-level encryption policy types require Event Gateway runtime 1.2 or newer.

encrypt_fields policies must be children of a produce schema_validation policy. decrypt_fields policies must be children of a consume schema_validation policy. Use the API field name parent_policy_id with a declarative !ref so the planner can order the schema validation parent before the field-level policy and inject the resolved ID during apply.

produce_policies:
  - ref: produce-schema-validation
    name: produce-schema-validation
    type: schema_validation
    config:
      type: json
  - ref: produce-encrypt-fields
    name: produce-encrypt-fields
    type: encrypt_fields
    parent_policy_id: !ref produce-schema-validation#id
    config:
      failure_mode: reject
      encrypt_fields:
        - paths: record.value.content.customer.ssn
          encryption_key:
            type: static
            key:
              id: !ref default-static-key#id

consume_policies:
  - ref: consume-schema-validation
    name: consume-schema-validation
    type: schema_validation
    config:
      type: json
  - ref: consume-decrypt-fields
    name: consume-decrypt-fields
    type: decrypt_fields
    parent_policy_id: !ref consume-schema-validation#id
    config:
      failure_mode: error
      key_sources:
        - type: static
      decrypt_fields:
        paths: record.value.content.customer.ssn

Organization

API Specification Example

organization:
 teams:
   # https://developer.konghq.com/api/konnect/identity/v3/#/operations/create-team
   - ref: string
     name: string required
     description: string (max 250 chars)
     labels: object [string]string
       key: value
     roles:
       - ref: string
         role_name: string
         # Prefer: !ref <api-ref> when entity_type_name=APIs.
         entity_id: string (uuid)
         entity_type_name: string
         entity_region: One of (us | eu | au | me | in | sg | *)

Organization team roles can also be declared as root resources.

organization_team_roles:
  - ref: string
    # Declarative organization team ref, not team name or UUID.
    team: string required
    role_name: string
    # Prefer: !ref <api-ref> when entity_type_name=APIs.
    entity_id: string (uuid)
    entity_type_name: string
    entity_region: One of (us | eu | au | me | in | sg | *)

Portals

API Specification Example

portals:
 - ref: string
   name: string required (1-255 chars)
   display_name: string (1-255 chars)
   description: string (max 512 chars, nullable)
   authentication_enabled: boolean (default: true)
   rbac_enabled: boolean (default: false)
   default_api_visibility: One of (public | private)
   default_page_visibility: One of (public | private)
   default_application_auth_strategy_id: string (uuid, nullable) # prefer: !ref <app-auth-strategy-ref>
   auto_approve_developers: boolean (default: false)
   auto_approve_applications: boolean (default: false)
   labels: object [string]string
     key: value
   customization: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/replace-portal-customization
     ref: string
     theme:
       name: string
       mode: One of (light | dark | system)
       colors:
         primary: string (hex color, e.g. #0055A4)
     layout: string
     css: string (nullable)
     menu:
       main: array[PortalMenuItem]
       footer_sections: array[PortalFooterMenuSection]
       footer_bottom: array[PortalMenuItem]
     spec_renderer:
       try_it_ui: boolean
       try_it_insomnia: boolean
       infinite_scroll: boolean
       show_schemas: boolean
       hide_internal: boolean
       hide_deprecated: boolean
       allow_custom_server_urls: boolean
     robots: string (nullable)
   auth_settings: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/update-portal-authentication-settings
     ref: string
     # OIDC and SAML provider-specific fields are no longer supported here.
     # Move provider config to identity_providers or portal_identity_providers.
     basic_auth_enabled: boolean
     konnect_mapping_enabled: boolean
     idp_mapping_enabled: boolean
   ip_allow_list: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-ip-allow-list
     ref: string
     allowed_ips: array[string] required # IP addresses or CIDR blocks
   integrations: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/upsert-portal-integrations
     ref: string
     google_tag_manager:
       enabled: boolean required
       type: tracking
       config_data:
         id: string required (pattern: ^GTM-[A-Za-z0-9]+$)
         l: string (nullable)
         preview: string (nullable)
         cookies_win: boolean (nullable)
         debug: boolean (nullable)
         npa: boolean (nullable)
         data_layer: string (nullable)
         env_name: string (nullable)
         auth_referrer_policy: string (nullable)
     google_analytics_4:
       enabled: boolean required
       type: analytics
       config_data:
         id: string required (pattern: ^G-[A-Za-z0-9-]+$)
         l: string (nullable)
   identity_providers: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-identity-provider
     - ref: string
       # Use this child for portal OIDC and SAML provider configuration.
       # At the root of a config, use portal_identity_providers.
       type: One of (oidc | saml) required
       enabled: boolean
       config: object required
         issuer_url: string # OIDC
         client_id: string # OIDC
         client_secret: string # OIDC
         scopes: array[string] # OIDC
         claim_mappings: # OIDC
           name: string
           email: string
           groups: string
         idp_metadata_url: string # SAML
         idp_metadata_xml: string # SAML
   custom_domain: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-custom-domain
     ref: string
     hostname: string required
     enabled: boolean required
     ssl: object required
       domain_verification_method: One of (http | custom_certificate) required
       custom_certificate: string # when domain_verification_method=custom_certificate
       custom_private_key: string # when domain_verification_method=custom_certificate
       skip_ca_check: boolean
   pages: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-page
     - ref: string
       slug: string required (max 512 chars)
       content: string required (markdown) # prefer: !file ./docs/page.md
       title: string (max 512 chars)
       visibility: One of (public | private)
       status: One of (published | unpublished)
       description: string (max 160 chars)
       parent_page_id: string (uuid, nullable) # prefer: !ref <page-ref>
       children:
         - ref: string
           slug: string required (max 512 chars)
           content: string required (markdown) # prefer: !file ./docs/page.md
           title: string (max 512 chars)
           visibility: One of (public | private)
           status: One of (published | unpublished)
           description: string (max 160 chars)
           parent_page_id: string (uuid, nullable) # prefer: !ref <page-ref>
   snippets: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-snippet
     - ref: string
       name: string required (max 512 chars)
       content: string required (markdown) # prefer: !file ./docs/snippet.md
       title: string (max 512 chars)
       visibility: One of (public | private)
       status: One of (published | unpublished)
       description: string (max 160 chars)
   teams: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-team
     - ref: string
       name: string required
       description: string (max 250 chars)
       roles: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/assign-role-to-portal-teams
         - ref: string
           role_name: string
           entity_id: string (uuid)
           entity_type_name: string
           entity_region: One of (us | eu | au | me | in | sg | *)
   email_config: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/create-portal-email-config
     ref: string
     domain_name: string (nullable)
     from_name: string (nullable)
     from_email: string (email, nullable)
     reply_to_email: string (email, nullable)
   audit_log_webhook: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/update-portal-audit-log-webhook
     ref: string
     enabled: boolean
     audit_log_destination_id: string (uuid) # prefer: !ref
   email_templates: # https://developer.konghq.com/api/konnect/portal-management/v3/#/operations/update-portal-custom-email-template
     <template_name>:
       ref: string
       name: string
       enabled: boolean
       content:
         subject: string (max 1024 chars, nullable)
         title: string (max 1024 chars, nullable)
         body: string (max 4096 chars, nullable)
         button_label: string (max 128 chars, nullable)
   assets:
     logo: string # data URL image (png/jpeg/gif/ico/svg)
     favicon: string # data URL image (png/jpeg/gif/ico/svg)

Portal identity providers and integrations can also be declared as root resources.

portal_identity_providers:
 - ref: string
   portal: string required # prefer: !ref <portal-ref>
   type: One of (oidc | saml) required
   enabled: boolean
   config: object required
     issuer_url: string # OIDC
     client_id: string # OIDC
     client_secret: string # OIDC
     scopes: array[string] # OIDC
     claim_mappings: # OIDC
       name: string
       email: string
       groups: string
     idp_metadata_url: string # SAML
     idp_metadata_xml: string # SAML

portal_integrations:
 - ref: string
   portal: string required # prefer: !ref <portal-ref>
   google_tag_manager:
     enabled: boolean required
     type: tracking
     config_data:
       id: string required (pattern: ^GTM-[A-Za-z0-9]+$)
       l: string (nullable)
       preview: string (nullable)
       cookies_win: boolean (nullable)
       debug: boolean (nullable)
       npa: boolean (nullable)
       data_layer: string (nullable)
       env_name: string (nullable)
       auth_referrer_policy: string (nullable)
   google_analytics_4:
     enabled: boolean required
     type: analytics
     config_data:
       id: string required (pattern: ^G-[A-Za-z0-9-]+$)
       l: string (nullable)

Portal IP allow lists can also be declared as root resources.

portal_ip_allow_lists:
  - ref: string
    portal: string required # prefer: !ref <portal-ref>
    allowed_ips: array[string] required # IP addresses or CIDR blocks

In sync mode, omitted ip_allow_list configuration is ignored. Include the ip_allow_list block when the portal IP allow list is owned by the config.

Portal audit-log webhooks can also be declared as root resources.

portal_audit_log_webhooks:
  - ref: string
    portal: string required # prefer: !ref <portal-ref>
    enabled: boolean
    audit_log_destination_id: string (uuid) # prefer: !ref

In sync mode, omitted audit_log_webhook configuration is ignored. Include the audit_log_webhook block when the portal webhook is owned by the config.

portals:
  - ref: docs-portal
    name: Docs Portal
    audit_log_webhook:
      ref: docs-portal-audit-log-webhook
      enabled: true
      audit_log_destination_id: !ref foo

audit-logs:
  destinations:
    - ref: foo
      _external:
        selector:
          matchFields:
            name: foo