auto import
auto import allows kftray to automatically discover port forward configurations from kubernetes service annotations, eliminating manual configuration for teams that want standardized port forwarding setups across their services.
when auto import becomes useful
auto import helps when teams have many microservices that need consistent port forwarding configurations. instead of manually creating configurations for each service, developers can annotate services once and have kftray automatically discover and import them.
this becomes especially valuable in microservices environments where services come and go frequently, or when teams want to standardize development environment setup across multiple developers.
the approach works well for teams that use infrastructure-as-code tools like terraform or helm, where annotations can be defined alongside service definitions.
how annotation-based discovery works
services get annotated with special kftray.app/ annotations that tell kftray how to configure port forwards. when someone triggers auto import, the tool scans available services in the cluster and creates configurations based on these annotations.
the basic annotation pattern looks like this:
apiVersion: v1
kind: Service
metadata:
name: api-gateway
annotations:
kftray.app/enabled: "true"
kftray.app/configs: "gateway-8080-8080"
spec:
ports:
- port: 8080
the configs annotation uses a pattern: alias-localport-remoteport. this creates a configuration with the alias "gateway", local port 8080, and remote port 8080.
workflow integration scenarios
infrastructure-as-code integration
teams using terraform or helm can include annotations directly in their service definitions. when services get deployed, they automatically become available for import:
resource "kubernetes_service" "payment_api" {
metadata {
name = "payment-service"
annotations = {
"kftray.app/enabled" = "true"
"kftray.app/configs" = "payments-8081-8080"
}
}
spec {
port {
port = 8080
}
}
}
developers can then run auto import to automatically configure forwards for all annotated services in their development environment.
team onboarding and standardization
new team members can run auto import to automatically get the same port forward setup as the rest of the team. this eliminates the manual process of sharing configuration files or explaining which services need forwarding.
the annotation approach also enforces consistency -- everyone gets the same local ports and aliases for the same services, reducing confusion and port conflicts.
using auto import in practice
desktop interface workflow
in the desktop interface, auto import appears in the main menu. clicking it opens a dialog where someone selects the kubeconfig file and kubernetes context to scan.
the import process shows discovered services with their annotations, allowing selective import of specific services rather than importing everything at once.
imported configurations merge with existing ones, so running auto import multiple times won't create duplicates of services that are already configured.
terminal interface workflow
in kftui, auto import works through the tab menu. the interface shows discovered services in the same table format as regular configurations, with space bar selection for choosing which services to import.
the keyboard-driven workflow fits naturally into the terminal interface's navigation patterns, making bulk import operations efficient for developers who prefer command-line tools.
realistic usage patterns
microservices development environment
a team working on an e-commerce platform might annotate their core services:
# API Gateway
apiVersion: v1
kind: Service
metadata:
name: api-gateway
annotations:
kftray.app/enabled: "true"
kftray.app/configs: "gateway-8080-8080"
---
# User Service
apiVersion: v1
kind: Service
metadata:
name: user-service
annotations:
kftray.app/enabled: "true"
kftray.app/configs: "users-8081-8080"
---
# Payment Service
apiVersion: v1
kind: Service
metadata:
name: payment-service
annotations:
kftray.app/enabled: "true"
kftray.app/configs: "payments-8082-8080"
developers can run auto import once to get forwards for all core services with consistent local ports (8080, 8081, 8082) and meaningful aliases.
database and infrastructure services
backend services like databases and message queues often need forwarding for local development:
apiVersion: v1
kind: Service
metadata:
name: postgres-primary
annotations:
kftray.app/enabled: "true"
kftray.app/configs: "database-5432-5432"
---
apiVersion: v1
kind: Service
metadata:
name: redis-cache
annotations:
kftray.app/enabled: "true"
kftray.app/configs: "cache-6379-6379"
this standardizes access to shared infrastructure across the development team.
configuration discovery and selection
auto import scans all services in the selected kubernetes context and namespace, looking for the kftray.app/enabled annotation. services without this annotation get ignored, allowing selective exposure of services for development access.
the discovery process respects kubernetes RBAC permissions -- if someone can't list services in a namespace, those services won't appear in auto import results.
context and namespace selection during import determines which services get discovered. teams often use different contexts for different environments (development, staging) and import from the appropriate environment.
troubleshooting auto import issues
import discovery problems
when auto import doesn't find expected services, the issue usually involves RBAC permissions or context selection. verify that the selected context and namespace contain the annotated services and that kubernetes credentials allow listing services.
use kubectl get services -n <namespace> to manually verify which services exist and check their annotations with kubectl get service <name> -o yaml.
annotation format problems
incorrect annotation syntax prevents services from being discovered. the kftray.app/configs value must follow the alias-localport-remoteport pattern exactly.
common mistakes include using wrong separators (underscores instead of dashes), invalid port numbers, or missing the kftray.app/enabled annotation.
port conflict resolution
auto import may create configurations with local ports that conflict with existing forwards or local services. when this happens, manually edit the imported configurations to use different local ports.
teams can avoid conflicts by coordinating local port assignments in their annotation strategy, using port ranges that don't overlap with common local development ports.
integration with team workflows
deployment pipeline integration
teams can include auto import as part of their development environment setup. after deploying services to a development cluster, developers run auto import to automatically configure local access to new or updated services.
this works particularly well with gitops workflows where service definitions include the necessary annotations from the start.
documentation and service discovery
annotations serve double duty as both configuration and documentation. developers can scan service annotations to understand which services are intended for local development access and what local ports they use.
this self-documenting approach reduces the need for separate documentation about development environment setup.
limitations and considerations
annotation management overhead
teams need to maintain annotations as part of their service definitions. this adds slight overhead to service creation and modification workflows.
changes to local port assignments require updating annotations and re-running auto import, which may not be as convenient as direct configuration editing.
cluster access requirements
auto import requires read access to kubernetes services, which may not be available in all development scenarios. teams with restricted cluster access might prefer file-based configuration sharing.
the feature also requires network connectivity to the kubernetes cluster during import, unlike configuration files which can be shared offline.
standardization vs flexibility trade-offs
annotation-based configuration enforces standardization but reduces flexibility compared to manual configuration. teams with highly customized port forwarding needs might find the annotation format limiting.
the approach works best for teams that benefit from consistency over customization flexibility.