Auto Import

Automatically discover port-forward configurations from Kubernetes service annotations.

Auto import discovers port-forward configurations from Kubernetes service annotations, so you don't have to create them manually.

Annotation format

apiVersion: v1
kind: Service
metadata:
  name: api-gateway
  namespace: production
  annotations:
    kftray.app/enabled: "true"
    kftray.app/configs: "api-8080-80,admin-8081-8080"
spec:
  selector:
    app: api-gateway
  ports:
    - name: http
      port: 80
      targetPort: 8080
    - name: admin
      port: 8080
      targetPort: 8080

The kftray.app/configs annotation defines port forwards using the format alias-localport-remoteport. Multiple forwards are comma-separated.

This example creates two configurations:

api: localhost:8080 → service port 80
admin: localhost:8081 → service port 8080

Required annotations

Annotation	Value	Description
`kftray.app/enabled`	`"true"`	Enables auto import for this service
`kftray.app/configs`	`"alias-local-remote,..."`	Comma-separated list of port forward definitions

How discovery works

kftray scans all services in namespaces you have access to, looking for the kftray.app/enabled: "true" annotation. For each annotated service:

Parse the kftray.app/configs value.

Create a configuration object with service and namespace from metadata, context from your current Kubernetes context, and alias, local_port, remote_port from the config string parts.

Add the configuration to your local database.

Discovery runs:

On kftray startup
When you manually trigger "Discover Services" in the interface
Every 10 minutes (desktop interface only)

RBAC permissions required

Auto import requires permissions to list services across namespaces. If discovery fails, verify permissions with kubectl auth can-i list services --all-namespaces. You may need a ClusterRole binding for cluster-wide discovery. If you don't have LIST privilege on a namespace, you can type the namespace name manually in the import dialog.

Integration with Helm

# templates/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: {{ include "myapp.fullname" . }}
  annotations:
    kftray.app/enabled: "true"
    kftray.app/configs: "{{ .Values.kftray.alias }}-{{ .Values.kftray.localPort }}-{{ .Values.service.port }}"
spec:
  ports:
    - port: {{ .Values.service.port }}
      targetPort: http

# values.yaml
service:
  port: 8080

kftray:
  alias: "myapp"
  localPort: 8080

Deploy with Helm and kftray automatically discovers the service:

helm install myapp ./myapp
# kftray discovers: myapp-8080-8080

Using auto import

Open kftray desktop interface.

Click "Discover Services" in the toolbar.

Select namespaces to scan (or "All Namespaces").

Click "Scan".

Review discovered configurations.

Click "Import Selected".

Discovered configurations appear in your port forward list immediately.

Discover annotated services and start port-forwards immediately, without opening the TUI:

# Discover and start all annotated services
kftui --auto-discover --context my-cluster --auto-start --non-interactive

# Save discovered configs to the database for later use
kftui --auto-discover --context my-cluster --save

# Use a custom kubeconfig file
kftui --auto-discover --context my-cluster --kubeconfig /path/to/kubeconfig --auto-start --non-interactive

# Enable alias-as-domain and auto loopback address for all discovered services
kftui \
  --auto-discover \
  --context my-cluster \
  --alias-as-domain \
  --auto-loopback \
  --auto-start \
  --non-interactive