TLS handshake timeout
This error occurs when a secure TLS connection fails to finalize the handshake phase within the default connection timeout window.
Usually happens because:
- ☑ Fragmented network packets are dropped due to CNI MTU size mismatches
- ☑ Control plane API server CPU throttling delays SSL cryptographic handshakes
- ☑ System proxy routes intercept and delay TLS packet exchanges
🔍 Quick Checklist:
What is TLS handshake timeout?
A 'TLS handshake timeout' error is raised by clients or server gateways when the network layer fails to complete the TLS/SSL cryptographic negotiation phase within a set duration. In Kubernetes v1.36 clusters, this typically happens when clients connect to the control plane API server over congested network links, when firewalls intercept and drop TLS packets, or when the API server is heavily loaded, failing to negotiate cipher parameters in time.
Common Causes
- Network packet loss or congestion: High network latency or drop rates prevent the client and API server from exchanging key agreements.
- Overloaded API server control plane: The control plane CPU is throttled, delaying cryptography operations and triggering client-side timeouts.
- MTU size mismatches: Incorrect Maximum Transmission Unit (MTU) sizes in the container network interface (CNI) cause fragmented packets to be silently dropped.
| Cause | Frequency |
|---|---|
| CNI network MTU packet size mismatch (fragmentation drop) | ⭐⭐⭐⭐⭐ |
| API server CPU throttling (crypto negotiation delay) | ⭐⭐⭐⭐ |
| Network proxy or firewall packet inspections delay | ⭐⭐⭐ |
Common Mistakes
- Setting MTU configurations to values larger than the physical host network card supports, triggering silent packet drops during SSL handshakes.
- Neglecting to scale API server resources during high concurrent user activities.
How to Fix
Kubernetes Operations & Verification
Adjust the MTU size inside the CNI (e.g. Calico) configuration to prevent network packet fragmentation drops in Kubernetes v1.36.
apiVersion: projectcalico.org/v3
kind: IPPool
metadata:
name: default-ipv4-ippool
spec:
cidr: 192.168.0.0/16
ipipMode: Always
# Configure MTU size to account for VXLAN/IPIP tunnel encapsulation headers (e.g. 1440 instead of 1500)
blockSize: 26
nodeSelector: all()
---
# Verify config map MTU settings
apiVersion: v1
kind: ConfigMap
metadata:
name: calico-config
namespace: kube-system
data:
veth_mtu: "1440"Platform Specific Fixes
Inspect network interface MTU configurations directly on Linux nodes.
# 1. List active network interfaces and MTU values
ip link show
# 2. Test MTU size restrictions by pinging with don't-fragment flag
ping -M do -s 1472 -c 3 192.168.1.100Best Practices
- Adopt automated MTU detection systems within the cluster CNI configuration.
- Establish load balancers in front of API servers to distribute TLS termination loads.
Frequently Asked Questions (FAQ)
Q: What causes a TLS handshake timeout in Kubernetes?
This means the TCP connection was established, but the client and API server couldn't finalize the secure TLS handshake within the timeout limit (default is often 10 seconds). This is usually caused by network congestion, MTU size mismatches, or an overloaded API server.
Q: How does CNI MTU mismatch cause TLS timeouts?
If your CNI network interface MTU is set larger than the physical network supports (e.g. 1500 on CNI vs 1420 on host VPN tunnel), large TLS packets (which contain key credentials) will be fragmented. If firewalls drop fragmented packets, the handshake hangs and times out.
Q: How do I troubleshoot an overloaded API server?
Check the control plane node's CPU usage. TLS handshakes require high CPU cryptographic operations. If the API server is throttled, it won't negotiate ciphers fast enough, causing client-side TLS timeouts.
Q: How do I bypass proxy-induced TLS handshake timeouts on macOS?
Ensure that local addresses (like ClusterIP ranges or local API endpoints) are added to the 'no_proxy' environment variable to prevent proxy servers from intercepting and delaying the TLS packets.