How to Use TCP Probe in Kubernetes for Container Health Checks

In Kubernetes, use a tcpSocket probe inside a livenessProbe or readinessProbe to check if a container is accepting TCP connections on a specific port. This probe tries to open a TCP connection to the container's port and marks the container healthy if successful.

Syntax

The tcpSocket probe is defined inside livenessProbe or readinessProbe in a Pod spec. It requires specifying the port to check. Optional fields like initialDelaySeconds, periodSeconds, and timeoutSeconds control timing.

Key parts:

• tcpSocket: Defines the TCP port to test.
• port: The container port number or name to connect to.
• initialDelaySeconds: Wait time before starting probes.
• periodSeconds: How often to run the probe.
• timeoutSeconds: How long to wait for a response.

yaml

livenessProbe:
  tcpSocket:
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 2

Example

This example shows a Pod with a container that uses a TCP liveness probe on port 8080. Kubernetes will try to open a TCP connection to port 8080 every 5 seconds after an initial delay of 10 seconds. If the connection fails, Kubernetes restarts the container.

yaml

apiVersion: v1
kind: Pod
metadata:
  name: tcp-probe-example
spec:
  containers:
  - name: tcp-server
    image: busybox
    command: ["sh", "-c", "while true; do nc -l -p 8080; done"]
    livenessProbe:
      tcpSocket:
        port: 8080
      initialDelaySeconds: 10
      periodSeconds: 5
      timeoutSeconds: 2

Output

kubectl get pod tcp-probe-example
NAME               READY   STATUS    RESTARTS   AGE
tcp-probe-example   1/1     Running   0          1m

Common Pitfalls

Common mistakes when using TCP probes include:

• Using the wrong port number or a port not open in the container.
• Setting initialDelaySeconds too low, causing false failures before the app is ready.
• Confusing tcpSocket with HTTP probes; TCP probes only check connection, not HTTP response.

Always verify the container listens on the specified port and adjust delays to match startup time.

yaml

Wrong probe example:
livenessProbe:
  tcpSocket:
    port: 9999  # Port not open
  initialDelaySeconds: 5
  periodSeconds: 5

Correct probe example:
livenessProbe:
  tcpSocket:
    port: 8080  # Correct open port
  initialDelaySeconds: 10
  periodSeconds: 5

Quick Reference

Field	Description
tcpSocket.port	Port number or name to test TCP connection
initialDelaySeconds	Seconds to wait before first probe
periodSeconds	Seconds between probes
timeoutSeconds	Seconds to wait for probe response
successThreshold	Number of successes for probe to be considered successful (default 1)
failureThreshold	Number of failures before marking container unhealthy (default 3)

Key Takeaways

Use tcpSocket inside livenessProbe or readinessProbe to check TCP port health.

Set initialDelaySeconds to allow your app to start before probing.

Ensure the container listens on the port specified in the probe.

TCP probes only check if the port is open, not the application protocol.

Adjust periodSeconds and timeoutSeconds to balance responsiveness and resource use.