Configuration of kongctl

kongctl provides a flexible system for configuring the CLI behavior which allows you to customize behavior for different machines, Konnect organizations, environments, and automation pipelines.

Note: The term configuration in this document describes altering of the behavior of the CLI itself, not to be confused with declarative configuration used to manage the state of Konnect resources. For declarative configuration, see the declarative configuration guide.

kongctl supports named collections of configuration values, which are called profiles. You can use profiles to separate configurations for any purpose you need. Common usage includes different organizations, regions, or machines.

Using profiles is optional. If no profile is specified, a built-in profile named default is applied.

Sample configuration snippet:

my-profile:     # profile name
  output: json  # configuration value
  konnect:       
    region: us  # configuration names can be nested

Each kongctl invocation uses a single profile to determine which configuration values to apply. You can specify the profile in different ways:

# No profile specified, the 'default' profile is implied
kongctl get apis

# Specify profile with flag
kongctl get apis --profile production

# Specify profile with environment variable
KONGCTL_PROFILE=production kongctl get apis

# Export a profile via environment variable
export KONGCTL_PROFILE=production
# Uses the production profile 
kongctl get apis
# Also uses the production profile 
kongcll apply -f config.yaml

All kongctl configuration values can be loaded via flags, environment variables, or the configuration file. This allows you to set defaults in files while overriding them as needed for specific commands or environments.

All configuration values are specified via a path. The path to a particular configuration value is provided in the usage text of the command. For example, the Konnect region configuration value is shown in the help text as:

--region string     Konnect region identifier (for example "eu")... 
                          - Config path: [ konnect.region ]

This shows that you can specify a region with the --region flag, but you can also set it in the configuration file or via environment variables based on the config path.

In the configuration file, this value would be set under the profile name with the following YAML syntax:

default:
  konnect:
    region: eu

When values are loaded via environment variables, the variable names must start with the KONGCTL_ prefix, then the desired profile, and finally the config path in uppercase with underscores instead of dots.

For example, to set the same region value for the default profiles, set the following environment variable:

KONGCTL_DEFAULT_KONNECT_REGION=eu

By default kongctl reads configurations from a file located at $XDG_CONFIG_HOME/kongctl/config.yaml and falls back to ~/.config/kongctl/config.yaml if XDG_CONFIG_HOME is not set.

You can specify a different configuration file via the --config-file flag:

--config-file string   Path to the configuration file to load.
                             - Default: [ $XDG_CONFIG_HOME/kongctl/config.yaml ]

Precedence

kongctl configuration values are loaded in the following precedence (highest to lowest):

1. Command-line flags: Explicit flags like --pat, --region, --output
2. Environment variables: KONGCTL_<PROFILE>_<CONFIG_PATH> variables
3. Configuration file: Values in config.yaml
4. Default values: Built-in defaults