Ownership, namespaces, and protection with kongctl

Read this page when choosing ownership boundaries, setting defaults, or enforcing namespace guardrails. A profile selects credentials and configuration; namespaces define ownership and reconciliation boundaries.

The kongctl section provides metadata for resource management. Namespace and protection metadata are supported on namespace-bearing resources. Most parent resources store this metadata in Konnect labels. Participating AI Gateway children own their metadata independently, even when nested under a gateway. Other children follow their parent’s lifecycle. Confirm support for each resource with kongctl explain.

The protected field prevents accidental deletion of critical resources:

portals:
  - ref: production-portal
    name: "Production Portal"
    kongctl:
      protected: true  # Cannot be deleted until protection is removed

The namespace field enables resource isolation:

apis:
  - ref: billing-api
    name: "Billing API"
    kongctl:
      namespace: finance-team  # Owned by finance team
      protected: false

A namespace must contain 1–63 lowercase alphanumeric characters or hyphens and must start and end with an alphanumeric character. Consecutive hyphens are permitted and are preserved exactly.

Use _defaults to set metadata defaults for namespace-bearing resources in one file. Explicit resource metadata overrides these defaults:

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

portals:
  - ref: api-portal
    name: "API Portal"
    # Inherits namespace: platform-team and protected: true

  - ref: test-portal
    name: "Test Portal"
    kongctl:
      namespace: qa-team
      protected: false
    # Overrides both defaults

kongctl provides some default behavior depending on how metadata fields are specified or omitted. The following tables summarize the behavior.

Namespace values can use !env in file defaults or resource metadata. They resolve before validation and sync scoping, and remain fixed in saved plans. See Environment Management for a reusable example.

namespace field behavior

protected field behavior

Portal and API children follow the parent’s ownership. Independently owned AI Gateway children inherit file defaults, rather than the gateway’s explicit metadata. Consumer credentials inherit consumer ownership. See the [AI Gateway federation guide][site-ai-gateway-federation-guide] for the support matrix, existing-resource ownership setup, and cascade-deletion limits.

The kongctl plan command provides built-in namespace guardrails:

• --require-any-namespace forces every managed resource to declare a namespace via kongctl.namespace or _defaults.kongctl.namespace.
• --require-namespace=<ns> restricts planning to the provided namespaces (repeat or comma-separate the flag to allow multiple values).

These flags help prevent accidentally operating on unexpected namespaces, especially when running in sync mode.

External resources do not participate in namespace enforcement and do not inherit kongctl metadata. If no managed parent resources are present, an explicit _defaults.kongctl.namespace satisfies --require-any-namespace and must match one of the values allowed by --require-namespace. Defaults on external-only files are retained for enforcement without adding namespaces to sync’s deletion scope. Defaults-only files still select namespaces for sync deletion.

_deck steps do not independently participate in namespace enforcement. For a managed control plane, enforcement checks the control plane’s namespace. A file containing only external control planes with _deck must declare a matching file-level default to satisfy namespace enforcement. This validates the manifest’s declared namespace; it does not check the external control plane’s labels or assign namespaces to Gateway entities managed by decK.

[site-ai-gateway-federation-guide]: https://github.com/Kong/kongctl/blob/main/docs/ai-gateway-federation.md