TCP probe configuration in Kubernetes - Deep Dive

Overview - TCP probe configuration

What is it?

A TCP probe in Kubernetes is a way to check if a container is ready or alive by trying to open a TCP connection on a specific port. It does not send any data but simply tests if the port is open and accepting connections. This helps Kubernetes know if the application inside the container is working properly or needs restarting. TCP probes are simpler than HTTP probes and useful for services that do not speak HTTP.

Why it matters

Without TCP probes, Kubernetes would not know if a container is actually ready to serve traffic or if it has crashed or hung. This could lead to sending requests to broken services, causing downtime or errors. TCP probes help maintain application reliability by allowing Kubernetes to restart or stop sending traffic to unhealthy containers automatically.

Where it fits

Before learning TCP probes, you should understand basic Kubernetes concepts like pods, containers, and the idea of health checks (probes). After mastering TCP probes, you can learn about other probe types like HTTP and command probes, and how to combine them for robust application monitoring.

Mental Model

Core Idea

A TCP probe checks if a container is alive by simply trying to open a network connection on a port without sending data.

Think of it like...

It's like knocking on a door to see if someone is home without entering or talking—if the door opens, the person is there and responsive.

┌─────────────────────────────┐
│ Kubernetes TCP Probe Process │
├─────────────────────────────┤
│ 1. Kubernetes tries to open  │
│    a TCP connection to port  │
│    inside the container.    │
│                             │
│ 2. If connection succeeds,  │
│    container is healthy.    │
│                             │
│ 3. If connection fails,     │
│    container is unhealthy. │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Kubernetes Probes Basics

Concept: Introduce what probes are and their role in Kubernetes.

Kubernetes uses probes to check the health of containers. There are three types: liveness, readiness, and startup probes. Each probe helps Kubernetes decide if a container should be restarted or if it can receive traffic. Probes run periodically and report success or failure.

Result

Learner understands that probes are health checks that keep applications reliable in Kubernetes.

Knowing probes are health checks helps you grasp why Kubernetes manages container lifecycle automatically.

2

Foundation

What is a TCP Probe in Kubernetes

Concept: Explain the TCP probe type and how it works.

A TCP probe tries to open a TCP connection to a container's port. It does not send any data, just checks if the port is open and accepting connections. If the connection opens, the probe succeeds; if not, it fails.

Result

Learner can distinguish TCP probes from other probe types like HTTP or command probes.

Understanding TCP probes as simple connection checks clarifies when to use them for non-HTTP services.

3

Intermediate

Configuring a TCP Probe in Pod Spec

🤔Before reading on: do you think TCP probes require specifying a path like HTTP probes? Commit to your answer.

Concept: Show how to write a TCP probe configuration in a Kubernetes pod YAML file.

In the pod spec, under containers, you add a livenessProbe or readinessProbe section. For TCP probes, you specify 'tcpSocket' with the port number. Example: livenessProbe: tcpSocket: port: 8080 initialDelaySeconds: 10 periodSeconds: 5 This tells Kubernetes to try connecting to port 8080 after 10 seconds, every 5 seconds.

Result

Learner can write a valid TCP probe configuration in Kubernetes manifests.

Knowing TCP probes don't need a path simplifies configuration for many services.

4

Intermediate

Differences Between Liveness and Readiness TCP Probes

🤔Before reading on: do you think liveness and readiness probes behave the same way? Commit to your answer.

Concept: Explain how TCP probes differ when used as liveness or readiness checks.

Liveness probes check if the container should be restarted if unhealthy. Readiness probes check if the container is ready to accept traffic. Both can use TCP probes, but readiness probes prevent traffic routing until success, while liveness probes trigger restarts on failure.

Result

Learner understands the distinct roles of liveness and readiness probes using TCP checks.

Recognizing the different effects of probe failures helps design better health checks.

5

Intermediate

Tuning TCP Probe Timing Parameters

🤔Before reading on: do you think setting very short probe intervals is always better? Commit to your answer.

Concept: Introduce parameters like initialDelaySeconds, periodSeconds, timeoutSeconds, and failureThreshold.

You can control when and how often Kubernetes runs TCP probes: - initialDelaySeconds: wait before first probe - periodSeconds: time between probes - timeoutSeconds: how long to wait for response - failureThreshold: how many failures before marking unhealthy Setting these properly avoids false positives and unnecessary restarts.

Result

Learner can adjust probe timings to match application startup and behavior.

Understanding timing parameters prevents premature restarts and improves stability.

6

Advanced

Using TCP Probes with Stateful and Non-HTTP Services

🤔Before reading on: do you think TCP probes work well for HTTP APIs? Commit to your answer.

Concept: Explain why TCP probes are ideal for services that do not use HTTP or have complex startup sequences.

Services like databases, caches, or custom TCP servers often don't have HTTP endpoints. TCP probes simply check if the port is open, making them perfect for these cases. They also avoid overhead of HTTP parsing and can detect if the service is listening even if not fully ready.

Result

Learner knows when TCP probes are the best choice for health checks.

Knowing the right probe type for your service avoids misconfigurations and false health reports.

7

Expert

Limitations and Pitfalls of TCP Probes in Production

🤔Before reading on: do you think a successful TCP probe guarantees the application is fully healthy? Commit to your answer.

Concept: Discuss scenarios where TCP probes can give false positives and how to mitigate them.

A TCP probe only checks if the port is open, not if the application is fully functional. For example, a service might accept connections but fail to process requests correctly. Combining TCP probes with other checks like HTTP or exec probes can improve accuracy. Also, aggressive probe settings can cause unnecessary restarts.

