CLI Configuration

The kubectl-ka plugin supports configuration through persistent configuration files, environment variables, and CLI flags, following the same pattern as kubectl and other plugins.

Configuration Precedence

Configuration values are resolved in the following order (highest to lowest priority):

  1. Plugin CLI Flags - Plugin-specific command line arguments

  2. Environment Variables - System environment variables

  3. Persistent Configuration - Cluster-specific settings stored in ~/.config/kubectl-ka.conf

  4. kubectl Configuration - Bearer tokens from kubectl config

  5. Default Values - Built-in defaults

Global Configuration Parameters

All configuration can be set using environment variables with the prefix KUBECTL_PLUGIN_KA_:

Environment Variable Description Default CLI Flag

KUBECTL_PLUGIN_KA_HOST

KubeArchive API host:port

https://localhost:8081

--host

KUBECTL_PLUGIN_KA_CERT_PATH

Path to KubeArchive API certificate file

(none)

--kubearchive-certificate-authority

KUBECTL_PLUGIN_KA_TLS_INSECURE

Skip TLS certificate verification for the KubeArchive API server

false

--kubearchive-insecure-skip-tls-verify

KUBECTL_PLUGIN_KA_TOKEN

Bearer token for KubeArchive API authentication

(from kubeconfig)

(uses kubectl’s --token flag)

KUBECTL_KA_CONFIG_PATH

Path to the kubectl-ka configuration file

~/.config/kubectl-ka.conf

(none)

Persistent Configuration

The plugin automatically manages cluster-specific configuration in ~/.config/kubectl-ka.conf. This eliminates the need to specify KubeArchive connection details repeatedly when working with multiple clusters.

Configuration File Location

The default configuration file location can be customized:

# Use custom configuration file location
export KUBECTL_KA_CONFIG_PATH="/path/to/my-config.conf"
kubectl ka get pods

Automatic Setup

When you first run a command, the plugin will:

  1. Detect if configuration exists for your current cluster

  2. If not found, offer to run interactive setup

  3. Attempt to discover KubeArchive services automatically

  4. Guide you through authentication setup if needed

Automatic service discovery only works with:

  • OpenShift Routes - Services exposed via OpenShift route resources

  • Local Port-forwarding - Services accessible via kubectl port-forward on localhost

For other service exposure methods (LoadBalancer, NodePort, Ingress, etc.), you must configure the KubeArchive host manually using kubectl ka config set host <url>.

Manual Configuration

You can also configure clusters manually using the config command:

# Interactive setup for current cluster
kubectl ka config setup

# Set KubeArchive host for current cluster
kubectl ka config set host https://kubearchive-api.example.com

# Set authentication token
kubectl ka config set token <your-service-account-token>

# Set custom certificate authority
kubectl ka config set ca /path/to/ca.crt

# Enable insecure TLS (defaults to true if no value provided)
kubectl ka config set insecure
kubectl ka config set insecure true    # Explicit

# Clear/reset configuration values
kubectl ka config unset ca             # Clear certificate authority
kubectl ka config unset insecure       # Reset to secure mode
kubectl ka config unset token          # Use kubectl's token dynamically

Configuration File Format

The configuration file uses YAML format:

clusters:
    production-cluster:
        cluster_name: production-cluster
        server_url: https://api.prod.example.com:6443
        host: https://kubearchive-api.prod.example.com
        tls_insecure: false
        cert_path: /path/to/ca.crt
        token: eyJhbGciOiJSUzI1NiIs...
    staging-cluster:
        cluster_name: staging-cluster
        server_url: https://api.staging.example.com:6443
        host: https://kubearchive-api.staging.example.com
        tls_insecure: true

Authentication

The KubeArchive API only supports bearer token authentication.

If your kubeconfig uses client certificates or other authentication methods, you must provide a bearer token from a service account in the cluster with sufficient permissions to perform the requested operations (get, list, logs).

Certificate Handling

The plugin uses separate certificate handling for Kubernetes and KubeArchive APIs:

KubeArchive API Certificate

The KubeArchive API certificate is configured independently from the Kubernetes cluster certificate. The --kubearchive-certificate-authority, --kubearchive-insecure-skip-tls-verify flags and their environment variables provides the certificate necessary configuration for the CLI.

Kubernetes Cluster Certificate

The Kubernetes cluster certificate continues to use kubectl’s standard --certificate-authority, --insecure-skip-tls-verify flags.

Examples

Use a bearer token for a service account

KUBECTL_PLUGIN_KA_TOKEN=$(kubectl -n test create token default) kubectl ka get v1 pods

Use insecure TLS for KubeArchive API

kubectl ka get v1 pods --kubearchive-insecure-skip-tls-verify

Use a certificate file for KubeArchive API

KUBECTL_PLUGIN_KA_CERT_PATH="/path/to/ca.crt" kubectl ka get v1 pods

Use a host different from a portforwarded one

KUBECTL_PLUGIN_KA_HOST="https://kubearchive.apps.example.com" kubectl ka get v1 pods