The sync command applies your configuration as the full desired state, creating and updating resources and deleting managed resources that are missing from explicitly scoped collections.
If you want to apply configuration without deleting resources (creates and updates only), use kongctl apply instead.
Sync scope is based on YAML key presence:
apis: [] deletes managed APIs in the selected namespace.portal block without
pages doesn’t delete Dev Portal pages. Use pages: [] under that portal block to
declare that the Dev Portal should have no pages.email_templates: {} means the Dev Portal should have no customized
email templates.{} and null
are intentionally different. Omit a singleton key to ignore that child.
Provide an object with fields to manage or update it. For optional,
delete-capable Dev Portal singletons such as custom_domain, email_config, and
audit_log_webhook, an empty object scopes the child with desired count zero:
custom_domain: {} deletes any existing managed custom domain for that
Dev Portal during sync. null is rejected because sync doesn’t infer reset or
delete semantics from null. Update-only singleton sections, such as
customization, cannot be deleted by declaring {}.api_documents: [] is rejected because it doesn’t identify which API owns
the desired zero count.For federated ownership, include the parent resource entry in the team
configuration and scope only the child collection that team owns. When the
parent is managed elsewhere and the resource type supports _external, declare
the parent as external and nest the child collection under that parent. This
allows sync to plan the child collection without treating the managed parent
collection in the team’s namespace as desired state.
apis:
- ref: orders-api
name: Orders API
documents: []portals:
- ref: shared-docs-portal
_external:
selector:
matchFields:
name: "Shared Docs Portal"
pages: []The external-parent pattern should not be combined with a namespace default unless the team also intends to scope managed parent resources in that namespace.
Preview sync changes:
kongctl sync -f config.yaml --dry-runSync configuration with a prompt confirmation:
kongctl sync -f team-config.yamlSkip confirmation prompt and sync changes without approval:
Be careful when using the
--auto-approveflag, as this command will create, update, and delete entities without any preview or confirmation.
kongctl sync -f config.yaml --auto-approveSync from a plan artifact:
kongctl sync --plan plan.jsonkongctl provides the following tools for syncing configuration:
|
Command |
Description |
|---|---|
| kongctl sync konnect | Synchronize with Konnect. |
Usage:
kongctl sync [flags]
kongctl sync [command]
Examples:
# Synchronize Konnect resources from declarative configuration
kongctl sync -f api.yaml
# Synchronize using the explicit Konnect target form
kongctl sync konnect -f api.yaml
# Execute a reviewed plan without prompting
kongctl sync --plan plan.json --auto-approve
Available Commands:
konnect Synchronize declarative configuration to Konnect
Flags:
--auto-approve Skip confirmation prompt
--base-dir string Base directory boundary for !file resolution.
Defaults to each -f source root (file: its parent dir, dir: the directory itself). For stdin, defaults to CWD.
- Config path: [ konnect.declarative.base-dir ]
--base-url string Base URL for Konnect API requests.
- Config path: [ konnect.base-url ]
- Default : [ https://us.api.konghq.com ]
--color-theme string Configures the CLI UI/theme (prompt, tables, TUI elements).
- Config path: [ color-theme ]
- Examples : [ auto, 3024_day, 3024_night, aardvark_blue, abernathy ]
- Reference : [ https://github.com/lrstanley/bubbletint/blob/master/DEFAULT_TINTS.md ] (default "auto")
--config-file string Path to the configuration file to load.
- Default: [ $XDG_CONFIG_HOME/kongctl/config.yaml ]
--dry-run Preview changes without applying them
--execution-report-file string Save execution report as JSON to file
-f, --filename strings Filename or directory to files to use to create the resource (can specify multiple)
-h, --help help for sync
--http-retry-backoff-factor float Exponential backoff growth factor for retries (for example: 2.0).
- Config path: [ konnect.http-retry-backoff-factor ]
--http-retry-initial-interval int Initial retry backoff interval in milliseconds (0 = use default).
- Config path: [ konnect.http-retry-initial-interval ]
--http-retry-max-attempts int Maximum total attempts for retryable HTTP requests (0 = use default, 1 disables retries).
- Config path: [ konnect.http-retry-max-attempts ]
--http-retry-max-interval int Maximum retry backoff interval in milliseconds (0 = use default).
- Config path: [ konnect.http-retry-max-interval ]
--http-retry-on-connection-errors Retry selected retryable connection-level errors.
- Config path: [ konnect.http-retry-on-connection-errors ]
--log-file string Write execution logs to the specified file instead of STDERR.
- Config path: [ log-file ]
--log-level string Configures the logging level. Execution logs are written to STDERR.
- Config path: [ log-level ]
- Allowed : [ trace|debug|info|warn|error ] (default "error")
--max-concurrency int Maximum number of concurrent API operations during execution (min 1, max 200).
When the plan contains execution_groups, operations within each group run
concurrently up to this limit. Use 1 for sequential execution.
- Config path: [ konnect.declarative.max-concurrency ] (default 5)
--no-telemetry Disable telemetry for this command invocation. Overrides config and env.
- Config path: [ telemetry.enabled ]
- Env var : [ KONGCTL_NO_TELEMETRY ]
- Default : [ false ]
-o, --output string Configures the format of data written to STDOUT.
- Config path: [ output ]
- Allowed : [ json|yaml|text ] (default "text")
--pat string Konnect Personal Access Token (PAT) used to authenticate the CLI.
Setting this value overrides tokens obtained from the login command.
- Config path: [ konnect.pat ]
--plan string Path to existing plan file
-p, --profile string Specify the profile to use for this command. (default "default")
-R, --recursive Process the directory used in -f, --filename recursively
--region string Konnect region identifier (for example "eu"). Used to construct the base URL when --base-url is not provided.
- Config path: [ konnect.region ]
--require-any-namespace Require explicit namespace on all resources (via kongctl.namespace or _defaults.kongctl.namespace).
Cannot be used with --require-namespace.
- Config path: [ konnect.declarative.require-any-namespace ]
--require-namespace strings Require specific namespaces. Accepts comma-separated list or repeated flags.
Cannot be used with --require-any-namespace.
Examples:
--require-namespace=foo # Allow only 'foo' namespace
--require-namespace=foo,bar # Allow 'foo' or 'bar' (comma-separated)
--require-namespace=foo --require-namespace=bar # Allow 'foo' or 'bar' (repeated flags)
- Config path: [ konnect.declarative.require-namespace ]
Use "kongctl sync [command] --help" for more information about a command.