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.

Practice

1. What is the main purpose of a TCP probe in Kubernetes?

easy

A. To check the container's memory usage

B. To monitor CPU usage of a container

C. To verify the container's file system integrity

D. To check if a container accepts TCP connections on a specified port

Solution

1. Step 1: Understand TCP probe function

   A TCP probe tests if a container is accepting TCP connections on a specific port.

2. Step 2: Compare with other options

   CPU, memory, and file system checks are not done by TCP probes but by other mechanisms.

3. Final Answer:

   To check if a container accepts TCP connections on a specified port -> Option D

4. Quick Check:

   TCP probe = connection check [OK]

Hint: TCP probe checks port connectivity, not resource usage [OK]

Common Mistakes:

• Confusing TCP probe with CPU or memory monitoring
• Thinking TCP probe checks file system health
• Assuming TCP probe checks HTTP endpoints

2. Which of the following is the correct syntax to define a TCP liveness probe in a pod spec?

easy

A. livenessProbe:
tcpSocket:
path: "/health"
initialDelaySeconds: 5
periodSeconds: 10

B. livenessProbe:
httpGet:
port: 8080
initialDelaySeconds: 5
periodSeconds: 10

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

D. livenessProbe:
exec:
command: ["curl", "localhost:8080"]
initialDelaySeconds: 5
periodSeconds: 10

Solution

1. Step 1: Identify TCP probe syntax

   TCP probes use tcpSocket with a port field, no path.

2. Step 2: Check options for correctness

   livenessProbe: tcpSocket: port: 8080 initialDelaySeconds: 5 periodSeconds: 10 uses tcpSocket with port 8080 and timing fields correctly. Others use HTTP or exec or invalid fields.

3. Final Answer:

   livenessProbe with tcpSocket and port field -> Option C

4. Quick Check:

   TCP probe syntax = tcpSocket + port [OK]

Hint: TCP probes use tcpSocket with port, no path [OK]

Common Mistakes:

• Using httpGet or exec instead of tcpSocket for TCP probes
• Adding a path field to tcpSocket (invalid)
• Omitting port number in tcpSocket

3. Given this pod spec snippet, what will happen if the container does not accept TCP connections on port 3306?

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

medium

A. Kubernetes will ignore the failure and keep the container running

B. Kubernetes will restart the container after the probe fails

C. The container will be marked ready immediately

D. The pod will be deleted permanently

Solution

1. Step 1: Understand liveness probe behavior

   Liveness probes check if a container is alive; failure triggers a restart.

2. Step 2: Apply to TCP probe failure

   If TCP connection on port 3306 fails, Kubernetes restarts the container to fix it.

3. Final Answer:

   Kubernetes will restart the container after the probe fails -> Option B

4. Quick Check:

   Liveness probe failure = container restart [OK]

Hint: Liveness probe failure triggers container restart [OK]

Common Mistakes:

• Confusing liveness with readiness probe effects
• Thinking pod is deleted permanently on failure
• Assuming failure is ignored

4. You configured a TCP readiness probe but Kubernetes reports probe failures immediately after pod start. Which is the most likely cause?

medium

A. initialDelaySeconds is missing or too low, so probe runs before container is ready

B. tcpSocket port is set to 0, which is invalid

C. periodSeconds is set too high, causing delayed checks

D. readinessProbe cannot use tcpSocket, only httpGet

Solution

1. Step 1: Analyze probe timing parameters

   Without initialDelaySeconds, probe starts immediately, possibly before container is ready.

2. Step 2: Evaluate other options

   Port 0 is invalid but would cause different errors; periodSeconds affects frequency, not immediate failure; tcpSocket is valid for readiness probes.

3. Final Answer:

   initialDelaySeconds is missing or too low, so probe runs before container is ready -> Option A

4. Quick Check:

   Missing initialDelaySeconds = early probe failure [OK]

Hint: Set initialDelaySeconds to delay probe start [OK]

Common Mistakes:

• Assuming tcpSocket is invalid for readiness probes
• Ignoring initialDelaySeconds importance
• Confusing periodSeconds with initialDelaySeconds

5. You want to configure a TCP readiness probe for a database container on port 5432. The container takes about 20 seconds to start accepting connections. Which configuration is best to avoid false failures?

hard

A. readinessProbe:
tcpSocket:
port: 5432
initialDelaySeconds: 25
periodSeconds: 10
failureThreshold: 3

B. readinessProbe:
tcpSocket:
port: 5432
initialDelaySeconds: 5
periodSeconds: 5
failureThreshold: 1

C. readinessProbe:
tcpSocket:
port: 5432
initialDelaySeconds: 0
periodSeconds: 10
failureThreshold: 5

D. readinessProbe:
tcpSocket:
port: 5432
initialDelaySeconds: 10
periodSeconds: 20
failureThreshold: 1

Solution

1. Step 1: Match initialDelaySeconds to container startup time

   Container needs ~20 seconds to accept connections, so initialDelaySeconds should be at least 20 to avoid early failures.

2. Step 2: Use periodSeconds and failureThreshold to allow retries

   Period of 10 seconds and failureThreshold of 3 means Kubernetes retries for up to 30 seconds before marking not ready, avoiding false negatives.

3. Final Answer:

   readinessProbe with initialDelaySeconds 25, periodSeconds 10, failureThreshold 3 -> Option A

4. Quick Check:

   Delay + retries prevent false failures [OK]

Hint: Set initialDelaySeconds > startup time, use retries [OK]

Common Mistakes:

• Setting initialDelaySeconds too low causing false failures
• Using failureThreshold of 1 with short delays
• Ignoring container startup time in probe config