Skip to main content

Kubernetes Targets

Kubernetes targets run commands inside pods via kubectl exec. Declare them under targets.pods in .xec/config.yaml; reference them as pods.<name>.

Basic Configuration​

targets:
  pods:
    api:
      namespace: production
      pod: api-server-7d9c5b4f8-x2n4l
      container: app
xec in pods.api "ps aux"

kubectl must be installed and authenticated against the cluster.

Reference​

Fields the CLI forwards to the Kubernetes adapter:

targets:
  pods:
    example:
      # Pod identification
      pod: api-server-abc123        # pod name, or a label selector: "-l app=api"
      namespace: production          # default: "default"
      container: app                 # container within the pod (default: first)

      # Cluster selection
      context: prod-cluster          # kubectl context; default: current-context
      kubeconfig: ~/.kube/prod       # kubeconfig file; default: ambient

      # Exec behaviour
      tty: true                      # allocate a TTY
      stdin: true                    # keep stdin open
      execFlags: ["--request-timeout=30s"]  # extra flags passed to kubectl exec

      # Environment for every command on this target
      env:
        DEPLOY_ENV: production

A pod value that starts with -l is resolved to the first pod matching the label selector before the exec call runs:

targets:
  pods:
    frontend:
      namespace: production
      pod: "-l app=frontend"

Other keys under a pod entry (selector, timeout, shell, per-target buffer limits) are accepted by the parser but are not forwarded to the connection.

Naming a Cluster Explicitly​

Without context, a target belongs to whatever kubectl config current-context happens to be — a target that says production can silently run against staging. Production targets should name their cluster:

targets:
  pods:
    prod-api:
      context: prod-cluster
      namespace: production
      pod: "-l app=api"

Environment Variables​

env is applied to every command executed on the target:

targets:
  pods:
    worker:
      namespace: jobs
      pod: "-l app=worker"
      env:
        QUEUE: high-priority

Examples​

Database Migration​

targets:
  pods:
    db-migrate:
      context: prod-cluster
      namespace: production
      pod: "-l app=api"
      container: app
xec in pods.db-migrate "npm run migrate"

Debugging a Specific Pod​

targets:
  pods:
    debug:
      namespace: staging
      pod: api-server-7d9c5b4f8-x2n4l
      tty: true
      stdin: true

Troubleshooting​

# Test the target
xec in pods.api "echo ok"

# Verbose output
xec --verbose in pods.api "echo ok"

# Show the resolved target configuration
xec config get targets.pods.api

# Check what kubectl itself sees
kubectl --context prod-cluster -n production get pods

Common failures:

  • Pod not found — the pod name is stale (pods are replaced on every deploy) or the selector matches nothing. Prefer -l selectors over literal pod names.
  • Wrong cluster — no context set and current-context points elsewhere.
  • Container not found — the pod has several containers and container: names none of them. List them with kubectl get pod <name> -o jsonpath='{.spec.containers[*].name}'.

Next Steps​

See Also​