configuring kftray

configuration in kftray centers around JSON objects that describe port-forwarding setups. both the desktop and terminal interfaces work with the same configuration database, so changes made in one appear immediately in the other.

when configuration matters

most developers start with simple port forwards and gradually need more sophisticated configuration as their kubernetes environment grows. someone working with a single microservice might only need basic settings, while teams managing dozens of services need organized configuration strategies.

configuration becomes important when dealing with multiple kubernetes contexts, custom kubeconfig files, team sharing requirements, or complex networking setups that require specific local addresses or proxy settings.

configuration data model

based on the source code analysis, kftray configurations include these fields:

{
  "id": 1,
  "service": "api-gateway",
  "namespace": "production",
  "local_port": 8080,
  "remote_port": 8080,
  "context": "prod-cluster",
  "workload_type": "service",
  "protocol": "tcp",
  "remote_address": null,
  "local_address": "127.0.0.1",
  "auto_loopback_address": false,
  "alias": "gateway",
  "domain_enabled": false,
  "kubeconfig": "/Users/dev/.kube/prod-config",
  "target": null
}

essential fields

the core fields that every configuration needs:

service: name of the kubernetes service or pod to forward to. this must match exactly what appears in kubectl get services or kubectl get pods.

namespace: kubernetes namespace containing the target service. defaults to "default" if not specified.

local_port and remote_port: the ports for forwarding. local_port binds on the developer's machine, remote_port connects to the kubernetes service.

context: kubernetes context name from kubeconfig. this determines which cluster the forward targets.

protocol: either "tcp" or "udp". tcp works directly, udp requires the kftray-server proxy deployment.

optional configuration fields

workload_type: "service" or "pod". services work better for stable connections, pods for debugging specific instances.

alias: human-readable name for the configuration. appears in the interface instead of service names.

kubeconfig: path to a specific kubeconfig file. useful when working with multiple clusters that use different authentication.

local_address: bind address for the local port. defaults to 127.0.0.1 (localhost only). set to 0.0.0.0 for network-wide access.

remote_address: target address within the cluster. usually left empty to use the service's default address.

auto_loopback_address: automatically configure local hostfile entries. helpful for services that expect specific domain names.

domain_enabled: enable local domain resolution for the service. works with auto_loopback_address for complex networking setups.

target: specific target within the service. used for advanced routing scenarios.

storage and persistence

both interfaces store configuration in ~/.kftray/kftray.db using SQLite. this database includes configuration definitions, state tracking, and run history.

log files go to ~/.kftray/app.log for general application logs and ~/.kftray/http_logs/ for http traffic captures (when enabled).

configuration changes persist across application restarts and remain consistent between the desktop and terminal interfaces.

workflow-based configuration patterns

single-service development

someone working on one microservice typically needs just the service itself and its database:

[
  {
    "service": "user-api",
    "namespace": "development",
    "local_port": 8080,
    "remote_port": 8080,
    "protocol": "tcp",
    "alias": "api"
  },
  {
    "service": "postgres",
    "namespace": "development", 
    "local_port": 5432,
    "remote_port": 5432,
    "protocol": "tcp",
    "alias": "db"
  }
]

microservices development

teams working with multiple services need organized port assignments to avoid conflicts:

[
  {
    "service": "gateway",
    "local_port": 8080,
    "alias": "gw"
  },
  {
    "service": "user-service",
    "local_port": 8081,
    "alias": "users"
  },
  {
    "service": "payment-service", 
    "local_port": 8082,
    "alias": "payments"
  },
  {
    "service": "notification-service",
    "local_port": 8083,
    "alias": "notifications"
  }
]

multi-environment access

developers often need access to different environments (staging, production) with environment-specific configurations:

[
  {
    "service": "api",
    "namespace": "staging",
    "context": "staging-cluster",
    "local_port": 8080,
    "kubeconfig": "/Users/dev/.kube/staging-config",
    "alias": "staging-api"
  },
  {
    "service": "api",
    "namespace": "production", 
    "context": "prod-cluster",
    "local_port": 8090,
    "kubeconfig": "/Users/dev/.kube/prod-config",
    "alias": "prod-api"
  }
]

export configurations to JSON files for team sharing:

# desktop interface: export from the menu
# terminal interface: copy the configuration from ~/.kftray/

team members import the shared JSON file, then adjust local ports if needed to avoid conflicts.

the desktop interface supports github repository sync for automatic configuration distribution. this works best for teams that want centralized configuration management.

set up a repository with configuration files, configure github sync in kftray, and team members automatically receive configuration updates.

advanced networking configuration

custom bind addresses

by default, port forwards bind to localhost only (127.0.0.1). for network-wide access, set local_address to 0.0.0.0:

{
  "service": "web-app",
  "local_port": 3000,
  "local_address": "0.0.0.0",
  "alias": "web"
}

this allows other machines on the network to access the forwarded service.

udp service forwarding

udp services require the kftray-server proxy component deployed in the kubernetes cluster:

{
  "service": "dns-service",
  "protocol": "udp",
  "local_port": 53,
  "remote_port": 53,
  "alias": "dns"
}

the proxy handles udp traffic that kubernetes can't forward directly.

domain name resolution

enable local domain resolution for services that expect specific hostnames:

{
  "service": "web-app",
  "domain_enabled": true,
  "auto_loopback_address": true,
  "alias": "app"
}

this configures local DNS entries so applications can access services by name instead of localhost:port.

configuration validation and troubleshooting

common configuration problems

port conflicts: multiple configurations using the same local_port cause binding errors. each active configuration needs a unique local port.

context mismatches: context names must match exactly what appears in kubeconfig. use kubectl config get-contexts to verify available contexts.

namespace issues: services must exist in the specified namespace. use kubectl get services -n <namespace> to verify service names.

protocol mismatches: udp forwarding requires the proxy server deployment. tcp forwards work directly with the kubernetes API.

configuration testing

test configurations before saving by checking that the target service exists and responds:

kubectl get service <service-name> -n <namespace> --context <context>

for services that aren't responding, check that pods are running and service selectors match pod labels.

configuration file management

backup strategies

regular configuration exports provide backup and version control:

# desktop: use export menu option
# terminal: copy ~/.kftray/kftray.db

store configuration files in version control alongside application code for team consistency.

eventually, multiple environments require context-specific configurations, and features like github sync or advanced networking become useful for workflow efficiency.

the key is starting simple and adding complexity only when the basic approach becomes limiting.

Edit this page on GitHub

Kftui Terminalusing kftui terminal interface

Guidestroubleshooting