TCP probe configuration in Kubernetes - Commands & Configuration

Introduction

Sometimes, you want to check if your app inside a container is ready or alive by testing if it can accept network connections. TCP probes help Kubernetes do this by trying to open a simple network connection to your app's port.

When you want Kubernetes to restart a container if it stops accepting network connections.

When you want to delay sending traffic to a container until it is ready to accept connections.

When your app does not have an HTTP endpoint but listens on a TCP port.

When you want a simple check to see if your app's port is open and responsive.

When you want to improve app reliability by automatically detecting and fixing network failures.

Config File - tcp-probe-pod.yaml

tcp-probe-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: tcp-probe-pod
spec:
  containers:
  - name: tcp-probe-container
    image: nginx:1.23
    ports:
    - containerPort: 80
    readinessProbe:
      tcpSocket:
        port: 80
      initialDelaySeconds: 5
      periodSeconds: 10
    livenessProbe:
      tcpSocket:
        port: 80
      initialDelaySeconds: 15
      periodSeconds: 20

This file creates a pod running an nginx container.

The readinessProbe uses a TCP socket check on port 80 to see if the container is ready to accept traffic. It waits 5 seconds before starting checks and repeats every 10 seconds.

The livenessProbe also uses a TCP socket check on port 80 to see if the container is alive. It waits 15 seconds before starting and repeats every 20 seconds.

Commands

This command creates the pod with the TCP readiness and liveness probes configured. Kubernetes will start the pod and begin checking the TCP port.

Terminal

kubectl apply -f tcp-probe-pod.yaml

Expected Output

pod/tcp-probe-pod created

This command checks the status of the pod to see if it is running and ready based on the TCP probe results.

Terminal

kubectl get pods tcp-probe-pod

Expected Output

NAME             READY   STATUS    RESTARTS   AGE

tcp-probe-pod    1/1     Running   0          20s

This command shows detailed information about the pod, including the results of the TCP probes and any events related to container health.

Terminal

kubectl describe pod tcp-probe-pod

Expected Output

Name:         tcp-probe-pod

Namespace:    default

Priority:     0

Node:         minikube/192.168.49.2

Start Time:   Thu, 01 Jun 2023 12:00:00 +0000

Labels:       <none>

Annotations:  <none>

Status:       Running

IP:           172.17.0.5

Containers:

  tcp-probe-container:

    Container ID:   docker://abcdef123456

    Image:          nginx:1.23

    Image ID:       docker-pullable://nginx@sha256:...

    Port:           80/TCP

    State:          Running

      Started:      Thu, 01 Jun 2023 12:00:10 +0000

    Ready:          True

    Restart Count:  0

    Readiness:      tcpSocket on port 80 delay=5s timeout=1s period=10s

    Liveness:       tcpSocket on port 80 delay=15s timeout=1s period=20s

Events:

  Type    Reason     Age   From               Message

  ----    ------     ----  ----               -------

  Normal  Scheduled  30s   default-scheduler  Successfully assigned default/tcp-probe-pod to minikube

  Normal  Pulled     25s   kubelet            Container image "nginx:1.23" already present on machine

  Normal  Created    25s   kubelet            Created container tcp-probe-container

  Normal  Started    25s   kubelet            Started container tcp-probe-container

Key Concept

If you remember nothing else from this pattern, remember: TCP probes check if your app's network port is open and accepting connections to decide if it is ready or alive.

Common Mistakes

Using a port number in the TCP probe that the container does not listen on.

The probe will always fail because it cannot connect, causing Kubernetes to think the container is unhealthy.

Make sure the TCP probe port matches the container's actual listening port.

Setting initialDelaySeconds too low before the app is ready to accept connections.

Kubernetes may mark the container as unhealthy and restart it before it has a chance to start properly.

Set initialDelaySeconds to a value that gives your app enough time to start.

Not defining both readinessProbe and livenessProbe when needed.

Without readinessProbe, Kubernetes may send traffic to a container that is not ready. Without livenessProbe, Kubernetes won't restart a crashed container.

Define readinessProbe to control traffic flow and livenessProbe to detect and fix crashes.

Summary

Create a pod YAML file with tcpSocket probes under readinessProbe and livenessProbe sections.

Apply the pod configuration using kubectl apply -f to start the pod with TCP health checks.

Use kubectl get pods and kubectl describe pod to verify the pod status and probe results.