Result

Learner understands the limits of TCP probes and how to design robust health checks.

Knowing TCP probes' limits prevents over-reliance and helps build multi-layered health strategies.

Under the Hood

Kubernetes runs the probe by opening a TCP socket to the container's IP and specified port inside the pod network namespace. It uses the operating system's networking stack to attempt a connection. If the TCP handshake completes successfully, the probe returns success immediately without sending any data. If the connection is refused or times out, the probe fails. This check is lightweight and fast because it only tests connectivity, not application logic.

Why designed this way?

TCP probes were designed to provide a simple, universal health check for any TCP-based service without requiring protocol-specific knowledge. Unlike HTTP probes, TCP probes do not need the application to implement an HTTP endpoint. This design choice allows Kubernetes to support a wide range of applications, including databases and custom protocols, with minimal configuration and overhead.

┌───────────────┐       ┌───────────────┐
│ Kubernetes    │       │ Container     │
│ Probe Runner  │──────▶│ TCP Port      │
│ (opens TCP   │       │ (listening?)  │
│ socket)       │       │               │
└───────────────┘       └───────────────┘
       │                       ▲
       │                       │
       │ connection success    │ connection refused or timeout
       ▼                       │
┌───────────────┐              │
│ Probe Result  │◀─────────────┘
│ Success/Fail  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a successful TCP probe mean the application is fully ready? Commit yes or no.

Common Belief: If the TCP probe succeeds, the application is fully healthy and ready to serve requests.

Reality: A successful TCP probe only means the port is open and accepting connections, not that the application logic is working correctly.

Why it matters: Relying solely on TCP probes can cause Kubernetes to send traffic to partially broken services, leading to errors or degraded user experience.

Quick: Do TCP probes require specifying a URL path like HTTP probes? Commit yes or no.

Common Belief: TCP probes need a path or endpoint to check inside the container.

Reality: TCP probes only require a port number; they do not use paths or send data.

Why it matters: Misunderstanding this leads to incorrect probe configurations and failed health checks.

Quick: Can TCP probes detect application startup delays accurately? Commit yes or no.

Common Belief: TCP probes can reliably detect when an application is fully started and ready.

Reality: TCP probes only check port availability, which may happen before the app is fully ready to handle requests.

Why it matters: This can cause Kubernetes to route traffic too early, causing failures or errors.

Quick: Is it safe to set very frequent TCP probe intervals? Commit yes or no.

Common Belief: Setting very short intervals for TCP probes improves health detection without downsides.

Reality: Too frequent probes can overload the application or network, causing false failures or performance issues.

Why it matters: Improper timing settings can cause unnecessary restarts and instability.

Expert Zone

1

TCP probes do not guarantee application-level health, so combining them with exec or HTTP probes can provide a fuller picture.

2

In some network environments, firewall rules or network policies can block TCP probes, causing false negatives.

3

TCP probes are lightweight but can still cause resource usage spikes if configured with aggressive timing on many pods.

When NOT to use

Avoid TCP probes when your application exposes HTTP endpoints that can provide richer health information. Use HTTP probes for detailed status codes and response checks. For complex startup or shutdown logic, consider exec probes that run custom commands inside the container.

Production Patterns

In production, TCP probes are often used for databases, caches, and legacy TCP services. They are combined with readiness probes to control traffic flow and liveness probes to trigger restarts. Experts tune timing parameters carefully to balance fast detection with stability and often use multi-probe strategies for robust health monitoring.

Connections

HTTP health probes

TCP probes are a simpler alternative to HTTP probes, focusing only on connectivity.

Understanding TCP probes helps grasp why HTTP probes add complexity by checking application responses beyond just connectivity.

Network socket programming

TCP probes rely on the basic concept of opening TCP sockets to test connectivity.

Knowing how TCP sockets work at the OS level clarifies why TCP probes are fast and lightweight.

Medical vital signs monitoring

Like checking a patient's pulse to see if the heart is beating, TCP probes check if a service port is open.

This cross-domain link shows how simple signals can indicate basic health but not full wellness.

Common Pitfalls

#1 Setting TCP probe port to a wrong or closed port.

Wrong approach:

livenessProbe:
tcpSocket:
port: 9999
initialDelaySeconds: 5
periodSeconds: 10

Correct approach:

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

Root cause:

Misunderstanding which port the application listens on causes probes to always fail.

#2 Using TCP probe alone for complex applications needing detailed health checks.

Wrong approach:

readinessProbe:
tcpSocket:
port: 8080
initialDelaySeconds: 5
periodSeconds: 5

Correct approach:

readinessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 5
periodSeconds: 5

Root cause:

Assuming TCP connectivity equals full readiness leads to routing traffic to partially broken services.

#3 Setting very short periodSeconds causing probe overload.

Wrong approach:

livenessProbe:
tcpSocket:
port: 8080
initialDelaySeconds: 2
periodSeconds: 1

Correct approach:

livenessProbe:
tcpSocket:
port: 8080
initialDelaySeconds: 10
periodSeconds: 10

Root cause:

Not considering resource impact of frequent probes causes instability and false failures.

Key Takeaways

TCP probes check container health by opening a TCP connection to a specified port without sending data.

They are simple, fast, and useful for non-HTTP services like databases or custom TCP servers.

TCP probes alone do not guarantee full application health; combining with other probes improves reliability.

Proper timing configuration of probes prevents false positives and unnecessary restarts.

Understanding TCP probes helps design better Kubernetes health checks and maintain application stability.