kubectl attach

When to Use kubectl attach

kubectl attach connects your terminal to the main process running inside a container. Unlike kubectl exec, which starts a new process, attach piggybacks on the existing PID 1 process. This is useful when you need to interact with an application that reads from stdin or when you want to observe the real-time output of the main process.

Attach vs Exec

The distinction between attach and exec is important:

# Attach: connects to the running main process
kubectl attach my-pod -it
# You are now talking to PID 1

# Exec: starts a NEW process in the container
kubectl exec -it my-pod -- /bin/bash
# You are in a new shell process, independent of PID 1

With attach, any input you type goes directly to the main process's stdin. With exec, you interact with a completely separate process. This has a critical safety implication: pressing Ctrl+C while attached can terminate the container's main process, causing a restart.

Interactive Applications

Attach is designed for containers running interactive processes that expect user input:

# Attach to a container running an interactive Python REPL
kubectl attach python-pod -it

# Attach to a container running an interactive Node.js session
kubectl attach node-pod -it

# Attach to a container running a game server console
kubectl attach game-server -c console -it

The container must be started with stdin: true and optionally tty: true in the pod spec for attach to work interactively:

spec:
  containers:
  - name: app
    image: python:3.12
    stdin: true
    tty: true
    command: ["python"]

Viewing Process Output

Even without interactive input, attach lets you see the real-time output of the main process:

# Watch the main process output
kubectl attach my-pod

# This is similar to kubectl logs -f but directly from the process
# rather than from the log buffer

For most log-viewing purposes, kubectl logs -f is more appropriate because it reads from the container runtime's log buffer and does not risk accidentally sending signals to the process.

Multi-Container Pods

Specify the container when the pod has multiple containers:

# Attach to a specific container
kubectl attach my-pod -c app -it

# Attach to the sidecar container
kubectl attach my-pod -c debug-console -it

Safety Precautions

Because attach connects directly to PID 1, exercise caution:

# Safe: attach with read-only observation (no -i flag)
kubectl attach my-pod

# Potentially dangerous: interactive attach where signals can kill the process
kubectl attach my-pod -it

If you accidentally kill the main process by sending Ctrl+C or other signals, the container will restart according to its restart policy. To detach without sending a signal, use the escape sequence Ctrl+P followed by Ctrl+Q (when the container has a TTY enabled).

Practical Scenarios

The most practical use cases for attach include:

• Debugging startup processes that hang waiting for input
• Interacting with CLI tools that run as the main container process
• Sending graceful shutdown commands to applications that accept them via stdin
• Monitoring real-time output during development

# Debug a process waiting for input
kubectl attach stuck-pod -it
# Type the expected input or send EOF with Ctrl+D

# Send a command to an interactive application
kubectl attach redis-pod -it
# Now you are in the Redis CLI if redis-cli is the main process

When to Choose Other Tools

For most debugging tasks, prefer kubectl exec over attach. Exec gives you a fresh shell without risk to the main process. Use kubectl logs -f for log streaming. Use kubectl debug for deep debugging with specialized tools. Reserve attach for the specific scenario where you need to interact with the main process directly.